Skip to main content

Agents Commands

See Agents module docs for permissions and data model.

soat create-agent​

Create an agent

  • Method: POST
  • Path: /api/v1/agents

Usage​

soat create-agent --ai-provider-id <string>

Options​

--project-id​

Public ID of the project

  • Source: body
  • Required: no
  • Type: string
--ai-provider-id​

Public ID of the AI provider

  • Source: body
  • Required: yes
  • Type: string
--name​

—

  • Source: body
  • Required: no
  • Type: string
--instructions​

—

  • Source: body
  • Required: no
  • Type: string
--model​

—

  • Source: body
  • Required: no
  • Type: string
--tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--tools​

Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any project_id on an entry is ignored), so they never appear in GET /tools and cannot be targeted by active_tool_ids/ step_rules (which reference tool_ids). Cannot be of type pipeline; nest a persisted pipeline tool via tool_ids instead. Use tool_ids to reference existing tools and tools for ones scoped to just this agent.

  • Source: body
  • Required: no
  • Type: array<unknown>
--max-steps​

—

  • Source: body
  • Required: no
  • Type: integer
--tool-choice​

Tool choice strategy. Accepts a string ("auto", "required") or an object (\{ "type": "tool", "name": "my_tool" \}).

  • Source: body
  • Required: no
  • Type: unknown
--stop-conditions​

—

  • Source: body
  • Required: no
  • Type: array<object>
--active-tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--step-rules​

—

  • Source: body
  • Required: no
  • Type: array<object>
--boundary-policy​

—

  • Source: body
  • Required: no
  • Type: object
--temperature​

—

  • Source: body
  • Required: no
  • Type: number
--knowledge-config​

—

  • Source: body
  • Required: no
  • Type: object
--output-schema​

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.

  • Source: body
  • Required: no
  • Type: object
--max-context-messages​

Maximum number of recent messages included in the context window. Null means no limit.

  • Source: body
  • Required: no
  • Type: integer
--single-session-per-actor​

When true, only one open session per actor_id is allowed for this agent.

  • Source: body
  • Required: no
  • Type: boolean

soat list-agents​

List agents

  • Method: GET
  • Path: /api/v1/agents

Usage​

soat list-agents

Options​

--project-id​

Project public ID to filter by

  • Source: query
  • Required: no
  • Type: string

soat get-agent​

Get an agent

  • Method: GET
  • Path: /api/v1/agents/{agent_id}

Usage​

soat get-agent --agent-id <string>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat update-agent​

Update an agent

  • Method: PUT
  • Path: /api/v1/agents/{agent_id}

Usage​

soat update-agent --agent-id <string>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string
--ai-provider-id​

—

  • Source: body
  • Required: no
  • Type: string
--name​

—

  • Source: body
  • Required: no
  • Type: string \| null
--instructions​

—

  • Source: body
  • Required: no
  • Type: string \| null
--model​

—

  • Source: body
  • Required: no
  • Type: string \| null
--tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--tools​

Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any project_id on an entry is ignored), so they never appear in GET /tools and cannot be targeted by active_tool_ids/ step_rules (which reference tool_ids). Cannot be of type pipeline; nest a persisted pipeline tool via tool_ids instead. Replaces the agent's entire tools array; set to null to clear.

  • Source: body
  • Required: no
  • Type: array<unknown>
--max-steps​

—

  • Source: body
  • Required: no
  • Type: integer \| null
--tool-choice​

Tool choice strategy. Accepts a string ("auto", "required") or an object (\{ "type": "tool", "name": "my_tool" \}).

  • Source: body
  • Required: no
  • Type: unknown \| null
--stop-conditions​

—

  • Source: body
  • Required: no
  • Type: array<object>
--active-tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--step-rules​

—

  • Source: body
  • Required: no
  • Type: array<object>
--boundary-policy​

—

  • Source: body
  • Required: no
  • Type: object
--temperature​

—

  • Source: body
  • Required: no
  • Type: number \| null
--knowledge-config​

—

  • Source: body
  • Required: no
  • Type: object
--output-schema​

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.

  • Source: body
  • Required: no
  • Type: object
--max-context-messages​

Maximum number of recent messages included in the context window. Null means no limit.

  • Source: body
  • Required: no
  • Type: integer \| null
--single-session-per-actor​

