Agent
This page is auto-generated from the formations OpenAPI spec. Do not edit manually — run
pnpm generate-formations-resource-docsto regenerate.
Creates an AI agent backed by a provider. The agent handles requests, runs tools, and can be attached to actors. Exactly one of ai_provider_id or model_route_id must be declared. Switching an existing agent between the two declares the new field together with an explicit null for the old one.
Syntax
type: agent
properties:
ai_provider_id: String
model_route_id: String
name: String
instructions: String
model: String
tool_bindings: ToolBindings[]
max_steps: Integer
tool_choice: Any
stop_conditions: StopConditions[]
active_tool_ids: String[]
guardrail_ids: String[]
step_rules: StepRules[]
boundary_policy: BoundaryPolicy
temperature: Number
max_context_messages: Integer
single_session_per_actor: Boolean
trace_content_mode: String
on_approval_expiry: String
knowledge_config: KnowledgeConfig
output_schema: Object
prompt_caching: PromptCaching
Types: ToolBindings[] · StopConditions[] · StepRules[] · BoundaryPolicy · KnowledgeConfig · PromptCaching
Output
The physical resource ID is the public ID of the created resource. Reference it from other resources with a ref expression:
some_field:
ref: MyAgent
Properties
ai_provider_id
Public ID of the AI provider to pin. Mutually exclusive with model_route_id.
Required: No Type: String Nullable: Yes
model_route_id
Public ID of a model route in the same project — the agent's completion model is resolved through the route's ordered targets with failover. Mutually exclusive with ai_provider_id and model.
Required: No Type: String Nullable: Yes
name
Agent display name
Required: No Type: String Nullable: Yes
instructions
System instructions for the agent
Required: No Type: String Nullable: Yes
model
Model identifier (overrides provider default)
Required: No Type: String Nullable: Yes
tool_bindings
Tools to attach, one binding object per tool: { tool_id }. Tool-call gating is owned by guardrails (attached via guardrail_ids on the project, agent, or tool), not by the binding. Inline tool entries are not supported in templates; declare a tool resource and reference it via tool_id (a { "ref": … } to a tool resource in the same template resolves at deploy time).
Required: No Type: Array of ToolBindings Nullable: Yes
max_steps
Maximum number of agentic steps per generation
Required: No Type: Integer Nullable: Yes
tool_choice
Controls how the model selects tools. Accepts a string ("auto", "required") or an object ({ "type": "tool", "tool_name": "my_tool" }).
Required: No Type: Any
stop_conditions
Conditions that stop the agent's work early — turn-scoped (has_tool_call) or chain-scoped (max_chain_generations).
Required: No Type: Array of StopConditions Nullable: Yes
active_tool_ids
Subset of the bound tools that are active
Required: No Type: Array of String Nullable: Yes
guardrail_ids
Guardrails attached at the agent scope.
Required: No Type: Array of String Nullable: Yes
step_rules
Per-step overrides applied during multi-step generation. Steps not covered by a rule use the agent defaults.
Required: No Type: Array of StepRules Nullable: Yes
boundary_policy
Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy.
Required: No Type: BoundaryPolicy Nullable: Yes
temperature
Sampling temperature
Required: No Type: Number Nullable: Yes
max_context_messages
Maximum number of recent messages to include in the context window sent to the model. When null, all messages are included.
Required: No Type: Integer Nullable: Yes
single_session_per_actor
When true, only one open session per actor_id is allowed for this agent.
Required: No Type: Boolean Nullable: Yes
trace_content_mode
Agent-scope zero-retention setting (full or none). null inherits the project's setting. full is refused when the project's own mode is none.
Required: No Type: String Nullable: Yes
on_approval_expiry
What happens when a held tool call expires un-approved: terminate (the default when null) ends the chain, react spawns a continuation that reports the staleness to the agent.
Required: No Type: String Nullable: Yes
knowledge_config
Knowledge retrieval configuration. When set, relevant documents and memories are injected into every generation.
Required: No Type: KnowledgeConfig Nullable: Yes
output_schema
JSON Schema describing the structured object the model must return. Non-streaming generations are constrained to this schema; the parsed value is returned as output.object.
Required: No Type: Object Nullable: Yes
prompt_caching
Prompt caching for this agent's turns. {"enabled": true} marks a cache breakpoint at the end of the system block and on the last message of each step. Null or omitted is off.
Required: No Type: PromptCaching Nullable: Yes
Sub-types
ToolBindings
Properties of each item in tool_bindings.
tool_id
Public ID of the tool to attach.
Required: No Type: String
tool
Inline tool definition. Not supported in a template: declare a tool resource and reference it via tool_id.
Required: No Type: Object Nullable: Yes
StopConditions
Properties of each item in stop_conditions.
type
Condition type — has_tool_call or max_chain_generations
Required: No Type: String
tool_name
Tool name to match when type is has_tool_call
Required: No Type: String Nullable: Yes
max_generations
Generations the continuation chain may reach when type is max_chain_generations
Required: No Type: Integer Nullable: Yes
StepRules
Properties of each item in step_rules.
step
1-indexed step number this rule applies to
Required: No Type: Integer
tool_choice
Tool choice override for this step, e.g. auto, required, or { type: tool, tool_name: search }
Required: No Type: Object Nullable: Yes
active_tool_ids
Tool IDs active on this step
Required: No Type: Array of String Nullable: Yes
BoundaryPolicy
Properties of the boundary_policy object.
statement
List of IAM policy statements
Required: No Type: Array of Statement
Statement
Properties of each item in statement.
effect
Effect — Allow or Deny
Required: No Type: String
action
IAM action strings, e.g. memories:* or agents:DeleteAgent
Required: No Type: Array of String
resource
Resource SRN patterns (optional; omit to match all resources)
Required: No Type: Array of String Nullable: Yes
condition
Condition block, in the same grammar a policy document uses: keys are condition operators mapping to context-key/value maps.
Required: No Type: Object Nullable: Yes
KnowledgeConfig
Properties of the knowledge_config object.
memory_store_ids
Public IDs of memory stores to retrieve from
Required: No Type: Array of String
document_ids
Public IDs of documents to retrieve from
Required: No Type: Array of String
document_paths
Retrieve from all documents matching these path prefixes
Required: No Type: Array of String
tags
Retrieve from documents and memories whose tags contain all these key-value pairs.
Required: No Type: Any
min_score
Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked. Omitted, there is no floor.
Required: No Type: Number
rrf_k
The k in the fusion term 1 / (k + rank); smaller weights the top of each ranking more heavily
Required: No Type: Integer
recency_half_life_days
Half-life in days of the decay applied to memory results after fusion; 0 disables it
Required: No Type: Number
limit
Maximum number of chunks to inject
Required: No Type: Integer
write_memory_store_id
Public ID of the memory store the agent can write to. When set, a write_memory tool is automatically available to the agent.
Required: No Type: String Nullable: Yes
PromptCaching
Properties of the prompt_caching object.
enabled
Whether the breakpoint is marked. Defaults to false.
Required: No Type: Boolean