Manage

Agents

Create and address grounded agents: the default agent, named agents with their own bucket scope, and programmatic provisioning.

The agent model

An agent is a saved retrieval + presentation identity. Every workspace has a default agent, and can add named agents that each point at their own buckets and policy:

Model id	What it is
`calypso-agent`	The workspace default agent
`calypso-agent:{agent_id}`	A named agent with its own bucket scope, role, and policy

The model id works identically everywhere: Ask, Search, Playground, MCP, and the widget.

The API returns the canonical spelling shown above. Legacy calypso-rag-agent ids are still accepted on input — see Model IDs and agents.

Discover agents

GET /v1/agents              Canonical Manage discovery: the default agent first, then every named agent with its profile
GET /v1/models              Full model catalog for your key
GET /v1/rag-agent/models    Permanent alias of the discovery surface (answers with `Deprecation` + `Link` headers)

A key for one workspace never exposes another workspace's agents. Reading agents needs no explicit capability grant — any active key for the workspace can list and read them.

Read one agent

GET /v1/agents/{agent_id}

Returns the agent's profile and callable model id; 404 agent_not_found for unknown ids.

Create an agent (API)

POST /v1/agents
Authorization: Bearer sk-...
Content-Type: application/json
Idempotency-Key: provision-support-agent

{
  "agent_id": "support",
  "name": "Support Agent",
  "instructions": "Answer from the support handbook. Be concise.",
  "bucket_slugs": ["support-handbook"],
  "response_policy": "medium"
}

Requires the rag:agent:create capability. The response returns the agent and its callable model id:

{
  "object": "rag_agent",
  "agent_id": "support",
  "model": "calypso-agent:support",
  "replayed": false,
  "profile": { "...": "..." }
}

Authorable fields: agent_id (becomes part of the model id — choose it deliberately), name, instructions, enabled, bucket_ids / bucket_slugs (retrieval scope), file_mode + file_ids / website_ids / qa_ids (legacy non-bucket scope), response_policy (fast | medium | extended default tier), top_k, temperature, seed, max_output_tokens.

Bucket bindings are validated at write time — unknown or archived buckets return bucket_not_found, so an agent can never be created pointing at nothing. Plan caps are enforced (402 agent_limit_reached). POST /v1/rag-agent/agents remains a permanent alias of this route.

Update an agent (API)

Requires the explicit-only rag:agent:update capability:

PUT /v1/agents/{agent_id}

Partial update: send only the fields to change (the authorable fields from create, except agent_id — the path segment is the agent's immutable identity and part of its model id; to rename, create a new agent and delete the old one). An explicit empty bucket_ids: [] clears the bucket bindings; bucket changes are validated exactly like create. 400 no_updates when the body changes nothing, 400 invalid_agent_profile when the merged shape fails validation, 404 agent_not_found for unknown ids.

Delete an agent (API)

Requires the explicit-only rag:agent:delete capability:

DELETE /v1/agents/{agent_id}
Authorization: Bearer sk-...

{ "object": "rag_agent_deleted", "agent_id": "support", "deleted": true, "request_id": "req_..." }

Blast-radius guard: if the team's web widget is bound to this named agent, the call answers 409 delete_blocked with details.bound_surface: "widget". Rebind the widget, or retry with ?force=true to delete anyway (clients calling the deleted model id will fail until it is recreated).
No soft-delete: first call 200, retry 404 agent_not_found.
/v1/agents is the canonical Manage surface — list, create, read, update, and delete all live there. The permanent alias surface is exactly two routes — POST /v1/rag-agent/agents (create) and GET /v1/rag-agent/models (model listing); update and delete have no alias and live only at /v1/agents/{agent_id}. Alias responses advertise the successor via Deprecation: true and Link: </v1/agents>; rel="successor-version" headers, with no sunset date — the alias is not scheduled for removal.

Choosing default vs named

Use the default agent for one canonical grounded behavior with the lowest maintenance. Use named agents when two use cases need different retrieval scope, different roles, or when one integration must stay stable while another evolves.

If a named agent is deleted, any client still calling its model id breaks until the agent is recreated or the client updated. Treat agent_id as part of your API contract.

Next steps

Buckets

Capabilities