Interface OpenAiChatOptions

Global context passed to the agent and all AI functions of the agent.

The model to use when model cannot serve the conversation's very first request because its provider is unavailable — a rate limit, a capacity outage, or any other failure on the provider's side. A request that fails for its own reasons (an invalid prompt, a rejected schema, an exhausted Squid quota) is never retried on the backup, nor is any request after the first one, nor one that already produced output or ran a tool.

A conversation that fell back then STAYS on that backup for the rest of its life, so an outage costs the primary's retry budget once rather than once per turn, and the model does not change mid-dialogue. The pin outlives the option that created it: changing or removing backupModel, changing the agent's own model, and the primary recovering all leave a pinned conversation where it is, and a pinned model that no longer resolves fails the request rather than moving the conversation. This is deliberate — a conversation accumulates provider-native file ids and a transcript in that provider's dialect, none of which survive a move. Pinning needs Squid-managed memory to have somewhere to record it; without memory every request is a first request anyway.

A request carrying fileIds follows from the same reasoning, and the two cases differ. A first request does not fall back where that would cost it the attachments — to a model that cannot read ids the primary could, or that reads them without owning them — since answering from a model that never saw them is worse than reporting the outage. Where neither model reads file ids they are inert either way and the fallback proceeds. A conversation already pinned is held to less: it keeps running on its model, and if that model reads no file ids the ids are ignored there as they are anywhere else, because the alternative is a conversation that can never run again.

Pass a model name for the model's own defaults, or a BackupModelOptions object to give the backup its own sampling settings. Everything else — instructions, functions, knowledge bases, connected agents, response format, memory — always comes from the primary configuration.

On a turn the backup serves, the sampling settings are ITS settings alone: temperature, reasoningEffort, maxTokens, maxOutputTokens and verbosity are read from backupModel and nowhere else, so a value left unset there takes the backup model's own default even when the agent's profile or the request itself carries one. This holds for every turn of a pinned conversation, not only the one that fell back — tuning meant for one model is not evidence of what another should use.

Applies to models served through Squid's own provider SDKs — the vendor models and openai_compatible, Bedrock and Vertex integrations. A model you serve yourself from backend code reports its failures as plain errors that carry no provider status, so a turn on one is never diagnosed as a provider outage and never falls back.

The backup resolves its API key exactly as it would as the primary model, and is skipped silently when it cannot be resolved, when it reaches the same model as the primary, or when either model is a CLI-backed agent. Leave unset to keep a provider outage surfacing as an error.

List of connected AI agents can be called by the current agent. Overrides the stored value.

List of connected AI agents can be called by the current agent. Overrides the stored value.

List of connected AiKnowlegeBases that can be called by the current agent

A set of filters that will limit the context the AI can access.

A set of filters that will limit the context the AI can access.

Whether to disable the whole context for the request. Default to false.

Rewrite prompt for RAG - defaults to false

Options for AI agent execution plan, allowing the agent to perform an execution plan before invoking connected agents, connected integrations, or functions.

File IDs to include in the chat context. These are IDs returned from the AI provider's Files API after uploading files. Files are attached to the conversation and can be read/analyzed by the AI.

An array of file URLs to include in the chat context.

Functions to expose to the AI. Either a function name or a name with an extra function context passed only to this function. The parameter values must be valid serializable JSON values. Overrides the stored value.

Preset instruction options that can be toggled on

Include metadata in the context.

Whether to include references from the source context in the response. Default to false.

Instructions to include with the prompt.

Whether to use the legacy knowledge base context mode, where KB results are fetched upfront and appended directly to the prompt. When false (default), the KB is exposed as a callable tool that the LLM can invoke on demand.

The maximum number of tokens the model should output. Passed directly to the AI model. Can be used to control the output verbosity.

The maximum number of input tokens that Squid can use when making the request to the AI model. Defaults to the max tokens the model can accept.

Maximum number of tool-call iterations the model may perform in a single chat turn. Defaults to 50.

The context ID to use for the request. If not provided, the agent's default context will be used.

Arbitrary client-defined annotations attached to this AI call for usage tracking. Reported as annotation.<key> tags on Squid AI usage metrics, so token usage can later be filtered and grouped by these values (e.g. { feature: 'support-bot', requestSource: 'mobile' }). Inherited by nested calls to connected agents made while serving this call. Limits: at most 10 entries, keys up to 64 characters, values up to 256 characters; entries beyond the limits are dropped or truncated.

Refuses prompts that carry PII before they reach the model. Read from the stored agent only — a value passed with a chat request is ignored, so a caller cannot switch off its own screening.

Current budget for nested or recursive AI chat calls per single prompt.

The level of reasoning effort to apply; defaults to model-specific value. Effective only for models with reasoning.

Which provider's reranker to use for reranking the context. Defaults to 'cohere'.

The format of the response from the AI model. Defaults to 'text'. A json_schema format is refused for a model whose provider has no way to carry a schema — see AiAgentResponseFormat.

Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true.

The temperature to use when sampling from the model. Default to 0.5.

Timeout in milliseconds for the entire chat request. Defaults to 240,000 (4 minutes).

Enable LLMs built-in code interpreter for executing Python code.

• 'none': Code interpreter is disabled (default).
• 'llm': Use LLM's native code interpreter to run Python code.

Note: Only supported by OpenAI, Anthropic and Gemini models. Ignored for other providers.

Controls response length and detail level. Use low for brief responses, medium for balanced detail, or high for comprehensive explanations. Default: 'medium'.

Note: this parameter is only supported by OpenAI and is ignored for others. It applies to every response format, including json_object and json_schema. For other providers ask about verbosity in prompt and using maxOutputTokens.

The options to use for the response in voice.

Names a persistent working directory for CLI-backed agents (claude-code, codex). When set, the agent runs in a directory keyed by this id, synced across pod replicas via the shared workspace server, so files created in one ask persist and are visible to later asks reusing the same id — including across providers.

Pass the same id consistently for a conversation; changing it points the agent at a different directory (and, for Claude Code, starts a fresh transcript). Must match [A-Za-z0-9_-] (1-200 chars). Ignored by non-CLI agents and when the workspace server is unconfigured (falls back to a pod-local, non-synced, ephemeral dir).