application public active Verified 2026-04-29

Agent

Agent and automation workspace for threads, workflows, approvals, and operator execution.

Documentation Map

What It Is

Agent and automation workspace for threads, workflows, approvals, and operator execution.

Canonical documentation for Topolo Agent lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Local product and operational docs have been retired in favor of the docs application.

Run the one narrow smoke check that verifies workspace bootstrap and thread creation behavior:

Architecture

Owners: ai-platform

Source repos: PlatformApplications/TopoloAgent

Dependencies: topolo-auth, applications-packages, topolo-developers, topolo-p2p

Repo shape

  • PlatformApplications/TopoloAgent/README.md
  • PlatformApplications/TopoloAgent/app/
  • PlatformApplications/TopoloAgent/docs/
  • PlatformApplications/TopoloAgent/infra/
  • PlatformApplications/TopoloAgent/migration.config.ts
  • PlatformApplications/TopoloAgent/package-lock.json
  • PlatformApplications/TopoloAgent/package.json
  • PlatformApplications/TopoloAgent/packages/
  • PlatformApplications/TopoloAgent/scripts/
  • PlatformApplications/TopoloAgent/topolo.cloudcontrol.json

Runtime Surfaces

Hosts:

https://agent.topolo.app https://topolo-agent.pages.dev https://topolo-agent-staging.pages.dev https://topolo-agent-stg.topolo-staging.workers.dev
topolo-agent

Config: PlatformApplications/TopoloAgent/app/wrangler.toml

Main: not declared

Routes: workers.dev or asset-only surface

topolo-agent-worker

Config: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

Main: index.ts

Routes: workers.dev or asset-only surface

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/agent.mdx

Source exists in repo: yes

Canonical Agent coverage now lives in the docs application. The backend worker now requires Topolo Auth validation for operator bearer tokens and no longer carries an Agent-local HS256/JWT secret verification path. The production Pages `/login` entry renders the shared branded first-party login surface from the `svc_topolo_agent` UI Kit registry entry and submits email/password credentials to Auth through the shared client; OAuth and other brokered flows still use hosted Auth. The connector catalog uses the Developers-owned mobile app catalog connector for Android and iOS artifact metadata. Agent exposes `GET /api/widget` for TopoloOne live workspace with active-flow, pending-task, pending-approval, and run-today stats. Cross-organization agent actions must enter through TopoloP2P and wait for the P2P policy decision before execution. Staging runs in the separate Topolo Staging Cloudflare account with staging Auth, Nexus, D1, R2, Queue, and Vectorize bindings.

App API page: /reference/apps/topolo-agent

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

svc_topolo_agent

API key scopes

approvals.write

Approve or reject gated Agent actions

Resource pattern: none

reports.read

View reports, artifacts, and work feed output

Resource pattern: none

workflows.read

View workflow plans and runs

Resource pattern: none

workflows.write

Create and run workflow plans

Resource pattern: none

workspace.read

View the Agent operating workspace

Resource pattern: none

workspace.write

Update workspace state and org memory

Resource pattern: none

Service permissions

approvals:write, reports:read, workflows:read, workflows:write, workspace:read, workspace:write

Data Ownership

d1

Binding: AGENT_DB

Target: 00000000-0000-0000-0000-000000000000

Environment: default

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

r2

Binding: AGENT_LOGS

Target: topolo-agent-logs-local

Environment: default

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

vectorize

Binding: KNOWLEDGE_VECTOR

Target: topolo-agent-knowledge-local

Environment: default

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

d1

Binding: AGENT_DB

Target: 46570203-40bb-4a66-b1f4-66ec89abb486

Environment: stg

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

r2

Binding: AGENT_LOGS

Target: topolo-agent-logs-staging

Environment: stg

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

vectorize

Binding: KNOWLEDGE_VECTOR

Target: topolo-agent-knowledge-staging

Environment: stg

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

d1

Binding: AGENT_DB

Target: 4b536b30-6fc6-430f-99c8-1c80575833bb

Environment: prod

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

r2

Binding: AGENT_LOGS

Target: topolo-agent-logs-production

Environment: prod

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

vectorize

Binding: KNOWLEDGE_VECTOR

Target: topolo-agent-knowledge-production

Environment: prod

Source: PlatformApplications/TopoloAgent/packages/backend/wrangler.toml

Queues / Cron / Workflows

Queue bindings:

  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-local
  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-staging (stg)
  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-production (prod)

Cron triggers

No cron triggers were detected.

Workflow signals

  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-local
  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-staging
  • AGENT_WORKFLOW_QUEUE -> topolo-agent-workflow-runs-production

