Formation Resource Types

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

Each resource type that can be declared in a Formation template is listed below. Click a type to see its full properties reference.

Output

All resource types return the public ID of the created resource as their output. You can reference this ID in other resource properties with a ref expression:

resources:
  MyMemory:
    type: memory
    properties:
      name: My Memory

  MyEntry:
    type: memory_entry
    properties:
      memory_id:
        ref: MyMemory   # resolves to the public ID of MyMemory
      content: Hello, world

Types

Type	Description
actor	Creates a stateful conversation actor that wraps an agent or chat session and optionally links to a memory store.
agent	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.
ai_provider	Configures an LLM provider connection (API key, model, endpoint) that agents use to generate responses.
api_key	Creates an API key scoped to the formation's project and optionally restricted by a set of policies. The key is owned by the caller who deployed the formation, exactly as one created through the API is, so it never carries more access than they already have.
chat	Creates a chat within the formation's project, connected either to an AI provider or — by declaring no provider — to the project's default_model_route_id.
conversation	Creates a conversation within the formation's project.
dataset	Declares an evaluation dataset — the named fixture suite an eval runs an agent against. Its test cases are declared separately as dataset_item resources, so an item curated through the API is never collateral of a formation apply. Deleting the dataset deletes its items and the evals bound to it.
dataset_item	One test case in a dataset: the messages sent to the agent under test and, optionally, the reference answer scorers compare against. Editing or removing an item never rewrites a run that already scored it — each result froze its own copy.
document	Stores a text document in a project, optionally indexing it for knowledge retrieval.
eval	Binds an agent under test to a dataset and the scorers its outputs are judged by. pass_threshold is the pass rate a run must reach for its passed verdict — the gate an agent-version promotion consumes.
file	Registers a file record within the formation's project.
guardrail	Creates a guardrail — an action-class document (class/guard) that gates tool-call autonomy. Attach it to a tool or agent via that resource's guardrail_ids (a { "ref": … } to this resource in the same template resolves to its physical id at deploy time). Mirrors the guardrails REST contract; class/default_class/guard/escalate are flattened here from the REST API's single document object.
ingestion_rule	Routes a file content_type to a converter (tool or agent) so ingestion can turn non-native files (images, audio, scanned PDFs) into Documents. See the Ingestion Rules module docs for the matching and converter-invocation model.
memory	Creates a named memory store that actors can read from and write to across conversations.
memory_entry	Adds a single text entry to a memory store.
model_route	Declares a model route within the formation's project: a named, ordered list of provider+model failover targets with retry and circuit-breaker configuration. Consumers reference it through their own model_route_id, or inherit it as the project's default_model_route_id.
orchestration	Creates a DAG orchestration that wires agents, tools, and knowledge lookups into a repeatable pipeline within the formation's project. Node resource references (agent_id, tool_id, memory_id, orchestration_id) accept { "ref": "LogicalId" } expressions to point at other resources declared in the same template — the basis for deploying an agent "squad" (a team of agents plus the flow that coordinates them) as a single stack.
policy	Creates an access-control policy within the formation's project.
project_price	Upserts a project-scoped price row so a deployed stack produces billing-grade usage cost with no out-of-band pricing step. The row is keyed on (provider, model, component, effective_from) within the formation's project — the middle pricing tier that covers every one of the project's instances of a given provider slug. When effective_from is omitted the price takes effect at deploy time, so generations run right after deploy are priced.
quota	Creates a quota — a project-scoped cap that blocks (enforce) or reports (monitor) when a windowed aggregate is exceeded. requests quotas are enforced by the request middleware; tokens/cost_usd quotas at the pre-generation check. Mirrors the quotas REST contract; scope, metric, window, and meter_type are immutable after creation (only limit, mode, and on_unpriced update).
secret	Creates an encrypted secret within the formation's project.
session	Creates a session attached to an agent within the formation's project.
tool	Defines a tool (HTTP endpoint, MCP server, SOAT action, or pipeline) that agents can invoke during a generation.
trigger	Binds a starter (manual, webhook, schedule, or event) to an executable target (orchestration, agent, tool, or eval). Firings run under the confined run-as identity of the caller who deployed the formation, so a firing never exceeds what that caller could do directly.
webhook	Registers an HTTPS endpoint to receive SOAT platform event notifications.
workflow	Creates a workflow — a state-machine definition (named states, allowed transitions, guards, and per-state automation) that tasks live in. State and transition dispatch references (agent_id, orchestration_id, tool_id inside an on_enter block) accept { "ref": "LogicalId" } expressions to point at agents, orchestrations or tools declared in the same template, so a workflow plus the agents and tools that service its states can deploy as one stack. Mirrors the workflows REST contract (states, transitions, payload_schema).