Agent Builder
What Agent Builder controls
Agent Builder is where you decide how a RAG agent behaves and which buckets it can search.
The saved policy from Agent Builder is reused across:
- Playground
- MCP and Upload API integrations
- linked-agent widget mode
Default agent and named agents
There is always one default model:
calypso-agent
You can also create named agents:
calypso-agent:{agent_id}
Use the default agent for the stable baseline behavior. Use named agents when you need separate bucket scopes, roles, or response policies for different use cases. API clients discover these agents through the team-scoped model catalog.
List the agent model IDs available to a project API key with:
GET /v1/rag-agent/models
Authorization: Bearer sk-...
The response is scoped to the key's team and includes the default calypso-agent plus named agents such as calypso-agent:support. Use this endpoint from MCP clients, n8n flows, backend services, or direct API callers before choosing the model value for /v1/responses.
What you can configure
The current policy model supports:
- retrieval enabled or disabled
- bucket-backed retrieval scope
- selected buckets for focused source sets
- named agent model ids such as
calypso-agent:support - optional generation model override
top_k- small talk behavior
- whether grounded source titles are returned
- role preset and role brief
- presentation mode
Presentation modes
The app supports response presentation choices such as:
- plain text
- markdown
- markdown with tables
- WhatsApp-safe
- auto
Choose presentation mode for the target surface, not for abstract style preference.
Bucket scope strategy
Buckets are the cleanest way to keep retrieval predictable. An agent should search the buckets that match its job, not every uploaded source by default.
Use a broader bucket scope when:
- the workspace has a small, trusted source set
- the agent handles general support or internal documentation questions
Use a narrower bucket scope when:
- the source pool is still noisy
- the use case is specialized
- you want separation between agents
- the same team has legal, pricing, support, and onboarding knowledge that should not be mixed
Deleting named agents
Deleting a named agent removes its calypso-agent:{agent_id} model id from the workspace, but it does not update every downstream client that may still call that id.
Before deleting a named agent, confirm:
- Playground tests have moved away from it
- widget bindings no longer depend on it
- MCP clients, n8n flows, and direct API callers no longer use that model id