Formations
A whole agent stack described in one template, deployed as one unit.
Overview
Everything else in this API is imperative: you create an agent, then a tool, then wire the second into the first, and you keep track of the ids in between. A formation inverts that. You write one template naming the agents, tools, memory stores, triggers and everything else the project needs, reference one resource from another by its logical name, and deploy the lot with a single call. The runtime works out the order, resolves the references, and rolls the whole deployment back if any resource fails.
Update the same formation with a changed template and
it converges: resources are
created, updated or deleted so the project matches what the template now says.
Delete the formation and everything it created goes with it,
except what the template asked to retain.
If you know CloudFormation or Terraform, you already know the shape. The reason to reach for it here is the same one: a stack you can review in a pull request, apply from CI, and tear down without hunting for the pieces.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
One answer is naturali's own: the naturali-conversion formation naturali
deploys for managed conversion is read-only, and a write
whose metadata sets naturali_managed answers
403 MANAGED_RESOURCE_READ_ONLY, on every path the runtime writes through,
not only these routes.
A template is a second way to create everything else in this API, so the plan rules that apply to the routes apply to a declaration too.
A deploy writes each resource under the same rules as its route — a provider's
credential, the plan's features, the trigger count and interval floor,
storage, credit, runs, a model's source and price —
once its parameters resolve; a refused write fails the deploy with that route's
status and code, and the refusal's meta. A validate or plan writes
nothing, so these rules do not answer it, except a managed model's source and
price: both are checked against the template, as a deploy checks them. A channel is counted
against the account when the deploy creates it.
An oauth_client resource declared without redirect_uri, or with null,
gets this API's callback, as on a direct create: see
OAuth clients → Redirect URI.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Formations.
Data Model
Formation
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the formation |
project_id | string | Project public ID |
name | string | Human-readable formation name |
template | object | The template as deployed. Credential-bearing properties — a secret resource's value, and any property a custom resource type declares write_only — read back as { "no_echo": true } rather than the value that was supplied. |
outputs | object, nullable | Resolved output values after stack deployment. An output that resolved a credential attribute on a formation deployed before those were refused is omitted. |
status | creating | active | updating | failed | deleting | deleted | delete_failed | Formation status |
metadata | object | Static annotations stored on the formation record (supplied at create/update). Not a substitution site — sub/param/ref expressions are rejected. Use the template's top-level metadata block for deploy-time substitution (see resolved_metadata). |
resolved_metadata | object, nullable | The template's top-level metadata block after parameter (sub/param) and resource (ref) substitution at the last deploy. Null when the template declares no metadata. |
resolved_parameters | object, nullable | Parameter values applied at the last deploy, for auditability. no_echo parameters are masked (***). Null when the template declares no parameters. |
error | object, nullable | Why the formation is failed or delete_failed. Null in every other status, and cleared by the next successful deploy. This is the reason a 2xx deploy response can report status: "failed" without a second call to list-formation-events. A failed apply names the resource that broke it in meta (logical_id, resource_type); a failed teardown lists every blocker under meta.failures. One case carries an error while the formation is active: FORMATION_REPLACE_CLEANUP_FAILED, when a deploy replaced a resource and the superseded one could not be deleted. The desired state is realised, so the deploy succeeded — but the old resource is still live, and meta.failures names it. It stays on the formation as pending cleanup and is retried on the next deploy or teardown, which clears the error once it is gone. |
resources | object[] | Resources managed by this formation (present on get/create/update) |
created_at | string (date-time) | |
updated_at | string (date-time) |
name is unique per project: reusing one is a 409.
FormationResource
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the resource record |
logical_id | string | Logical identifier from the template |
resource_type | string | Resource type (e.g. agent, memory_store) |
physical_resource_id | string, nullable | Public ID of the physical resource |
status | pending | created | updated | deleted | failed | Current resource status |
The physical_resource_id is the bridge back to the rest of this API: a
formation-created agent is an ordinary agent, readable and
callable through
agents like any other.
Key Concepts
A template is parameters, resources and outputs
resources is the only required block. Each entry maps a logical id — your name
for the resource, used to reference it elsewhere — to a type and a properties
bag whose shape depends on that type.
Three expressions can appear anywhere in a property value, which is why the declaration itself is free-form:
| Expression | Resolves to |
|---|---|
{ "ref": "LogicalId" } | that resource's physical_resource_id, after it is created |
{ "param": "Name" } | the value of a declared parameter |
{ "sub": "text ${Name}" } | the string with parameter values interpolated |
A check on a property value holding an expression waits for the deploy, where
it runs on the resolved value; validate and plan check literals only.
A ref also declares a dependency, so ordering is derived rather than stated;
depends_on is there for the ordering a ref does not express.
Deploy a system from a template
has an agent ref its provider and tool before either exists.
Parameters are declared with an optional default, and a parameter without one
must be supplied at deploy time. A parameter's type is string (the default),
number or list; a supplied value is a string that parses to it (a numeric
string, a JSON array), or the deploy is refused with
400 FORMATION_INVALID_PARAMETERS. Mark a sensitive one no_echo, and a value you
want carried across an update use_previous_value — the same idea as
CloudFormation's, declared in the template rather than passed on each call.
Validate, then plan, then deploy
Three calls, in increasing commitment, and the middle one is the one worth building a habit around:
| Call | What it does |
|---|---|
POST …/formations/validate | Parses and type-checks the template. Creates nothing. |
POST …/formations/plan | Says what a deploy would create, update, replace or delete. Creates nothing. |
POST …/formations / PUT …/formations/{formation_id} | Applies it. |
A plan is what makes an update reviewable: the diff between the template in your branch and the stack in production, before anything moves. Deploy a system from a template plans an instruction change before applying it.
A template can pull a property's text from a file with { file: <relative path> };
the CLI resolves it when the template is passed as @stack.yaml
(values from a file).
Which resource types this API accepts
The template's type is a plain string rather than a fixed list, because the
runtime lets a deployment register its own types. What this deployment accepts
is ai_provider, tool, agent, actor, collection, conversation,
dataset, dataset_item, decider, document, file, guardrail,
ingestion_rule, memory, memory_rule, memory_store, metadata_schema,
model_route, eval, oauth_client, orchestration, playbook, policy, quota, secret,
session, trigger and workflow, plus three naturali registers itself. Every type's properties
are its <Type>ResourceProperties schema in the
formations spec; a write-only property is never stored
with the resource or read back.
An eval, decider, ingestion_rule, memory_rule or playbook requires
policy_ids, the policies its work acts under; an entry may be
{ "ref": "<LogicalId>" } to a policy in the same template. The deployer must
hold every grant they carry, else the resource fails with
POLICY_GRANT_NOT_HELD.
naturali's three are handled by naturali rather than the runtime, and each is documented on its module page:
| Type | Declares | Behavior |
|---|---|---|
channel | A channel | Channels → Formations |
mcp_server | An MCP server | MCP servers → Formations |
webhook | A naturali webhook | Webhooks → Formations |
A naturali_ai_provider is not declarable; a formation holding one releases it
(AI providers → Formations).
A deploy does only what its deployer could do directly. Before naturali
handles a write, the deployer must hold the type's own create, update or
delete action (as its REST route names it, channels:CreateChannel for a
channel) and what its properties carry: agents:CreateAgentGeneration on a
channel's default.agent_id, tools:CallTool on each of an mcp_server's
tools[].tool_id, the read action of each event type a webhook's events
select. Else the resource fails with ACTION_NOT_HELD, naming the
action and resource.
A { "ref_attr": "LogicalId.name" } to one of the three resolves to any of its
string properties as last read, never a credential or a write-only one; a type
whose module page names more attributes resolves those too.
The list is closed. A template naming anything else, including a type
the runtime itself supports, is refused before anything is deployed:
validate answers 200 with
valid: false and the error in errors, and
plan and deploy answer
400 VALIDATION_FAILED. The list is the resource types of the modules this
API serves, so a module arriving here brings its resource type with it, and
one that is not served cannot be reached by declaring it instead of calling
it.
A tool resource's type, and an agent resource's inline tool type, accept
what POST /v1/projects/{project_id}/tools
accepts: any other literal value is 400 VALIDATION_FAILED, with the accepted values
in meta.allowed and the declaration's path in meta.field. A declared
ai_provider is held to the
credential rule a direct create is.
A template naming api_key, chat or project_price is
refused as any other type off the list is, and the refusal is deliberate
rather than an omission.
api_key is the one that matters most: the key it would mint belongs to the
upstream runtime, not to naturali, so anyone holding it would talk to the runtime
directly — outside the project membership, the role checks and everything else
this API enforces on every request. The other two belong to surfaces naturali
serves itself: project_price is the pricing naturali owns for
managed models, and chat overlaps the
channels stack.
Everything api_key, chat and project_price would have done is
still reachable — through API keys and
channels, which are naturali's own routes for the same jobs.
A builtin tool
A builtin tool is declared as the
tools API takes it: a tool with type: builtin, name, the actions it
runs, and optional description and preset_parameters. {ref} on it
resolves to the tool's id, so it binds like any tool:
resources:
Cases:
type: tool
properties:
name: cases
type: builtin
actions: [create-playbook-case, get-playbook-case]
Agent:
type: agent
properties:
name: intake
instructions: Open a case for each new request.
tool_bindings:
- tool_id:
ref: Cases
The deployer must hold each action, whether actions is a literal or an
expression resolved at deploy: one it lacks fails the deploy with
403 ACTION_NOT_HELD. An action this API does not offer is 400.
A computed tag is refused under an iam:RequestTag condition
A resource's tags are checked against the deployer's
policies before anything is resolved. A value computed from a
param, sub or ref is unknown then, so when any condition in those
policies names iam:RequestTag/<key> for that key, the deploy is refused with
403 FORBIDDEN whatever the value resolves to. A literal value is evaluated.
Deleting a resource from the template deletes it for real
Removing a resource from a template and updating the formation deletes the
physical resource. Set deletion_policy: retain on a resource to keep it alive
and only drop it from the stack — the escape hatch for a memory store or a document
whose contents outlive the stack that created it.
An active formation can still carry an error
status and error are usually read together — failed explains itself in
error. One case breaks that pairing: a deploy that replaced a resource,
realised the desired state, and then could not delete the one it superseded. The
formation is active, because what you asked for exists and works, and error
is FORMATION_REPLACE_CLEANUP_FAILED with error.meta.failures naming every
resource still live.
Read it as "applied, with something left over", not as a failure. The superseded resource stays on the formation as pending cleanup and is retried on the next deploy or teardown, which clears the error once it is gone. Nothing references it any more, so it does not affect what the stack does — but it is still a real resource.
So a deploy that checks only status === "active" will call a partial cleanup a
clean success. Check error too.
Events are the deploy log
Every deploy, update and teardown is recorded as an operation, with the plan it
applied and — for a failure — which resource broke it. That history is what
GET …/formations/{formation_id}/events
returns, and it is where a failed status explains itself.
Examples
Plan a template before applying it
- CLI
- SDK
- curl
naturali plan-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--template @stack.yaml
import { readFileSync } from 'node:fs';
const { data: plan } = await naturali.formations.planFormation({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { template: readFileSync('stack.yaml', 'utf8') },
});
console.log(plan?.changes);
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/formations/plan" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile t stack.yaml '{template: $t}')"
Deploy an agent and the tool it calls
The template below is the smallest useful stack: one tool, one agent that has it
bound, and the agent's id as an output. ref is what removes the two-step dance
— the agent is declared before the tool exists, and the runtime fills the id in.
parameters:
ToolToken:
type: string
no_echo: true
resources:
SupportTool:
type: tool
properties:
name: lookup-order
type: http
description: Looks up an order by id
parameters:
type: object
properties:
order_id:
type: string
required:
- order_id
execute:
url: https://api.example.com/orders/{order_id}
headers:
Authorization:
sub: 'Bearer ${ToolToken}'
SupportAgent:
type: agent
properties:
name: support
model: anthropic.claude-sonnet-4-20250514-v1:0
instructions: Answer order questions. Look the order up before answering.
tool_bindings:
- tool_id:
ref: SupportTool
outputs:
agent_id:
ref: SupportAgent
- CLI
- SDK
- curl
naturali create-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-stack \
--template @stack.yaml \
--parameters '{"ToolToken":"tok_live_123"}'
import { readFileSync } from 'node:fs';
const { data: formation } = await naturali.formations.createFormation({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'support-stack',
template: readFileSync('stack.yaml', 'utf8'),
parameters: { ToolToken: 'tok_live_123' },
},
});
console.log(formation?.status, formation?.outputs?.agent_id);
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/formations" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile t stack.yaml \
'{name: "support-stack", template: $t, parameters: {ToolToken: "tok_live_123"}}')"
Apply a changed template to the same stack
Deploying the same stack again is an update, not a second stack: the formation
converges on whatever the template now says. A nullable property the template
omits or sets to null is cleared; a property the update cannot clear refuses
null.
A template read back can be deployed again as read. On an update, and on a plan
naming formation_id, each { "no_echo": true } placeholder takes the stored
value at its path, provided its resource then equals the declaration last
deployed. A resource changed beside a placeholder, a placeholder in a resource
the formation does not hold, and any placeholder on a create are
400 VALIDATION_FAILED. Keep a credential where it stands, or replace it by
sending the value.
- CLI
- SDK
- curl
naturali update-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--formation-id form_V1StGXR8Z5jdHi6B \
--template @stack.yaml
import { readFileSync } from 'node:fs';
const { data: formation } = await naturali.formations.updateFormation({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
formation_id: 'form_V1StGXR8Z5jdHi6B',
},
body: { template: readFileSync('stack.yaml', 'utf8') },
});
console.log(formation?.status);
curl -X PUT \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/formations/form_V1StGXR8Z5jdHi6B" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile t stack.yaml '{template: $t}')"
Read the deploy history
- CLI
- SDK
- curl
naturali list-formation-events \
--project-id proj_V1StGXR8Z5jdHi6B \
--formation-id form_V1StGXR8Z5jdHi6B \
--limit 10
const { data: events } = await naturali.formations.listFormationEvents({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
formation_id: 'form_V1StGXR8Z5jdHi6B',
},
query: { limit: 10 },
});
for (const event of events?.data ?? []) {
console.log(event.operation_type, event.status);
}
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/formations/form_V1StGXR8Z5jdHi6B/events?limit=10" \
-H "Authorization: Bearer $NATURALI_TOKEN"