Searches approved buckets only
An agent is bound to the exact source sets it may use, so retrieval stays scoped and repeatable.
Elephant · Agents
elephant-agent reads every bucket you have. A named agent gets its own buckets, instructions, answer depth and presentation: a study coach that reads only your course, a research assistant that reads only your papers. The same id answers in ChatGPT, Claude, the API, n8n and the web widget. Build it in Agent Builder, test it in Playground, use it.
An agent is bound to the exact source sets it may use, so retrieval stays scoped and repeatable.
Retrieval scope, top_k, answer depth, role, source visibility, and presentation live on the agent, not in each call.
Every answer carries the sources it drew on, so users verify instead of trusting a black box.
The example
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.
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": "elephant-agent:support", "replayed": false, … }Named agents
Each assistant reads its own buckets and follows its own instructions, and the model id says which one answered.
elephant-agent:study
Buckets
biology-101, exam-notes
Brief
Quiz me and summarise from my course material only, citing the page.
elephant-agent:research
Buckets
papers, reading-notes
Brief
Answer from my collected papers and quote the passage behind every claim.
elephant-agent:home
Buckets
home-and-contracts, manuals
Brief
Answer questions about my lease, insurance and appliances from the documents themselves.
Policy
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
Pick the buckets, the role, the answer depth, and the presentation mode. Or POST /v1/agents from a script.
Ask real questions against your real buckets with a real project API key, and read the grounding state before you rely on it.
Use elephant-agent:{agent_id} in ChatGPT, Claude, the API, n8n or the widget. One id, one set of instructions, one set of citations.
Playground
The important interpretation work in Playground is how grounding surfaced. Four states tell you whether the answer can be trusted.
From the docs
| Default agent | elephant-agent |
|---|---|
| Named agent | elephant-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 |
Questions and answers
Keep reading
PDFs, screenshots, pages and notes. What it reads and how you save it.
Folders your AI remembers. Ask one, or all of them.
A source on every answer: file, page and passage, with a link to open it.
The exact passage, ranked, without a written answer.
Private by default: no training on your files, never deletes, you choose what each AI may do.
The reference this page is written from, with every endpoint and field.
Start today
Pick its buckets, write its instructions once, and call it by name from ChatGPT, Claude or your own app.