Skip to main content

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 cannot declare past a plan

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​

FieldTypeDescription
idstringPublic ID of the formation
project_idstringProject public ID
namestringHuman-readable formation name
templateobjectThe 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.
outputsobject, nullableResolved output values after stack deployment. An output that resolved a credential attribute on a formation deployed before those were refused is omitted.
statuscreating | active | updating | failed | deleting | deleted | delete_failedFormation status
metadataobjectStatic 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_metadataobject, nullableThe 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_parametersobject, nullableParameter values applied at the last deploy, for auditability. no_echo parameters are masked (***). Null when the template declares no parameters.
errorobject, nullableWhy 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.
resourcesobject[]Resources managed by this formation (present on get/create/update)
created_atstring (date-time)
updated_atstring (date-time)

name is unique per project: reusing one is a 409.

FormationResource​

FieldTypeDescription
idstringPublic ID of the resource record
logical_idstringLogical identifier from the template
resource_typestringResource type (e.g. agent, memory_store)
physical_resource_idstring, nullablePublic ID of the physical resource
statuspending | created | updated | deleted | failedCurrent 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:

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

CallWhat it does
POST …/formations/validateParses and type-checks the template. Creates nothing.
POST …/formations/planSays 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:

TypeDeclaresBehavior
channelA channelChannels → Formations
mcp_serverAn MCP serverMCP servers → Formations
webhookA naturali webhookWebhooks → 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.

Some of the runtime's own types are not available here

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​

naturali plan-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--template @stack.yaml

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
naturali create-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-stack \
--template @stack.yaml \
--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.

naturali update-formation \
--project-id proj_V1StGXR8Z5jdHi6B \
--formation-id form_V1StGXR8Z5jdHi6B \
--template @stack.yaml

Read the deploy history​

naturali list-formation-events \
--project-id proj_V1StGXR8Z5jdHi6B \
--formation-id form_V1StGXR8Z5jdHi6B \
--limit 10
  • Agents and Tools — what a stack usually declares.
  • Projects — the boundary a formation deploys inside.
  • Secrets — where a credential a template references should live.
  • Triggers — how a declared stack starts doing work on its own.