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

Options​

--project-id​

Public ID of the project

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

Public ID of the AI provider to pin. Mutually exclusive with model_route_id.

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

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.

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

Display name.

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

System instructions, sent as the system message of every generation.

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

Model identifier on the pinned AI provider. Omitted, the provider's default model is used. Cannot be combined with model_route_id.

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

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.

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

Maximum agent loop steps per turn (default 20).

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

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.

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

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.

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

Persisted tools from tool_bindings the model sees on every step. Omitted or [] leaves every bound tool active. See Active Tools.

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

Guardrails attached at the agent scope.

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

Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn. See Step Rules.

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

Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.

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

Sampling temperature passed to the model. Omitted, the provider's default applies.

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

Knowledge search run before every generation; its matches are prepended as reference context. See 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 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.

  • Source: body
  • Required: no
  • Type: object
--prompt-caching​

Prompt caching for this agent's turns. \{"enabled": true\} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. 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. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.

  • 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
--max-output-tokens​

Maximum number of tokens the model may generate per step of a turn. A response that reaches it stops with stop_reason length. Null leaves the model's default.

  • Source: body
  • Required: no
  • Type: integer \| null
  • Example: 1024
--reasoning​

How much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.

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

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

  • Source: body
  • Required: no
  • Type: boolean
--trace-content-mode​

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.

  • Source: body
  • Required: no
  • Type: enum("full", "none", null)
--on-approval-expiry​

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.

  • Source: body
  • Required: no
  • Type: enum("terminate", "react", null)
--version-label​

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.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: initial

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

Options​

This command has no options.

soat update-agent​

Update an agent

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

Usage​

soat update-agent

Options​

--ai-provider-id​

Public ID of the AI provider to pin. Mutually exclusive with model_route_id; set to null when switching to a route.

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

Model route in the same project. Mutually exclusive with ai_provider_id and model; set to null to clear.

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

Display name; null clears it.

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

System instructions, sent as the system message of every generation; null clears them.

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

Model identifier on the pinned AI provider; null falls back to the provider's default model. Cannot be combined with model_route_id.

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

Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to null to clear. See Tool Bindings.

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

Maximum agent loop steps per turn; null restores the default of 20.

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

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.

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

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.

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

Persisted tools from tool_bindings the model sees on every step. null or [] leaves every bound tool active. See Active Tools.

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

Guardrails attached at the agent scope.

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

Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn; null clears them. See Step Rules.

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

Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.

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

Sampling temperature passed to the model; null restores the provider's default.

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

Knowledge search run before every generation; its matches are prepended as reference context. null turns it off. See 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 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.

  • Source: body
  • Required: no
  • Type: object
--prompt-caching​

Prompt caching for this agent's turns. \{"enabled": true\} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. 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. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.

  • 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
--max-output-tokens​

Maximum number of tokens the model may generate per step of a turn. A response that reaches it stops with stop_reason length. Null leaves the model's default.

  • Source: body
  • Required: no
  • Type: integer \| null
  • Example: 1024
--reasoning​

How much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.

  • Source: body
  • Required: no
  • Type: object
--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
--trace-content-mode​

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.

  • Source: body
  • Required: no
  • Type: enum("full", "none", null)
--on-approval-expiry​

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.

  • Source: body
  • Required: no
  • Type: enum("terminate", "react", null)
--version-label​

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.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: pre-tone-change
--expected-version​

Refuses the write unless the resource is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat patch-agent​

Partially update an agent

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

Usage​

soat patch-agent

Options​

--ai-provider-id​

Public ID of the AI provider to pin. Mutually exclusive with model_route_id; set to null when switching to a route.

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

Model route in the same project. Mutually exclusive with ai_provider_id and model; set to null to clear.

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

Display name; null clears it.

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

System instructions, sent as the system message of every generation; null clears them.

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

Model identifier on the pinned AI provider; null falls back to the provider's default model. Cannot be combined with model_route_id.

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

Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to null to clear. See Tool Bindings.

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

