---
title: "Build a custom AI assistant over your own files | Calypso"
canonical_url: "https://www.calypso.so/elephant/agents"
last_updated: 2026-11-21
meta:
  description: "Create named assistants that read only the buckets you choose, with their own instructions and answer style, and call them from ChatGPT, Claude or the API."
  keywords: "custom AI assistant on your documents, AI study assistant for notes, AI research assistant for papers, build a RAG agent, OpenAI compatible RAG agent"
  "og:description": "Create named assistants that read only the buckets you choose, with their own instructions and answer style, and call them from ChatGPT, Claude or the API."
  "og:title": "Build a custom AI assistant over your own files | Calypso"
  "twitter:description": "Create named assistants that read only the buckets you choose, with their own instructions and answer style, and call them from ChatGPT, Claude or the API."
  "twitter:title": "Build a custom AI assistant over your own files | Calypso"
---

Connect your AI

**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.

[**Read the agents docs**](https://docs.calypso.so/context/manage/agents) [**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant)

## **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.

| 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 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.

<dl>

<dt>**Available**</dt>
<dd>Grounded sources were returned and can be inspected directly.</dd>

<dt>**Hidden**</dt>
<dd>Grounding likely happened, but source titles are intentionally hidden by policy.</dd>

<dt>**Missing**</dt>
<dd>Grounding was expected but did not surface cleanly. Check the key, the named agent, and bucket readiness.</dd>

<dt>**None**</dt>
<dd>No grounded sources were returned. The answer is not evidence-backed.</dd></dl>

**From the docs**

## Model ids, endpoints, and limits.

| **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**

## Before you create one.

**Keep reading**

[<h3>**Sources **</h3>PDFs, screenshots, pages and notes. What it reads and how you save it.](https://www.calypso.so/elephant/sources) [<h3>**Buckets **</h3>Folders your AI remembers. Ask one, or all of them.](https://www.calypso.so/elephant/buckets) [<h3>**Citations **</h3>A source on every answer: file, page and passage, with a link to open it.](https://www.calypso.so/elephant/citations) [<h3>**Search **</h3>The exact passage, ranked, without a written answer.](https://www.calypso.so/elephant/search) [<h3>**Privacy **</h3>Private by default: no training on your files, never deletes, you choose what each AI may do.](https://www.calypso.so/elephant/privacy) [<h3>**Agents in the docs **</h3>The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/manage/agents)

**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.

[**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant) [**Read the docs**](https://docs.calypso.so/context/manage/agents)