Reference

Policy behavior

Understand which Calypso RAG policy fields change retrieval behavior, which fields affect presentation, and how those choices show up across Playground, Code, and the widget.

Why policy semantics matter

In Calypso RAG, the visible model ID is only part of the story. The saved policy behind that model determines what the agent can search and how it responds.

Core policy ideas

Retrieval scope

Source scope determines which materials the agent is allowed to search before answering.

Role

Role shapes tone and answer posture. It does not act as a source-selection mechanism on its own.

Answer depth

The response tier selects how much work the agent does before answering, and which model writes the answer.

Source visibility

Whether sources are returned changes citation visibility, not whether retrieval happened at all.

Practical field interpretation

This scopes the agent to one or more knowledge buckets, and it takes precedence over every other source field. When bucket_ids is set, Calypso forces file_mode to selected and clears file_ids, website_ids, and qa_ids — bucket scope replaces individually selected sources rather than adding to them.

Bucket scope searches the bucket's own index, which holds files and web pages (pages sync into bucket stores as indexed text). Q&A entries are the remaining exception: a Q&A member is not retrievable through bucket scope — keep Q&A sources on a non-bucket policy.

`file_mode`

This decides whether the agent searches all retrievable file-backed content or only selected sources. It is ignored when bucket_ids is set.

Files uploaded through the public upload APIs always carry a bucket destination and are indexed into that bucket, so they are retrieved through bucket scope — and only once indexing completes and the file's bucket sync is active for that bucket. If an uploaded file is never found, check two causes: the policy uses file_mode or explicit ids and does not include the bucket the file was ingested into, or the file's bucket sync has not reached active (poll GET /v1/sources/{id} and check ready — or bucket_sync_status for the detailed ladder).

`file_ids`, `website_ids`, `qa_ids`

These narrow the included source pool when selected scope is being used, and are cleared when bucket_ids is set.

`top_k`

This sets how many passages the agent's final retrieval call returns, clamped to 1–20. It is honored on every answer the agent produces, so raising it widens the evidence the model sees (and the tokens it costs) while lowering it tightens the answer onto the strongest matches. Left unset, the agent uses the platform default of 10. Internal context sub-searches keep their own fixed depth and are unaffected.

`smalltalk_enabled`

This decides whether lightweight greetings and pleasantries can be answered more freely or should be forced through grounded behavior.

`return_sources`

This controls whether grounded source titles are surfaced in the final response.

Response tier

Requests choose an answer depth per call through the OpenAI-standard effort field (reasoning.effort on Responses, reasoning_effort on Chat Completions). Allowed values are minimal, low, medium, and high: minimal/low map to the Fast tier, medium to Medium, high to Extended. Higher tiers use a stronger answer model. When a request does not specify one, Calypso uses the agent's saved default tier, falling back to Fast. The canonical mapping table lives in the API overview.

`presentation_mode`

This helps the same grounded answer fit different delivery surfaces. It currently shapes web widget replies; calypso-agent and named agents return the model's own markdown, so treat presentation mode as a widget setting rather than an API-surface one.

Best practice

Change one important policy dimension at a time, then validate in Playground before moving on to an integration surface.

Model IDs and agents

Troubleshooting