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 |
|---|---|---|---|
projectId | string | no | Public ID of the project |
aiProviderId | string | yes | Public ID of the AI provider |
name | string | no | — |
instructions | string | no | — |
model | string | no | — |
toolBindings | array<object> | no | Tools to attach, one binding object per tool — the canonical attachment field. Cannot be combined with the deprecated tool_ids/tools shorthands (400). See Tool Bindings. |
toolIds | array<string> | no | Deprecated shorthand — each entry becomes a bare { "tool_id": … } binding. Use tool_bindings instead. |
tools | array<string> | no | Deprecated shorthand — each entry becomes a bare { "tool": … } binding (an ephemeral definition: no separate Tool resource is created, any project_id on an entry is ignored, entries never appear in GET /tools, cannot be targeted by active_tool_ids/step_rules, and cannot be of type pipeline). Use tool_bindings instead. |
maxSteps | number | no | — |
toolChoice | string | no | Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "name": "my_tool" }). |
stopConditions | array<object> | no | — |
activeToolIds | array<string> | no | — |
guardrailIds | array<string> | no | Guardrails attached at the agent scope. |
stepRules | array<object> | no | — |
boundaryPolicy | object | no | — |
temperature | number | no | — |
knowledgeConfig | object | no | — |
outputSchema | object | no | JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as output.object in the generation response. See the Structured Output section in the Agents module docs. |
maxContextMessages | number | no | Maximum number of recent messages included in the context window. Null means no limit. |
singleSessionPerActor | boolean | no | When true, only one open session per actor_id is allowed for this agent. |
list-agents
List agents
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
projectId | 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 |
|---|---|---|---|
agentId | string | yes | — |
update-agent
Update an agent
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
aiProviderId | string | no | — |
name | string | no | — |
instructions | string | no | — |
model | string | no | — |
toolBindings | array<object> | no | Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to null to clear. Cannot be combined with the deprecated tool_ids/tools shorthands (400). See Tool Bindings. |
toolIds | array<string> | no | Deprecated shorthand — replaces only the reference (tool_id) bindings, rewriting them bare. Use tool_bindings instead. |
tools | array<string> | no | Deprecated shorthand — replaces only the inline (tool) bindings (ephemeral definitions: no separate Tool resource is created, any project_id on an entry is ignored, entries never appear in GET /tools, cannot be targeted by active_tool_ids/step_rules, and cannot be of type pipeline). Set to null to clear the inline bindings. Use tool_bindings instead. |
maxSteps | number | no | — |
toolChoice | string | no | Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "name": "my_tool" }). |
stopConditions | array<object> | no | — |
activeToolIds | array<string> | no | — |
guardrailIds | array<string> | no | Guardrails attached at the agent scope. |
stepRules | array<object> | no | — |
boundaryPolicy | object | no | — |
temperature | number | no | — |
knowledgeConfig | object | no | — |
outputSchema | object | no | JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as output.object in the generation response. See the Structured Output section in the Agents module docs. |
maxContextMessages | number | no | Maximum number of recent messages included in the context window. Null means no limit. |
singleSessionPerActor | boolean | no | When true, only one open session per actor_id is allowed for this agent. |
patch-agent
Partially update an agent
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
aiProviderId | string | no | — |
name | string | no | — |
instructions | string | no | — |
model | string | no | — |
toolBindings | array<object> | no | Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to null to clear. Cannot be combined with the deprecated tool_ids/tools shorthands (400). See Tool Bindings. |
toolIds | array<string> | no | Deprecated shorthand — replaces only the reference (tool_id) bindings, rewriting them bare. Use tool_bindings instead. |
tools | array<string> | no | Deprecated shorthand — replaces only the inline (tool) bindings (ephemeral definitions: no separate Tool resource is created, any project_id on an entry is ignored, entries never appear in GET /tools, cannot be targeted by active_tool_ids/step_rules, and cannot be of type pipeline). Set to null to clear the inline bindings. Use tool_bindings instead. |
maxSteps | number | no | — |
toolChoice | string | no | Tool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "name": "my_tool" }). |
stopConditions | array<object> | no | — |
activeToolIds | array<string> | no | — |
guardrailIds | array<string> | no | Guardrails attached at the agent scope. |
stepRules | array<object> | no | — |
boundaryPolicy | object | no | — |
temperature | number | no | — |
knowledgeConfig | object | no | — |
outputSchema | object | no | JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as output.object in the generation response. See the Structured Output section in the Agents module docs. |
maxContextMessages | number | no | Maximum number of recent messages included in the context window. Null means no limit. |
singleSessionPerActor | boolean | no | When true, only one open session per actor_id is allowed for this agent. |
delete-agent
Delete an agent
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
force | boolean | no | When true, deletes the agent's dependent generations and traces instead of returning 409 AGENT_HAS_DEPENDENTS. |
create-agent-generation
Run an agent generation
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
messages | array<object> | yes | — |
stream | boolean | no | When true the response is an SSE stream |
toolContext | object | no | Key-value pairs forwarded as X-Soat-Context-<Key> headers on every http, mcp and soat tool call in this generation. Each key's first character is uppercased and the rest is used verbatim. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY. |
actionId | 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). |
guardrailContext | object | 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 | object | no | Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips when the generation is fetched via the generations API. Reserved server-owned keys (action_id, trigger_id, run_id, node_id, extraction, and internal recovery state) cannot be set here and are rejected with 400. |
extract | boolean | no | Per-turn override of the agent's knowledge_config.extraction default. Omit to follow the agent's stored config. Set false to suppress automatic memory extraction for this turn (e.g. an operational or tool-listing turn that would only add noise to a curated memory). Set true to force extraction on for this turn even when the agent does not enable it by default, provided the agent has a write_memory_id. Has no effect on streaming or requires_action turns, which never extract. |
knowledgeConfig | object | no | Per-generation knowledge retrieval override. Array filters (memory_ids, memory_tags, document_ids, document_paths) are unioned with the agent's stored knowledge_config; scalar fields (min_score, limit) use the per-generation value when present. |
submit-agent-tool-outputs
Submit tool outputs for a paused generation
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
generationId | string | yes | — |
toolOutputs | array<object> | yes | — |