TRtraversal
workers

Deploy Worker

Changed on

Explicitly deploy a worker.

The body is discriminated on platform: a Slack deploy names the channel to bind to, a Teams deploy names the channel plus a display-name override, and a web deploy names the worker instead, because web mints its own handle and has no channel to pick. Slack is the default variant, so a body written before platform existed still parses.

State-changing, so it goes through the standard AuthorizedUserDep chain (authenticated + CSRF-validated). The organization comes from the authenticated user, never the request body, so a caller cannot deploy into another org's channel — and the deploying identity likewise comes from the session, so the announcement can't be attributed to someone else.

post/workers

Request

  • Base URL
    https://api.traversal.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.traversal.com/workers
  • Auth
    none declared

Request body

OR
OR

Response

Successful Response

idstring required
organization_idstring required
resource_idstring required
display_namestring required
platform'slack' | 'teams' | 'web' required

A supported chat platform.

Values align with integration_instances.type so a chat install's platform and its integration row stay in lockstep.

channel_urlstring nullable required
agent_typestring required
mode'incident' | 'alerts' | 'custom' required

The kind of channel the agent lives in — its standing mission.

Drives the swappable mode block in the system prompt (and, later, the toolset). escalation and others land as localized drop-ins (their standing block + tooling) when that work begins.

incident and alerts each state a mission the worker owns whatever the operator writes. custom states none: it supplies only the conduct floor the identity block forward-references, and the operator's custom_instruction is what gives the worker something to do. A channel that is neither working an incident nor triaging alert fires gets this one rather than being told it is in an incident (PRD-3766). The value is what customer-facing surfaces render, so it reads as the operator's own word for it rather than as an internal category.

A member's name is persisted, in resident_agent_workflow.mode and resident_agent_template.mode — plain varchars with no DB-side value set — and read back through this enum, so adding a member is one deploy but removing or renaming one orphans every row holding it. It also makes a member forward-only: code that predates it raises on a row that carries it, rather than degrading. So a new member wants its read deployed everywhere before anything can write it — either landing the member ahead of the paths that create it, or gating creation while it rolls out.

The same names are stored in usage policy bodies. Renaming or removing a member stops a body naming it from parsing, and that disables the template's policies.

custom_instructionstring nullable
created_atstring date-time required
updated_atstring date-time required
stopped_atstring date-time nullable required
status'critical' | 'attention' | 'working' | 'stable' required

The worker's present-tense status top-line, shown as a pill on the /workers list. Only these agent-picked values are ever stored in the status column; a null column means none has been emitted yet (the UI renders that as starting), and the terminal stopped state is derived from stopped_at — neither is stored here, so there is no second source of truth.

The agent-facing definitions live on the status field in prompts.py (the only copy the model reads); keep this summary in sync with it.

Values: CRITICAL: Immediate coordinated response is warranted because user-facing impact is severe or escalating. ATTENTION: A specific person or team should act now, but immediate coordinated incident response is not warranted. STABLE: Resting floor — no specific person or team needs to act now and no coordinated incident response is warranted. WORKING: Legacy — no longer emittable, see EmittableWorkerStatus.

status_messagestring nullable required
status_updated_atstring date-time nullable required

Changes