- 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.
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:tagsreplaces 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/agentslists each agent’s tags from its published config, so a tag shows up in the list only afterPOST /v1/agents/:agentId/branches/:branchId/publish. Tags are a workspace label only and are not sent to the voice runtime.
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 return404 agent_not_found — there is no enumeration distinction between “wrong org” and “doesn’t exist.”
Related guides
- Conversations — start a preview call against an agent.
- Workspaces — set which organization is active.