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.

Syntax

type: agent
properties:
  ai_provider_id: String
  name: String
  instructions: String
  model: String
  tool_ids: String[]
  max_steps: Integer
  tool_choice: Any
  stop_conditions: StopConditions[]
  active_tool_ids: String[]
  step_rules: StepRules[]
  boundary_policy: BoundaryPolicy
  temperature: Number
  max_context_messages: Integer
  single_session_per_actor: Boolean
  knowledge_config: KnowledgeConfig

Types: StopConditions[] · StepRules[] · BoundaryPolicy · KnowledgeConfig

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

Required: Yes Type: String

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_ids

Agent tool IDs to attach

Required: No Type: Array of String 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", "name": "my_tool" }).

Required: No Type: Any Nullable: Yes

stop_conditions

Conditions that stop multi-step generation early. The loop stops when any condition is met.

Required: No Type: Array of StopConditions Nullable: Yes

active_tool_ids

Subset of tool_ids that are active

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

knowledge_config

Knowledge retrieval configuration. When set, relevant documents and memory entries are injected into every generation.

Required: No Type: KnowledgeConfig Nullable: Yes

Sub-types

StopConditions

Properties of each item in stop_conditions.

type

Condition type — currently hasToolCall

Required: No Type: String

tool_name

Tool name to match when type is hasToolCall

Required: No Type: String 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

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

Syntax​

Output​

Properties​

Sub-types​

StopConditions​

StepRules​

BoundaryPolicy​

Statement​

KnowledgeConfig​

Syntax

Output

Properties

Sub-types

StopConditions

StepRules

BoundaryPolicy

Statement

KnowledgeConfig