Calypso Calypso

Elephant · Agents

One assistant per job. One memory.

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.

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": "elephant-agent:support", "replayed": false, … }

Named agents

Three jobs, three assistants, one memory.

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

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.

FieldChangesEffect
bucket_idsRetrievalWhich sources may be searched. Takes precedence over every other source field.
top_kRetrievalHow many passages the final retrieval returns, 1 to 20, default 10. Wider evidence costs more tokens.
response_policyRetrieval and modelFast, medium, or extended: how much work happens before answering and which model writes it.
rolePresentationTone and answer posture. Not a source-selection mechanism.
source visibilityPresentationWhether grounded source titles are returned. Retrieval happens either way.
presentation modePresentationPlain 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 your real buckets with a real project API key, and read the grounding state before you rely on it.

  3. 03

    Ship the model id

    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

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 agentelephant-agent
Named agentelephant-agent:{agent_id}
DiscoverGET /v1/agents · GET /v1/models
ManagePOST /v1/agents · PUT /v1/agents/{agent_id} · DELETE /v1/agents/{agent_id}
top_k1 to 20 passages per answer, default 10
Response modesfast, medium, extended
Presentation modesplain text, markdown, markdown with tables, WhatsApp-safe, auto

Questions and answers

Before you create one.

Keep reading

Start today

Give every job its own assistant.

Pick its buckets, write its instructions once, and call it by name from ChatGPT, Claude or your own app.