--- title: "Build a RAG agent with its own scope and policy | Calypso Context" canonical_url: "https://www.calypso.so/context/agents" last_updated: "2026-09-16T00:41:15.086Z" meta: description: "One default agent, any number of named agents. Each binds to its buckets, carries a role, an answer depth, and a presentation mode, and answers as the same model id through the API, MCP, n8n, the widget, and WhatsApp." keywords: "build a RAG agent, hosted RAG agents, custom AI agent on your documents, AI agents with citations, OpenAI compatible RAG agent" "og:description": "One default agent, any number of named agents. Each binds to its buckets, carries a role, an answer depth, and a presentation mode, and answers as the same model id through the API, MCP, n8n, the widget, and WhatsApp." "og:title": "Build a RAG agent with its own scope and policy | Calypso Context" "twitter:description": "One default agent, any number of named agents. Each binds to its buckets, carries a role, an answer depth, and a presentation mode, and answers as the same model id through the API, MCP, n8n, the widget, and WhatsApp." "twitter:title": "Build a RAG agent with its own scope and policy | Calypso Context" --- Calypso home **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. [**Read the agents docs**](https://docs.calypso.so/context/manage/agents) [**Start 14-day free trial**](https://context.calypso.so/join) ## **Searches approved buckets only** An agent is bound to the exact source sets it may use, so retrieval stays scoped and repeatable. ## **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. 1. 01 ### **Build in Agent Builder** Pick the buckets, the role, the answer depth, and the presentation mode. Or POST /v1/agents from a script. 2. 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. 3. 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.](https://www.calypso.so/context/sources) [

**Buckets **

Scoped, durable source memory. Provision by slug, bind to agents.](https://www.calypso.so/context/buckets) [

**Citations **

A source on every answer: annotations by offset, a structured source list, native mode.](https://www.calypso.so/context/citations) [

**Search **

Retrieval without generation: the passages an answer would cite, ranked.](https://www.calypso.so/context/search) [

**Privacy **

Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.](https://www.calypso.so/context/privacy) [

**Agents in the docs **

The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/manage/agents) **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. [**Start 14-day free trial**](https://context.calypso.so/join) [**Read the developer docs**](https://docs.calypso.so/context/manage/agents)