Agents

MCP tools for the Agents module. See the Agents module docs for permissions and data model.

create-agent

Create an agent

Arguments

Argument	Type	Required	Description
project_id	string	no	Public ID of the project
ai_provider_id	string	no	Public ID of the AI provider to pin. Mutually exclusive with model_route_id.
model_route_id	string	no	Public ID of a model route in the same project. The agent's completion model is then resolved through the route's ordered targets with failover. Mutually exclusive with ai_provider_id and model.
name	string	no	Display name.
instructions	string	no	System instructions, sent as the system message of every generation.
model	string	no	Model identifier on the pinned AI provider. Omitted, the provider's default model is used. Cannot be combined with model_route_id.
tool_bindings	array<object>	no	Tools to attach, one binding object per tool — the only attachment field. An entry is either a reference ({ "tool_id": … }) or an inline definition ({ "tool": … }). See Tool Bindings.
max_steps	number	no	Maximum agent loop steps per turn (default 20).
tool_choice	any	no	Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "tool_name": "my_tool" }). A forcing value ("required" or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a has_tool_call entry in stop_conditions — otherwise the write is refused with FORCED_TOOL_CHOICE_CANNOT_STOP.
stop_conditions	array<object>	no	Conditions that end the agent's work early, on top of max_steps. Two scopes: {"type": "has_tool_call", "tool_name": "<resolved tool name>"} ends the turn after the step that calls the named tool. It narrows when the loop ends — it never lets it run past max_steps. {"type": "max_chain_generations", "max_generations": <n>} bounds the continuation chain instead: once the chain has spawned that many generations, further resumptions stop with chain_limit rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's MAX_CONTINUATION_CHAIN_GENERATIONS, so an agent can be stricter than the platform but never looser. An unknown type, a has_tool_call without a tool_name, a max_chain_generations whose max_generations is not a positive integer, or a non-object entry is rejected with 400.
active_tool_ids	array<string>	no	Persisted tools from tool_bindings the model sees on every step. Omitted or [] leaves every bound tool active. See Active Tools.
guardrail_ids	array<string> | null	no	Guardrails attached at the agent scope.
step_rules	array<object>	no	Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn. See Step Rules.
boundary_policy	object | null	no	Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.
temperature	number	no	Sampling temperature passed to the model. Omitted, the provider's default applies.
knowledge_config	object	no	Knowledge search run before every generation; its matches are prepended as reference context. See Knowledge Config.
output_schema	object | null	no	JSON Schema describing the structured object the model must return. When set, non-streaming generations constrain output to this schema and the parsed value is returned as output.object. The schema is enforced on the way back, not just sent to the model: an object that violates it fails the generation with 502 OUTPUT_SCHEMA_VALIDATION_FAILED, naming the violated field. Constraints beyond required/type (minLength, enum, pattern, minItems) are honored and are what reject a structurally valid but degenerate answer. See the Structured Output section in the Agents module docs.
prompt_caching	object | null	no	Prompt caching for this agent's turns. {"enabled": true} marks a cache breakpoint at the end of the turn's static prefix — the tool definitions and the instructions together — so a provider that caches by explicit breakpoint reads that prefix back on every later step of the turn and every later turn of the session instead of being charged for it again. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. An agent with no instructions has no block to mark and caches nothing. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage.
max_context_messages	number	no	Maximum number of recent messages included in the context window. Null means no limit.
single_session_per_actor	boolean	no	When true, only one open session per actor_id is allowed for this agent.
trace_content_mode	string | null	no	Zero-retention opt-in for this agent. null inherits the project's setting; none means trace and generation content is never written. Setting full under a project whose own mode is none is refused with 400 — the project is a floor an agent may only tighten.
on_approval_expiry	string | null	no	What happens when one of this agent's held tool calls expires un-approved. null (the default) and terminate end the chain there — the expired approval, its approvals.expired event and the auto-filed approval_expired exception are the whole record. react spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
version_label	string | null	no	Optional tag for the config version this write archives (e.g. initial). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.

list-agents

List agents

Arguments

Argument	Type	Required	Description
project_id	string	no	Project public ID to filter by
limit	number	no	Maximum number of results to return
offset	number	no	Number of results to skip

get-agent

Get an agent

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID

update-agent

Update an agent

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
ai_provider_id	string | null	no	Public ID of the AI provider to pin. Mutually exclusive with model_route_id; set to null when switching to a route.
model_route_id	string | null	no	Model route in the same project. Mutually exclusive with ai_provider_id and model; set to null to clear.
name	string | null	no	Display name; null clears it.
instructions	string | null	no	System instructions, sent as the system message of every generation; null clears them.
model	string | null	no	Model identifier on the pinned AI provider; null falls back to the provider's default model. Cannot be combined with model_route_id.
tool_bindings	array<object> | null	no	Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to null to clear. See Tool Bindings.
max_steps	number | null	no	Maximum agent loop steps per turn; null restores the default of 20.
tool_choice	any	no	Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "tool_name": "my_tool" }). A forcing value ("required" or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a has_tool_call entry in stop_conditions — otherwise the write is refused with FORCED_TOOL_CHOICE_CANNOT_STOP.
stop_conditions	array<object> | null	no	Conditions that end the agent's work early, on top of max_steps. Two scopes: {"type": "has_tool_call", "tool_name": "<resolved tool name>"} ends the turn after the step that calls the named tool. It narrows when the loop ends — it never lets it run past max_steps. {"type": "max_chain_generations", "max_generations": <n>} bounds the continuation chain instead: once the chain has spawned that many generations, further resumptions stop with chain_limit rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's MAX_CONTINUATION_CHAIN_GENERATIONS, so an agent can be stricter than the platform but never looser. An unknown type, a has_tool_call without a tool_name, a max_chain_generations whose max_generations is not a positive integer, or a non-object entry is rejected with 400.
active_tool_ids	array<string> | null	no	Persisted tools from tool_bindings the model sees on every step. null or [] leaves every bound tool active. See Active Tools.
guardrail_ids	array<string> | null	no	Guardrails attached at the agent scope.
step_rules	array<object> | null	no	Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn; null clears them. See Step Rules.
boundary_policy	object | null	no	Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.
temperature	number | null	no	Sampling temperature passed to the model; null restores the provider's default.
knowledge_config	object | null	no	Knowledge search run before every generation; its matches are prepended as reference context. null turns it off. See Knowledge Config.
output_schema	object | null	no	JSON Schema describing the structured object the model must return. When set, non-streaming generations constrain output to this schema and the parsed value is returned as output.object. The schema is enforced on the way back, not just sent to the model: an object that violates it fails the generation with 502 OUTPUT_SCHEMA_VALIDATION_FAILED, naming the violated field. Constraints beyond required/type (minLength, enum, pattern, minItems) are honored and are what reject a structurally valid but degenerate answer. See the Structured Output section in the Agents module docs.
prompt_caching	object | null	no	Prompt caching for this agent's turns. {"enabled": true} marks a cache breakpoint at the end of the turn's static prefix — the tool definitions and the instructions together — so a provider that caches by explicit breakpoint reads that prefix back on every later step of the turn and every later turn of the session instead of being charged for it again. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. An agent with no instructions has no block to mark and caches nothing. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage.
max_context_messages	number | null	no	Maximum number of recent messages included in the context window. Null means no limit.
single_session_per_actor	boolean | null	no	When true, only one open session per actor_id is allowed for this agent.
trace_content_mode	string | null	no	Zero-retention opt-in for this agent. null inherits the project's setting; none means trace and generation content is never written. Setting full under a project whose own mode is none is refused with 400.
on_approval_expiry	string | null	no	What happens when one of this agent's held tool calls expires un-approved. null (the default) and terminate end the chain there — the expired approval, its approvals.expired event and the auto-filed approval_expired exception are the whole record. react spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
version_label	string | null	no	Optional tag for the config version this write archives (e.g. pre-tone-change). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.
expected_version	any	no	Refuses the write unless the resource is at this version.

patch-agent

Partially update an agent

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
ai_provider_id	string | null	no	Public ID of the AI provider to pin. Mutually exclusive with model_route_id; set to null when switching to a route.
model_route_id	string | null	no	Model route in the same project. Mutually exclusive with ai_provider_id and model; set to null to clear.
name	string | null	no	Display name; null clears it.
instructions	string | null	no	System instructions, sent as the system message of every generation; null clears them.
model	string | null	no	Model identifier on the pinned AI provider; null falls back to the provider's default model. Cannot be combined with model_route_id.
tool_bindings	array<object> | null	no	Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to null to clear. See Tool Bindings.
max_steps	number | null	no	Maximum agent loop steps per turn; null restores the default of 20.
tool_choice	any	no	Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "tool_name": "my_tool" }). A forcing value ("required" or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a has_tool_call entry in stop_conditions — otherwise the write is refused with FORCED_TOOL_CHOICE_CANNOT_STOP.
stop_conditions	array<object> | null	no	Conditions that end the agent's work early, on top of max_steps. Two scopes: {"type": "has_tool_call", "tool_name": "<resolved tool name>"} ends the turn after the step that calls the named tool. It narrows when the loop ends — it never lets it run past max_steps. {"type": "max_chain_generations", "max_generations": <n>} bounds the continuation chain instead: once the chain has spawned that many generations, further resumptions stop with chain_limit rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's MAX_CONTINUATION_CHAIN_GENERATIONS, so an agent can be stricter than the platform but never looser. An unknown type, a has_tool_call without a tool_name, a max_chain_generations whose max_generations is not a positive integer, or a non-object entry is rejected with 400.
active_tool_ids	array<string> | null	no	Persisted tools from tool_bindings the model sees on every step. null or [] leaves every bound tool active. See Active Tools.
guardrail_ids	array<string> | null	no	Guardrails attached at the agent scope.
step_rules	array<object> | null	no	Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn; null clears them. See Step Rules.
boundary_policy	object | null	no	Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.
temperature	number | null	no	Sampling temperature passed to the model; null restores the provider's default.
knowledge_config	object | null	no	Knowledge search run before every generation; its matches are prepended as reference context. null turns it off. See Knowledge Config.
output_schema	object | null	no	JSON Schema describing the structured object the model must return. When set, non-streaming generations constrain output to this schema and the parsed value is returned as output.object. The schema is enforced on the way back, not just sent to the model: an object that violates it fails the generation with 502 OUTPUT_SCHEMA_VALIDATION_FAILED, naming the violated field. Constraints beyond required/type (minLength, enum, pattern, minItems) are honored and are what reject a structurally valid but degenerate answer. See the Structured Output section in the Agents module docs.
prompt_caching	object | null	no	Prompt caching for this agent's turns. {"enabled": true} marks a cache breakpoint at the end of the turn's static prefix — the tool definitions and the instructions together — so a provider that caches by explicit breakpoint reads that prefix back on every later step of the turn and every later turn of the session instead of being charged for it again. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. An agent with no instructions has no block to mark and caches nothing. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage.
max_context_messages	number | null	no	Maximum number of recent messages included in the context window. Null means no limit.
single_session_per_actor	boolean | null	no	When true, only one open session per actor_id is allowed for this agent.
trace_content_mode	string | null	no	Zero-retention opt-in for this agent. null inherits the project's setting; none means trace and generation content is never written. Setting full under a project whose own mode is none is refused with 400.
on_approval_expiry	string | null	no	What happens when one of this agent's held tool calls expires un-approved. null (the default) and terminate end the chain there — the expired approval, its approvals.expired event and the auto-filed approval_expired exception are the whole record. react spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
version_label	string | null	no	Optional tag for the config version this write archives (e.g. pre-tone-change). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.
expected_version	any	no	Refuses the write unless the resource is at this version.

delete-agent

Delete an agent

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
force	boolean	no	When true, deletes the agent's dependent generations and traces, revokes its accepted shares and leaves its ingestion rules naming it instead of returning 409 AGENT_HAS_DEPENDENTS.

create-agent-generation

Run an agent generation

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
messages	array<object>	yes	Conversation turns, oldest first. Roles are user and assistant: the system prompt is the agent's instructions, so a system entry is refused with 400 SYSTEM_MESSAGE_NOT_ALLOWED.
tool_context	object | null	no	Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this generation. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY.
action_id	string	no	Logical action label recorded on the generation's usage meter, so spend can be rolled up per action (e.g. an A/B/C/D operating action).
guardrail_context	object | null	no	Caller-supplied guardrail context (the context.* namespace guard and class expressions read at tool-dispatch time). Free-form and never interpreted by the platform; a guardrail may combine it with a context_tool per its context_mode. See the guardrails module.
metadata	any	no	Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the ticket or case this action belongs to). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary, what knowledge retrieval served) lives in its own top-level generation fields and cannot be written from here. Use the request's own action_id field to set the usage-attribution label.
idempotency_key	string	no	Deduplication key, unique within the project, that makes a retry of an at-least-once delivery or an ambiguous failure safe. The first request under a key runs the generation; any later request carrying it runs nothing and answers 202 with the generation the key names, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the generation record for as long as the record exists. Every other body field except stream is the request the key names: reusing a key with any of them changed, or on another agent of the project, is 409 IDEMPOTENCY_KEY_REUSED. stream and wait say how the caller receives the generation, not what it is, so a retry may flip them.
knowledge_config	object | null	no	Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; tags pairs are merged with the override winning per key; scalar fields (min_score, rrf_k, recency_half_life_days, limit) use the per-generation value when present.

submit-agent-tool-outputs

Submit tool outputs for a paused generation

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
generation_id	string	yes	Public ID of the generation paused at requires_action
tool_outputs	array<object>	yes	Results for the tool calls the paused generation is waiting on, one entry per tool_call_id.

list-agent-versions

List an agent's config versions

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
limit	number	no	Maximum number of results to return
offset	number	no	Number of results to skip

get-agent-version

Get an archived agent config version

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
version	number	yes	Archived config version number

restore-agent-version

Restore an archived config as a new version

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
version	number	yes	Archived config version number
label	string	no	Tag for the version this restore creates. Defaults to restored from v{version}.

set-agent-release

Set or replace a staged rollout

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID
stable_version	number	yes	An existing version to serve as the baseline
canary_version	number	yes	An existing version to trial. Must differ from stable_version.
canary_percent	number	yes	Percentage of traffic to assign to canary_version
promotion_gate	string | null	no	Eval to gate promotion on. It must belong to this project and evaluate this agent; anything else is a 400. Omit it, or send null, for a rollout that can be promoted at will.

promote-agent-release

Promote the canary and end the rollout

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID

abort-agent-release

Abort the rollout and roll back to stable

Arguments

Argument	Type	Required	Description
agent_id	string	yes	Agent public ID