ConversationSettings
Conversation-level settings controlling behavior across sends
maxLoops caps the total number of generations in a run — not the number of
tool round trips. Default is 2, which is what one round trip costs: a first
generation to emit the tool call, a second to synthesize its result.
On the final generation the model is sent no tools at all (the request omits the
tools array), so it cannot emit a call there. maxLoops: 1 therefore means a
single tool-free reply — a valid way to ask for one, but not a way to get one tool
round trip.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
interruptPolicy | string (INTERRUPT_POLICY_REJECT_NEW, INTERRUPT_POLICY_CANCEL_ONGOING, INTERRUPT_POLICY_QUEUE, INTERRUPT_POLICY_IGNORE) or integer (int32) | Optional | Policy for an incoming message while another generation run is active. |
maxLoops | integer (int32) | Optional | Default limit on agentic generation loops for the conversation. Minimum: -2147483648. Maximum: 2147483647. |
maxParallelTools | integer (int32) | Optional | Maximum number of tool executions allowed concurrently by this configuration. Minimum: -2147483648. Maximum: 2147483647. |
mcpServers | Array of MCPServerReference | Optional | MCP servers available to this conversation; used for tool discovery/filtering |
toolPolicy | ToolExecutionPolicy | Optional | Optional per-conversation tool execution policy applied to AgentConfig |
promptVariables | Map from string to JSON value | Optional | Typed values used when rendering profile prompt templates. They are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. |
Values of interruptPolicy
How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning |
|---|---|---|---|
INTERRUPT_POLICY_REJECT_NEW | 1 | Canonical | Reject the new send with an error while a run is active; do not append its user message. |
INTERRUPT_POLICY_CANCEL_ONGOING | 2 | Canonical | Cancel the ongoing run and start a new run for the incoming message. |
INTERRUPT_POLICY_QUEUE | 3 | Canonical | Queue the incoming message to run after the current run completes. |
INTERRUPT_POLICY_IGNORE | 4 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
interruptPolicy | string (INTERRUPT_POLICY_REJECT_NEW, INTERRUPT_POLICY_CANCEL_ONGOING, INTERRUPT_POLICY_QUEUE, INTERRUPT_POLICY_IGNORE) or integer (int32) | Optional | Policy for an incoming message while another generation run is active. |
maxLoops | integer (int32) | Optional | Default limit on agentic generation loops for the conversation. Minimum: -2147483648. Maximum: 2147483647. |
maxParallelTools | integer (int32) | Optional | Maximum number of tool executions allowed concurrently by this configuration. Minimum: -2147483648. Maximum: 2147483647. |
mcpServers | Array of MCPServerReference | Optional | MCP servers available to this conversation; used for tool discovery/filtering |
toolPolicy | ToolExecutionPolicy | Optional | Optional per-conversation tool execution policy applied to AgentConfig |
promptVariables | Map from string to JSON value | Optional | Typed values used when rendering profile prompt templates. They are shared by profiles in the conversation and can be refreshed with UpdatePromptVariables. Switching profiles renders the new template with the same values. |
Values of interruptPolicy
How a conversation handles a new send while another generation run is active.
| Value | No. | Form | Meaning |
|---|---|---|---|
INTERRUPT_POLICY_REJECT_NEW | 1 | Canonical | Reject the new send with an error while a run is active; do not append its user message. |
INTERRUPT_POLICY_CANCEL_ONGOING | 2 | Canonical | Cancel the ongoing run and start a new run for the incoming message. |
INTERRUPT_POLICY_QUEUE | 3 | Canonical | Queue the incoming message to run after the current run completes. |
INTERRUPT_POLICY_IGNORE | 4 | Canonical | Accept the send without persisting its message or starting a new run; let the ongoing run continue. |
Where used
| Reference | Relationship |
|---|---|
| Create a new conversation thread | POST /api/v1/llm/create-thread |
| Update conversation settings | POST /api/v1/llm/update-settings |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Update prompt variables | POST /api/v1/llm/update-prompt-variables |
Download the public reference contract.
Document: DOC-API-MODEL-conversation-settings.