Model IDs and agents

Model IDs

Every Calypso integration addresses an agent by its model ID:

Both are accepted anywhere a model ID is expected — the model field on Responses and Chat Completions, the agent field on Search, the widget, the MCP server, and the n8n node.

GET /v1/models returns the full catalog available to your API key, and GET /v1/rag-agent/models returns just the default agent and its named agents.

Legacy IDs

calypso-rag-agent and calypso-rag-agent:{agent_id} address the same agents and are supported indefinitely — existing integrations need no change.

Responses echo the model ID you sent, so a client pinned to a legacy ID never sees it change:

curl https://api.calypso.so/v1/responses \
  -H "Authorization: Bearer $CALYPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "calypso-rag-agent", "input": "What does our refund policy say?"}'
# -> { "model": "calypso-rag-agent", ... }

Restricted keys match agent IDs across both spellings, so a key whose Allowed models list was saved with either form resolves the same agent.

New integrations should use calypso-agent, which is what GET /v1/models advertises.

Named agent IDs

The agent_id becomes part of the runtime contract, so choose it intentionally. Agents can be created in Agent Builder or programmatically.

When to use the default agent

Use the default agent when:

• the team wants one canonical grounded behavior
• a widget or code path should not depend on a specialized agent
• you want the lowest-maintenance deployment target

When to use named agents

Use named agents when:

• two use cases need different retrieval scope
• role or presentation requirements differ materially
• one integration should stay stable while another is evolving

Important warning

If a named agent is deleted, any client still calling that model ID will break until the agent is recreated or the client is updated.