Environment Variables and Bindings

Environment variables:

CLOUDFLARE_ACCOUNT_ID ENVIRONMENT NEXUS_GATEWAY_URL NODE_ENV SERVICE_ID TOPOLO_AUTH_URL account_id

All wrangler bindings

  • AGENT_DB (d1) -> 00000000-0000-0000-0000-000000000000
  • AGENT_LOGS (r2) -> topolo-agent-logs-local
  • KNOWLEDGE_VECTOR (vectorize) -> topolo-agent-knowledge-local
  • AGENT_WORKFLOW_QUEUE (queue) -> topolo-agent-workflow-runs-local
  • AGENT_DB (d1) -> 46570203-40bb-4a66-b1f4-66ec89abb486 [stg]
  • AGENT_LOGS (r2) -> topolo-agent-logs-staging [stg]
  • KNOWLEDGE_VECTOR (vectorize) -> topolo-agent-knowledge-staging [stg]
  • AGENT_WORKFLOW_QUEUE (queue) -> topolo-agent-workflow-runs-staging [stg]
  • AGENT_DB (d1) -> 4b536b30-6fc6-430f-99c8-1c80575833bb [prod]
  • AGENT_LOGS (r2) -> topolo-agent-logs-production [prod]
  • KNOWLEDGE_VECTOR (vectorize) -> topolo-agent-knowledge-production [prod]
  • AGENT_WORKFLOW_QUEUE (queue) -> topolo-agent-workflow-runs-production [prod]

Deployments

Deployment environments: stg, prod

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Wrangler surfaces

  • PlatformApplications/TopoloAgent/app/wrangler.toml -> topolo-agent
  • PlatformApplications/TopoloAgent/packages/backend/wrangler.toml -> topolo-agent-worker

Build and deploy commands

  • build — PlatformApplications/TopoloAgent/app/package.json :: vite build
  • preview — PlatformApplications/TopoloAgent/app/package.json :: vite preview
  • build — PlatformApplications/TopoloAgent/package.json :: npm run build --workspace=packages/backend
  • build:app — PlatformApplications/TopoloAgent/package.json :: npm run build --workspace=app
  • build:all — PlatformApplications/TopoloAgent/package.json :: npm run build && npm run build:app
  • deploy:web — PlatformApplications/TopoloAgent/package.json :: npm run build:app && CLOUDFLARE_ACCOUNT_ID=49ef1ba682ad8cfd720c86699ae17521 npx wrangler pages deploy app/dist --project-name=topolo-agent --branch=production
  • deploy:stg — PlatformApplications/TopoloAgent/package.json :: npm run deploy:stg --workspace=packages/backend
  • deploy:staging — PlatformApplications/TopoloAgent/package.json :: npm run deploy:stg && npm run deploy:web:staging
  • deploy:prod — PlatformApplications/TopoloAgent/package.json :: npm run deploy:prod --workspace=packages/backend
  • deploy:production — PlatformApplications/TopoloAgent/package.json :: npm run deploy:prod
  • build:app:staging — PlatformApplications/TopoloAgent/package.json :: VITE_API_URL=https://topolo-agent-stg.topolo-staging.workers.dev VITE_AUTH_URL=https://auth.stg.topolo.us VITE_SERVICE_ID=svc_topolo_agent VITE_CURRENT_APP_URL=https://topolo-agent-staging.pages.dev VITE_BUGFIX_API_URL=https://bugfix.stg.topolo.us npm run build --workspace=app
  • deploy:web:staging — PlatformApplications/TopoloAgent/package.json :: npm run build:app:staging && CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac npx wrangler@4 pages deploy app/dist --project-name=topolo-agent-staging --branch=main
  • build — PlatformApplications/TopoloAgent/packages/backend/package.json :: tsc --noEmit
  • deploy:stg — PlatformApplications/TopoloAgent/packages/backend/package.json :: wrangler deploy --env stg
  • deploy:prod — PlatformApplications/TopoloAgent/packages/backend/package.json :: wrangler deploy --env prod

Failure Modes

No default failure-mode heuristics are currently flagged for this system.

Debugging Runbooks

Start with these entrypoints:

  • PlatformApplications/TopoloAgent/app/wrangler.toml
  • PlatformApplications/TopoloAgent/packages/backend/wrangler.toml
  • PlatformApplications/TopoloDocs/src/content/public/applications/agent.mdx
  • PlatformApplications/TopoloAgent/README.md
  • PlatformApplications/TopoloAgent/app/package.json
  • PlatformApplications/TopoloAgent/package.json
  • PlatformApplications/TopoloAgent/packages/backend/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-29

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.