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

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

```yaml
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`](/docs/formations-types/actor) | Creates a stateful conversation actor that wraps an agent or chat session and optionally links to a memory store. |
| [`agent`](/docs/formations-types/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`](/docs/formations-types/ai-provider) | Configures an LLM provider connection (API key, model, endpoint) that agents use to generate responses. |
| [`api_key`](/docs/formations-types/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`](/docs/formations-types/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`](/docs/formations-types/conversation) | Creates a conversation within the formation's project. |
| [`dataset`](/docs/formations-types/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`](/docs/formations-types/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`](/docs/formations-types/document) | Stores a text document in a project, optionally indexing it for knowledge retrieval. |
| [`eval`](/docs/formations-types/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`](/docs/formations-types/file) | Registers a file record within the formation's project. |
| [`guardrail`](/docs/formations-types/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`](/docs/formations-types/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`](/docs/formations-types/memory) | Creates a named memory store that actors can read from and write to across conversations. |
| [`memory_entry`](/docs/formations-types/memory-entry) | Adds a single text entry to a memory store. |
| [`model_route`](/docs/formations-types/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`](/docs/formations-types/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`](/docs/formations-types/policy) | Creates an access-control policy within the formation's project. |
| [`project_price`](/docs/formations-types/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`](/docs/formations-types/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`](/docs/formations-types/secret) | Creates an encrypted secret within the formation's project. |
| [`session`](/docs/formations-types/session) | Creates a session attached to an agent within the formation's project. |
| [`tool`](/docs/formations-types/tool) | Defines a tool (HTTP endpoint, MCP server, SOAT action, or pipeline) that agents can invoke during a generation. |
| [`trigger`](/docs/formations-types/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`](/docs/formations-types/webhook) | Registers an HTTPS endpoint to receive SOAT platform event notifications. |
| [`workflow`](/docs/formations-types/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`). |