When true, only one open session per actor_id is allowed for this agent.

  • Source: body
  • Required: no
  • Type: boolean \| null

soat patch-agent​

Partially update an agent

  • Method: PATCH
  • Path: /api/v1/agents/{agent_id}

Usage​

soat patch-agent --agent-id <string>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string
--ai-provider-id​

—

  • Source: body
  • Required: no
  • Type: string
--name​

—

  • Source: body
  • Required: no
  • Type: string \| null
--instructions​

—

  • Source: body
  • Required: no
  • Type: string \| null
--model​

—

  • Source: body
  • Required: no
  • Type: string \| null
--tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--tools​

Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any project_id on an entry is ignored), so they never appear in GET /tools and cannot be targeted by active_tool_ids/ step_rules (which reference tool_ids). Cannot be of type pipeline; nest a persisted pipeline tool via tool_ids instead. Replaces the agent's entire tools array; set to null to clear.

  • Source: body
  • Required: no
  • Type: array<unknown>
--max-steps​

—

  • Source: body
  • Required: no
  • Type: integer \| null
--tool-choice​

Tool choice strategy. Accepts a string ("auto", "required") or an object (\{ "type": "tool", "name": "my_tool" \}).

  • Source: body
  • Required: no
  • Type: unknown \| null
--stop-conditions​

—

  • Source: body
  • Required: no
  • Type: array<object>
--active-tool-ids​

—

  • Source: body
  • Required: no
  • Type: array<string>
--step-rules​

—

  • Source: body
  • Required: no
  • Type: array<object>
--boundary-policy​

—

  • Source: body
  • Required: no
  • Type: object
--temperature​

—

  • Source: body
  • Required: no
  • Type: number \| null
--knowledge-config​

—

  • Source: body
  • Required: no
  • Type: object
--output-schema​

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.

  • Source: body
  • Required: no
  • Type: object
--max-context-messages​

Maximum number of recent messages included in the context window. Null means no limit.

  • Source: body
  • Required: no
  • Type: integer \| null
--single-session-per-actor​

When true, only one open session per actor_id is allowed for this agent.

  • Source: body
  • Required: no
  • Type: boolean \| null

soat delete-agent​

Delete an agent

  • Method: DELETE
  • Path: /api/v1/agents/{agent_id}

Usage​

soat delete-agent --agent-id <string>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string
--force​

When true, deletes the agent's dependent generations and traces instead of returning 409 AGENT_HAS_DEPENDENTS.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: false

soat create-agent-generation​

Run an agent generation

  • Method: POST
  • Path: /api/v1/agents/{agent_id}/generate

Usage​

soat create-agent-generation --agent-id <string> --messages <array<object>>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string
--messages​

—

  • Source: body
  • Required: yes
  • Type: array<object>
--stream​

When true the response is an SSE stream

  • Source: body
  • Required: no
  • Type: boolean
  • Default: false
--trace-id​

Optional trace ID to group generations

  • Source: body
  • Required: no
  • Type: string
--parent-trace-id​

The trace ID of the parent agent generation that triggered this one (for agent-to-agent calls)

  • Source: body
  • Required: no
  • Type: string \| null
--root-trace-id​

The trace ID of the root generation in the call chain; if omitted, this generation is the root

  • Source: body
  • Required: no
  • Type: string \| null
--max-call-depth​

Maximum nested agent-call depth; 0 short-circuits with a depth-guard response

  • Source: body
  • Required: no
  • Type: integer
  • Default: 10
--tool-context​

Key-value pairs injected as context headers into all tool call requests made during this generation.

  • Source: body
  • Required: no
  • Type: object<string, string>
--action-id​

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).

  • Source: body
  • Required: no
  • Type: string
--knowledge-config​

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.

  • Source: body
  • Required: no
  • Type: object

soat submit-agent-tool-outputs​

Submit tool outputs for a paused generation

  • Method: POST
  • Path: /api/v1/agents/{agent_id}/generate/{generation_id}/tool-outputs

Usage​

soat submit-agent-tool-outputs --agent-id <string> --generation-id <string> --tool-outputs <array<object>>

Options​

--agent-id​

—

  • Source: path
  • Required: yes
  • Type: string
--generation-id​

—

  • Source: path
  • Required: yes
  • Type: string
--tool-outputs​

—

  • Source: body
  • Required: yes
  • Type: array<object>