Searches approved buckets only
An agent is bound to the exact source sets it may use, so retrieval stays scoped and repeatable.
Calypso Context · Agents
One runtime, specialized behaviour.
calypso-agent is your workspace default. A named agent gets its own bucket scope, role, answer depth, and presentation mode, and the same model id answers through the API, MCP, n8n, the web widget, and Calypso WhatsApp. Build it in Agent Builder, test it in Playground, ship it.
Policy defined once
Retrieval scope, top_k, answer depth, role, source visibility, and presentation live on the agent, not in each call.
Citations by default
Every answer carries the sources it drew on, so users verify instead of trusting a black box.
The example
Create it once. Call it like a model.
Provision a named agent with an idempotency key, then address it by model id from any OpenAI SDK. Discovery lists what your key can use.
CALYPSO_API_KEY
curl -X POST "https://api.calypso.so/v1/agents" \
-H "Authorization: Bearer $CALYPSO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: provision-support-agent" \
-d '{
"agent_id": "support",
"name": "Support Agent",
"instructions": "Answer from the support handbook. Be concise.",
"bucket_slugs": ["support-handbook"],
"response_policy": "medium"
}'
# { "object": "rag_agent", "agent_id": "support",
# "model": "calypso-agent:support", "replayed": false, … }Named agents
Three jobs, three agents, one runtime.
Each agent reads its own buckets and follows its own brief. The team that runs them never mixes them up, because the model id says which one answered.
calypso-agent:support
Buckets
support-handbook
Brief
Answer troubleshooting questions from approved support sources, with citations.
calypso-agent:pricing
Buckets
pricing, legal
Brief
Explain plans, limits, packaging, and procurement rules from approved sources only.
calypso-agent:onboarding
Buckets
onboarding, support-handbook
Brief
Guide setup and implementation from curated onboarding knowledge.
Policy
What changes retrieval, and what only changes presentation.
The visible model id is only part of the story. These fields decide what the agent searches and how it speaks. Change one at a time and validate in Playground.
| Field | Changes | Effect |
|---|---|---|
| bucket_ids | Retrieval | Which sources may be searched. Takes precedence over every other source field. |
| top_k | Retrieval | How many passages the final retrieval returns, 1 to 20, default 10. Wider evidence costs more tokens. |
| response_policy | Retrieval and model | Fast, medium, or extended: how much work happens before answering and which model writes it. |
| role | Presentation | Tone and answer posture. Not a source-selection mechanism. |
| source visibility | Presentation | Whether grounded source titles are returned. Retrieval happens either way. |
| presentation mode | Presentation | Plain text, markdown, markdown with tables, WhatsApp-safe, or auto. Choose for the surface. |
How it works
Build, test, ship.
- 01
Build in Agent Builder
Pick the buckets, the role, the answer depth, and the presentation mode. Or POST /v1/agents from a script.
- 02
Test in Playground
Ask real questions against real buckets with a real project API key, and read the grounding state before anything reaches a customer.
- 03
Ship the model id
Use calypso-agent: on the API, MCP, n8n, the widget, or a Smart Board. One id, one policy, one set of citations.
Playground
Read the grounding state, not just the reply.
The important interpretation work in Playground is how grounding surfaced. Four states tell you whether the answer can be trusted.
- Available
- Grounded sources were returned and can be inspected directly.
- Hidden
- Grounding likely happened, but source titles are intentionally hidden by policy.
- Missing
- Grounding was expected but did not surface cleanly. Check the key, the named agent, and bucket readiness.
- None
- No grounded sources were returned. The answer is not evidence-backed.
From the docs
Model ids, endpoints, and limits.
| Default agent | calypso-agent |
|---|---|
| Named agent | calypso-agent:{agent_id} |
| Discover | GET /v1/agents · GET /v1/models |
| Manage | POST /v1/agents · PUT /v1/agents/{agent_id} · DELETE /v1/agents/{agent_id} |
| top_k | 1 to 20 passages per answer, default 10 |
| Response modes | fast, medium, extended |
| Presentation modes | plain text, markdown, markdown with tables, WhatsApp-safe, auto |
| Legacy ids | calypso-rag-agent ids are still accepted on input; the API returns the canonical calypso-agent spelling |
Questions and answers
Before you create one.
Keep reading
Sources
PDFs, images, pages, and data. What it reads and how it gets in.
Buckets
Scoped, durable source memory. Provision by slug, bind to agents.
Citations
A source on every answer: annotations by offset, a structured source list, native mode.
Search
Retrieval without generation: the passages an answer would cite, ranked.
Privacy
Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.
Agents in the docs
The reference this page is written from, with every endpoint and field.
Start today
Create the agent layer your product can trust.
Bind buckets, set the policy once, and launch cited answers on every surface with one model id.