# Agent

> > This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

# Agent

> This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to 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

```yaml
type: agent
properties:
  ai_provider_id: String
  model_route_id: String
  name: String
  instructions: String
  model: String
  tool_bindings: Object[]
  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
```

_Types: [StopConditions[]](#stopconditions) · [StepRules[]](#steprules) · [BoundaryPolicy](#boundarypolicy) · [KnowledgeConfig](#knowledgeconfig)_

## Output

The physical resource ID is the **public ID** of the created resource. Reference it from other resources with a `ref` expression:

```yaml
      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 Object
_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
_Nullable_: Yes

---

**`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](#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](#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](#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 memory entries are injected into every generation.

_Required_: No
_Type_: [KnowledgeConfig](#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

---

## Sub-types

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

---

### 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

---

### KnowledgeConfig

Properties of the `knowledge_config` object.

**`memory_ids`**

Public IDs of memories to retrieve from

_Required_: No
_Type_: Array of String

---

**`memory_tags`**

Retrieve from all memories matching these tags

_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

---

**`min_score`**

Minimum similarity score (0–1) for retrieved chunks

_Required_: No
_Type_: Number

---

**`limit`**

Maximum number of chunks to inject

_Required_: No
_Type_: Integer

---

**`write_memory_id`**

Public ID of the memory the agent can write to. When set, a `write_memory` tool is automatically available to the agent.

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`extraction`**

Automatic fact extraction from completed generation turns (requires write_memory_id). Pass `true` to enable with defaults, or an object to customize the provider, model, and prompt used for the extraction completion.

_Required_: No
_Type_: Any

---