Maximum agent loop steps per turn; null restores the default of 20.

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

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.

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

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.

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

Persisted tools from tool_bindings the model sees on every step. null or [] leaves every bound tool active. See Active Tools.

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

Guardrails attached at the agent scope.

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

Per-step overrides of tool_choice and active_tool_ids, numbered from the first step of the turn; null clears them. See Step Rules.

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

Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.

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

Sampling temperature passed to the model; null restores the provider's default.

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

Knowledge search run before every generation; its matches are prepended as reference context. null turns it off. See 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 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.

  • Source: body
  • Required: no
  • Type: object
--prompt-caching​

Prompt caching for this agent's turns. \{"enabled": true\} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. 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. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.

  • 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
--max-output-tokens​

Maximum number of tokens the model may generate per step of a turn. A response that reaches it stops with stop_reason length. Null leaves the model's default.

  • Source: body
  • Required: no
  • Type: integer \| null
  • Example: 1024
--reasoning​

How much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.

  • Source: body
  • Required: no
  • Type: object
--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
--trace-content-mode​

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.

  • Source: body
  • Required: no
  • Type: enum("full", "none", null)
--on-approval-expiry​

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.

  • Source: body
  • Required: no
  • Type: enum("terminate", "react", null)
--version-label​

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.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: pre-tone-change
--expected-version​

Refuses the write unless the resource is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat delete-agent​

Delete an agent

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

Usage​

soat delete-agent

Options​

--force​

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.

  • 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 --messages <array<object>>

Options​

--wait​

When omitted or false (default), the generation runs in the background and 202 Accepted is returned immediately with a generation_id to poll. Pass true to block until the generation settles and receive the result. Mutually exclusive with stream: true. A tool call, builtin or MCP, always waits.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: false
--messages​

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.

  • 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. Each generation appends its own steps to the trace's steps object, and step_count covers them all.

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

  • 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
--guardrail-context​

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.

  • Source: body
  • Required: no
  • Type: object<string, unknown>
--metadata​

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.

  • Source: body
  • Required: no
  • Type: unknown
--idempotency-key​

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.

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

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.

  • 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 --tool-outputs <array<object>>

Options​

--tool-outputs​

Results for the tool calls the paused generation is waiting on, one entry per tool_call_id.

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

soat list-agent-versions​

List an agent's config versions

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

Usage​

soat list-agent-versions

Options​

This command has no options.

soat get-agent-version​

Get an archived agent config version

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

Usage​

soat get-agent-version

Options​

This command has no options.

soat restore-agent-version​

Restore an archived config as a new version

  • Method: POST
  • Path: /api/v1/agents/{agent_id}/versions/{version}/restore

Usage​

soat restore-agent-version

Options​

--label​

Tag for the version this restore creates. Defaults to restored from v\{version\}.

  • Source: body
  • Required: no
  • Type: string
  • Example: rollback-incident-42

soat set-agent-release​

Set or replace a staged rollout

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

Usage​

soat set-agent-release --stable-version <integer> --canary-version <integer> --canary-percent <integer>

Options​

--stable-version​

An existing version to serve as the baseline

  • Source: body
  • Required: yes
  • Type: integer
  • Example: 3
--canary-version​

An existing version to trial. Must differ from stable_version.

  • Source: body
  • Required: yes
  • Type: integer
  • Example: 4
--canary-percent​

Percentage of traffic to assign to canary_version

  • Source: body
  • Required: yes
  • Type: integer
  • Example: 20
--promotion-gate​

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.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: eval_V1StGXR8Z5jdHi6B

soat promote-agent-release​

Promote the canary and end the rollout

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

Usage​

soat promote-agent-release

Options​

This command has no options.

soat abort-agent-release​

Abort the rollout and roll back to stable

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

Usage​

soat abort-agent-release

Options​

This command has no options.