--- name: naturali-orchestrate-several-agents description: Chain several naturali.ai agents into one orchestration (researcher, writer, reviewer), start a run and read what each step produced. Use when asked to build a multi-agent pipeline or squad, chain agents in sequence, pass one agent's output to the next, write input_mapping, state_mapping or output_mapping, validate an orchestration, start or poll a run, or read a run's node_executions. license: Apache-2.0 metadata: author: naturali.ai source: https://docs.naturali.ai/docs/tutorials/orchestrate-several-agents --- # Orchestrate several agents Outcome: a `support-reply` orchestration of three agents, each doing one job in order, proven by a `succeeded` run whose record shows the facts, the draft and the checked reply each step produced. ## Before you start - `NATURALI_TOKEN` — a `nat_sk_…` project API key; `PROJECT` — the project id. - `Provider` in `naturali.yaml`, from `naturali-enable-naturali-models` or `naturali-bring-your-own-model-key`, deployed as `$FORMATION` with `naturali-deploy-a-formation`. - Every agent node is one generation: this pipeline counts as three runs against the plan's monthly allowance, and its managed tokens draw on the balance. A run never starts while the project owes for usage already served (`402 insufficient_credit`). Ids below are examples; use the ones your own calls return. ## 1. Declare the three agents Each agent does one job and reads only what the step before handed over. An agent node receives its inputs as **one user message, one `key: value` line per input**, so the instructions name the inputs they expect. Add to `naturali.yaml` (agent mechanics in `naturali-create-an-agent`): ```yaml resources: Researcher: type: agent properties: name: support-researcher ai_provider_id: { ref: Provider } instructions: You receive a customer question and a policy. List, as short bullet points, only the policy facts that answer the question. Writer: type: agent properties: name: support-writer ai_provider_id: { ref: Provider } instructions: You receive a customer question and a list of facts. Write a friendly reply of at most three sentences that uses only those facts. Reviewer: type: agent properties: name: support-reviewer ai_provider_id: { ref: Provider } instructions: You receive facts and a draft reply. Return the draft, corrected so it states nothing the facts do not support. Return only the reply text, without quotes. outputs: researcher_id: { ref: Researcher } writer_id: { ref: Writer } reviewer_id: { ref: Reviewer } ``` Apply it with `naturali-deploy-a-formation` and export the ids from `outputs`: ```bash export RESEARCHER=agent_lBSeFLo1Z4NgQlm0 export WRITER=agent_VOJ1cafUEXZnR8ut export REVIEWER=agent_iKQR3K4ivAFcVSzC ``` - Without a formation (only when the user asks): `POST …/agents` per agent with the same properties (CLI `naturali create-agent` · SDK `naturali.agents.createAgent`). ## 2. Validate the pipeline `nodes` say what each step does, `edges` what follows what. In an `agent` node: - `input_mapping` — what the agent receives; each value is JSON Logic over the run's state. `input.question` is the run's input; bare `facts` is what an earlier node wrote. - `state_mapping` — where the answer goes; `output.content` is the agent's text reply. The formation validate only type-checks properties; this call checks the graph itself without saving it — an edge to a missing node, a `var` no step writes, a node missing a field its type needs. CLI `naturali validate-orchestration` · SDK `naturali.orchestrations.validateOrchestration` ```bash curl -X POST "https://api.naturali.ai/v1/projects/$PROJECT/orchestrations/validate" \ -H "Authorization: Bearer $NATURALI_TOKEN" \ -H "Content-Type: application/json" \ -d @- <