Agent Bucket Uploads

Use agent-facing file uploads when an uploaded file should support a RAG agent conversation while still being routed through a required knowledge bucket.

What Agent Bucket Uploads Are

Agent bucket uploads are file uploads made for an immediate calypso-rag-agent workflow, but they still land in a durable knowledge bucket.

Use this path when the file should support a near-term agent conversation and return an OpenAI-style file_id. Do not use it as the main path for durable content pipelines. For reusable knowledge ingestion, use the Single-file Upload API, Batch Upload API, or MCP Server durable knowledge tools.

Why The Upload Is Bucket-Driven

Calypso routes agent file uploads through buckets so the file uses the same retrieval and indexing path as the rest of the agent's knowledge.

That gives the upload:

a clear destination bucket
indexing and RAG readiness metadata
compatibility with fileIds on calypso-rag-agent
the same team-scoped model and bucket rules used by named RAG variants

MCP Tool

In MCP clients, use:

calypso-upload-agent-file

The tool uploads through the agent-facing file API and returns an OpenAI-style file_id.

Required routing:

targetModel: the RAG model variant that should use the file, such as calypso-rag-agent:legal.
bucketId: required when the selected model has multiple active buckets.

If the selected model has exactly one active bucket, the MCP server can auto-select it. If the model has no active buckets, bind the agent variant to a bucket before uploading.

Example

{
  "filename": "contract.pdf",
  "mimeType": "application/pdf",
  "filePath": "/Users/me/Desktop/contract.pdf",
  "targetModel": "calypso-rag-agent:legal",
  "bucketId": "bucket_abc123",
  "waitForReady": true
}

Then pass the returned id to the agent:

{
  "model": "calypso-rag-agent:legal",
  "prompt": "Summarize the termination terms in the uploaded contract.",
  "fileIds": ["file_abc123"]
}

Bucket Selection Rules

Model bucket state	Upload behavior
One active bucket	The MCP server can auto-select the bucket.
Multiple active buckets	Pass `bucketId` explicitly.
No active buckets	Upload is blocked until the agent variant is connected to a bucket.

Read calypso://rag-agent-models in the MCP client to inspect the selected model's active buckets.

When To Use This Path

Use agent bucket uploads for:

a temporary contract, report, or screenshot used in one conversation
a user-driven analysis flow where the client expects an OpenAI-compatible file_id
a file that should be query-ready before the next prompt

Use durable knowledge uploads instead when:

the source should become part of a governed bucket
a job is syncing many files
you need batch status, dry runs, or stable ingestion records

Readiness

If the next prompt depends on the uploaded file, wait for RAG readiness before asking the agent.

In MCP, set:

{
  "waitForReady": true
}

Batch Upload API

MCP Server