Skip to main content
An agent is the unit of configuration for a voice conversation. It owns:
  • A name the team uses to identify it.
  • A system prompt that steers the underlying LLM.
  • An organization that scopes who can see and edit it.
  • A creator — the user who first created it.
  • Optional tags for organizing agents.
Agents are mutable: you can rename them, edit the system prompt (via the web UI’s draft flow), tag, archive and duplicate them. Deleting an agent cascades to any conversations that referenced it.

Tags and archiving

Tags are part of the agent’s versioned configuration, so they follow the same draft → publish flow as the prompt or voice. Set them in the draft config and publish:
  • tags replaces the whole tag list (send [] to clear). Tags are trimmed and de-duplicated case-insensitively — "Sales" and " sales " count as one tag. Up to 20 tags of at most 30 characters each.
  • GET /v1/agents lists each agent’s tags from its published config, so a tag shows up in the list only after POST /v1/agents/:agentId/branches/:branchId/publish. Tags are a workspace label only and are not sent to the voice runtime.
Archiving is agent-level and takes effect immediately. PATCH /v1/agents/:id is a partial update:
true archives and false restores. Archiving only hides the agent from the default agents list; its configuration, conversations and widget keep working. GET /v1/agents and GET /v1/agents/:id return it as archived (boolean). Duplicating an agent copies its published config (tags included); the copy always starts active. GET /v1/agents also returns conversations_7d: how many conversations each agent started in the last 7 days.

Lifecycle

Scope rules

All agent endpoints are organization-scoped. The endpoints read the requester’s active organization from the session and only return agents that belong to it. Cross-tenant lookups return 404 agent_not_found — there is no enumeration distinction between “wrong org” and “doesn’t exist.”