Topolo Agent

Public overview of the Cloudflare-first agent and automation platform in the Topolo portfolio.

publicverified 2026-07-29agentsautomationworkflows

What It Is

Topolo Agent is the platform surface for agent execution, workflow orchestration, approvals, inbox work, workspace-linked automation, and standalone reusable person profiles. Agent also owns reusable public assistant surfaces such as Lois on the TopoloOne marketing site, so public chat behavior, persona selection, source links, and safety policy are managed in one place rather than duplicated across websites.

Architecture

The system combines a Cloudflare-backed backend with a browser application and shared packages, using Topolo Auth for login and request validation. Its connector catalog now references the Developers-owned mobile app catalog for installable Android and iOS app metadata instead of a standalone app-library service. Agent-owned person profiles capture source-backed writing style, speaking style, persona rules, usage policy, preview drafts, and optional Voice profile links without automatically creating an autonomous AI worker. The profile manager is a standalone Agent surface and does not depend on Director workflows or workspace-summary hydration.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

See /systems/topolo-agent for the current repo and deployment inventory.

API Reference

The current contract is curated rather than OpenAPI-backed in the docs platform. Use /systems/topolo-agent and the internal handbook for the active route families and workspace surface. Public website chat integrations call the same Agent-backed public assistant route through their owning site's same-origin proxy. Authenticated products can use /api/person-profiles to manage org-scoped profiles, profile sources, style snapshots, and draft previews for downstream script, social, email, chat, and narration generation. The subject user can manage their own likeness profile. Organization owners, admins, and super admins can manage profiles for company use. Normal users cannot manage another human user's likeness profile.

Auth and Permissions

Topolo Agent relies on Topolo Auth for frontend login and backend validation. Workflow, thread, and workspace operations are scoped by the authenticated user and org context. The browser app now uses the shared Topolo browser auth client contract with cookie-backed refresh, callback-code redemption on auth.topolo.app, and app identity resolved from the topolo-agent Auth service slug at runtime. Browser SSO callbacks delegate Auth /sso/exchange handling to the shared client, so callback URLs carry one-time sso_code values rather than bearer tokens. The backend worker validates operator bearer tokens through Topolo Auth and does not retain an Agent-local JWT secret verification path.

Data Ownership

Topolo Agent owns threads, workflow state, inbox items, approvals, reports, monitors, workspace-linked execution state, and source-backed person-profile metadata. Topolo Voice owns actual synthetic voice assets, provider voice IDs, and future voice outreach or inbound call-center voice runtime data. Topolo Auth owns the user identity, organization role, and admin boundary used to authorize company use of a human likeness.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /agents, its offline policy is read_through_cache, and it requires organization context.

Published permissions: agents:read, workflows:read, reports:read, workspace:read.

  • /agents uses /api/agents with the record.list template and agent.agents.list data source.
  • /agents/:id uses /api/agents/:id with the record.detail template and agent.agents.detail data source.
  • /workflows uses /api/workflows with the record.list template and agent.workflows.list data source.
  • /workflows/:id uses /api/workflows/:id with the record.detail template and agent.workflows.detail data source.
  • /approvals uses /api/approvals with the record.list template and agent.approvals.list data source.
  • /approvals/:id uses /api/approvals/:id with the record.detail template and agent.approvals.detail data source.
  • /threads uses /api/threads with the record.list template and agent.threads.list data source.
  • /threads/:id uses /api/threads/:id with the record.detail template and agent.threads.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Agent deploys as a Cloudflare-first application with separate frontend and backend surfaces.

Failure Modes

  • workspace or workflow state drifts between frontend and backend
  • auth service registration is missing or incorrect
  • agent route contracts change without corresponding docs updates
  • a normal user can access another user's likeness profile
  • a product treats a person profile as an autonomous agent without an Auth-linked agent_employee principal and accountable human owner

Debugging

Start with /systems/topolo-agent, then verify the backend route family and the frontend auth configuration for the failing flow.

Use It

Open Agent for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-agent --json
topolo actions --service topolo-agent --json
topolo actions capabilities --service topolo-agent --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Agent and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Verified the native_capability mobile experience contract and its 8 published route(s) against apps/TopoloAgent origin/staging 5e3fc3d2655a on 2026-07-27.

  • Reconciled this page against apps/TopoloAgent origin/staging 357e53364399 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloAgent commits through 0707d82; reviewed 383 commits since 2026-05-14, including 0707d82 chore(deps): refresh @topolo-io/app-shell pins; d77a50e Stop blocking startup on i18n readiness; db345b8 Fix Agent thread detail header state; 73b7912 Fix Agent navigation error and thread rail UX.

  • Removed hardcoded concrete app IDs from Agent runtime on 2026-05-13 so browser auth, backend validation, widgets, seed checks, and connector calls resolve service slugs through Auth.

  • Added standalone person-profile UI and preview-route coverage on 2026-05-08 so Agent can manage and test writing/speaking likeness profiles without requiring another app workflow.

  • Corrected person-profile authorization on 2026-05-07 so own-likeness and company-admin use are governed by Agent/Auth rather than a separate Consent-style service.

  • Added public person-profile coverage on 2026-05-07 so Agent is documented as the owner of reusable writing/speaking profile metadata without collapsing it into an autonomous agent.

  • Moved the Agent mobile app catalog connector to the Developers-owned catalog on 2026-04-22.

  • Removed the Agent backend local HS256/JWT secret verification path on 2026-04-18

  • Delegated Agent browser callback-code redemption to the shared Topolo Auth client on 2026-04-18.

  • Promoted Agent browser SSO callbacks to Auth /sso/exchange on 2026-04-17 so callback URLs require a one-time sso_code instead of bearer tokens

  • Standardized the Topolo Agent browser auth layer on the shared Topolo browser auth client on 2026-03-31

  • Standardized the public product label to Agent, aligned the frontend launcher/catalog source with Auth-managed metadata, and recorded the frontend Worker target in CloudControl on 2026-04-04

  • Added canonical Topolo Agent coverage and retired repo-local product docs on 2026-03-30