Skip to main content

Deploy a Multi-Agent App with Agent Formation

This tutorial builds the same multi-agent orchestration pipeline from Multi-Agent Sonnet with Nested Agent Calls — an orchestrator agent that delegates sonnet stanzas to four specialized sub-agents — but deploys the entire system with a single Agent Formation template instead of many ordered API calls.

You will write a template describing all 14 resources, validate and preview it, deploy it in one call, run the orchestrator, update the formation, and delete it.

Prerequisites​

  • SOAT running locally. Follow the Quick Start guide to bring the stack up with Docker Compose.
  • New to SOAT? Read Key Concepts to understand projects, agents, and sessions before diving in.
  • Want to see the same pipeline built step by step? Read Multi-Agent Sonnet with Nested Agent Calls first.
  • CLI installed and configured, or SDK set up. See CLI or SDK.
  • For production hardening (secrets, env vars), see Configuration.
  • Ollama running locally with qwen2.5:0.5b pulled (ollama pull qwen2.5:0.5b).
  • Server is at http://localhost:5047.
export SOAT_BASE_URL=http://localhost:5047

Step 1 — Log in as admin​

Admin is the built-in superuser. See Users for full authentication details.

ADMIN_TOKEN=$(soat login-user --username admin --password Admin1234! | jq -r '.token')
export SOAT_TOKEN=$ADMIN_TOKEN

Step 2 — Create a project​

All resources are scoped to a project.

PROJECT_ID=$(soat create-project --name 'Sonnet Workshop' | jq -r '.id')
echo "PROJECT_ID: $PROJECT_ID"

Step 3 — Write the formation template​

A formation template is a JSON object with a resources map and an optional outputs map. This template defines all 14 resources of the sonnet pipeline — an Ollama provider, a shared poem document, read/write tools, four stanza agents, five orchestrator tools, and the orchestrator. SOAT resolves { "ref": "logicalId" } expressions in dependency order, so tool_bindings[].tool_id, ai_provider_id, and nested preset_parameters.agentId are wired automatically.

This tutorial uses a local Ollama provider so it can run without external credentials. To connect xAI, OpenAI, Anthropic, or Amazon Bedrock instead, see Connect Third-Party LLMs.

cat > formation.json << 'EOF'
{
  "resources": {
    "provider": {
      "type": "ai_provider",
      "properties": {
        "name": "Sonnet Ollama",
        "provider": "ollama",
        "default_model": "qwen2.5:0.5b"
      }
    },
    "poemDoc": {
      "type": "document",
      "properties": {
        "content": "(empty - will be overwritten by stanza agents)",
        "path": "/poems/sonnet.txt"
      }
    },
    "poemReadTool": {
      "type": "tool",
      "properties": {
        "name": "poem-read",
        "type": "builtin",
        "description": "Read the shared poem document",
        "actions": ["get-document"],
        "preset_parameters": { "document_id": { "ref": "poemDoc" } }
      }
    },
    "poemWriteTool": {
      "type": "tool",
      "properties": {
        "name": "poem-write",
        "type": "builtin",
        "description": "Update the shared poem document",
        "actions": ["update-document"],
        "preset_parameters": { "document_id": { "ref": "poemDoc" } }
      }
    },
    "stanza1Agent": {
      "type": "agent",
      "properties": {
        "name": "Stanza 1 - First Quatrain",
        "ai_provider_id": { "ref": "provider" },
        "instructions": "You are deterministic stanza worker 1. Do exactly two tool calls: first poem-read, then poem-write. Never ask follow-up questions. Write the poem title on the first line, add a blank line, then write the FIRST quatrain (4 lines) using ABAB. In poem-write, set content to the full poem-so-far including your stanza.",
        "tool_bindings": [{ "tool_id": { "ref": "poemReadTool" } }, { "tool_id": { "ref": "poemWriteTool" } }],
        "step_rules": [
          { "step": 1, "tool_choice": { "type": "tool", "tool_name": "poem-read_get-document" } },
          { "step": 2, "tool_choice": { "type": "tool", "tool_name": "poem-write_update-document" } }
        ],
        "max_steps": 5
      }
    },
    "stanza2Agent": {
      "type": "agent",
      "properties": {
        "name": "Stanza 2 - Second Quatrain",
        "ai_provider_id": { "ref": "provider" },
        "instructions": "You are deterministic stanza worker 2. Do exactly two tool calls: first poem-read, then poem-write. Never ask follow-up questions. Write the SECOND quatrain (4 lines) using CDCD. In poem-write, set content to the full poem-so-far including your stanza.",
        "tool_bindings": [{ "tool_id": { "ref": "poemReadTool" } }, { "tool_id": { "ref": "poemWriteTool" } }],
        "step_rules": [
          { "step": 1, "tool_choice": { "type": "tool", "tool_name": "poem-read_get-document" } },
          { "step": 2, "tool_choice": { "type": "tool", "tool_name": "poem-write_update-document" } }
        ],
        "max_steps": 5
      }
    },
    "stanza3Agent": {
      "type": "agent",
      "properties": {
        "name": "Stanza 3 - Third Quatrain",
        "ai_provider_id": { "ref": "provider" },
        "instructions": "You are deterministic stanza worker 3. Do exactly two tool calls: first poem-read, then poem-write. Never ask follow-up questions. Write the THIRD quatrain (4 lines) using EFEF. In poem-write, set content to the full poem-so-far including your stanza.",
        "tool_bindings": [{ "tool_id": { "ref": "poemReadTool" } }, { "tool_id": { "ref": "poemWriteTool" } }],
        "step_rules": [
          { "step": 1, "tool_choice": { "type": "tool", "tool_name": "poem-read_get-document" } },
          { "step": 2, "tool_choice": { "type": "tool", "tool_name": "poem-write_update-document" } }
        ],
        "max_steps": 5
      }
    },
    "stanza4Agent": {
      "type": "agent",
      "properties": {
        "name": "Stanza 4 - Final Couplet",
        "ai_provider_id": { "ref": "provider" },
        "instructions": "You are deterministic stanza worker 4. Do exactly two tool calls: first poem-read, then poem-write. Never ask follow-up questions. Write the FINAL couplet (2 lines) using GG. In poem-write, set content to the full poem-so-far including your couplet.",
        "tool_bindings": [{ "tool_id": { "ref": "poemReadTool" } }, { "tool_id": { "ref": "poemWriteTool" } }],
        "step_rules": [
          { "step": 1, "tool_choice": { "type": "tool", "tool_name": "poem-read_get-document" } },
          { "step": 2, "tool_choice": { "type": "tool", "tool_name": "poem-write_update-document" } }
        ],
        "max_steps": 5
      }
    },
    "callStanza1Tool": {
      "type": "tool",
      "properties": {
        "name": "call-stanza-1",
        "type": "builtin",
        "description": "Call stanza 1 agent",
        "actions": ["create-agent-generation"],
        "preset_parameters": {
          "agent_id": { "ref": "stanza1Agent" },
          "messages": [{ "role": "user", "content": "Theme: artificial intelligence. Write stanza 1 with title + first quatrain." }]
        }
      }
    },
    "callStanza2Tool": {
      "type": "tool",
      "properties": {
        "name": "call-stanza-2",
        "type": "builtin",
        "description": "Call stanza 2 agent",
        "actions": ["create-agent-generation"],
        "preset_parameters": {
          "agent_id": { "ref": "stanza2Agent" },
          "messages": [{ "role": "user", "content": "Theme: artificial intelligence. Write stanza 2 (second quatrain)." }]
        }
      }
    },
    "callStanza3Tool": {
      "type": "tool",
      "properties": {
        "name": "call-stanza-3",
        "type": "builtin",
        "description": "Call stanza 3 agent",
        "actions": ["create-agent-generation"],
        "preset_parameters": {
          "agent_id": { "ref": "stanza3Agent" },
          "messages": [{ "role": "user", "content": "Theme: artificial intelligence. Write stanza 3 (third quatrain)." }]
        }
      }
    },
    "callStanza4Tool": {
      "type": "tool",
      "properties": {
        "name": "call-stanza-4",
        "type": "builtin",
        "description": "Call stanza 4 agent",
        "actions": ["create-agent-generation"],
        "preset_parameters": {
          "agent_id": { "ref": "stanza4Agent" },
          "messages": [{ "role": "user", "content": "Theme: artificial intelligence. Write stanza 4 (final couplet)." }]
        }
      }
    },
    "readFinalPoemTool": {
      "type": "tool",
      "properties": {
        "name": "read-final-poem",
        "type": "builtin",
        "description": "Read the final poem from the shared document",
        "actions": ["get-document"],
        "preset_parameters": { "document_id": { "ref": "poemDoc" } }
      }
    },
    "orchestrator": {
      "type": "agent",
      "properties": {
        "name": "Sonnet Orchestrator",
        "ai_provider_id": { "ref": "provider" },
        "instructions": "Call tools in this exact order: call-stanza-1, call-stanza-2, call-stanza-3, call-stanza-4, then read-final-poem. Do not ask follow-up questions. Return ONLY the poem text.",
        "tool_bindings": [
          { "tool_id": { "ref": "callStanza1Tool" } },
          { "tool_id": { "ref": "callStanza2Tool" } },
          { "tool_id": { "ref": "callStanza3Tool" } },
          { "tool_id": { "ref": "callStanza4Tool" } },
          { "tool_id": { "ref": "readFinalPoemTool" } }
        ],
        "step_rules": [
          { "step": 1, "tool_choice": { "type": "tool", "tool_name": "call-stanza-1_create-agent-generation" } },
          { "step": 2, "tool_choice": { "type": "tool", "tool_name": "call-stanza-2_create-agent-generation" } },
          { "step": 3, "tool_choice": { "type": "tool", "tool_name": "call-stanza-3_create-agent-generation" } },
          { "step": 4, "tool_choice": { "type": "tool", "tool_name": "call-stanza-4_create-agent-generation" } },
          { "step": 5, "tool_choice": { "type": "tool", "tool_name": "read-final-poem_get-document" } }
        ],
        "max_steps": 8
      }
    }
  },
  "outputs": {
    "orchestrator_id": { "ref": "orchestrator" },
    "poem_doc_id": { "ref": "poemDoc" }
  }
}
EOF
TEMPLATE=$(cat formation.json)

Step 4 — Validate the template​

Validate the template structure before doing anything else. See Formations for validation rules.

soat validate-formation --template "$TEMPLATE"

Expected output:

{ "valid": true }

Step 5 — Preview the deployment plan​

Preview the changes SOAT will make before deploying. The plan lists all resources that will be created. See Formations.

soat plan-formation --project_id "$PROJECT_ID" --template "$TEMPLATE" | jq '.'

Expected output — 14 resources all marked as create:

[
  { "action": "create", "logical_id": "provider", "type": "ai_provider" },
  { "action": "create", "logical_id": "poemDoc", "type": "document" },
  { "action": "create", "logical_id": "poemReadTool", "type": "tool" },
  { "action": "create", "logical_id": "poemWriteTool", "type": "tool" },
  { "action": "create", "logical_id": "stanza1Agent", "type": "agent" },
  { "action": "create", "logical_id": "stanza2Agent", "type": "agent" },
  { "action": "create", "logical_id": "stanza3Agent", "type": "agent" },
  { "action": "create", "logical_id": "stanza4Agent", "type": "agent" },
  { "action": "create", "logical_id": "callStanza1Tool", "type": "tool" },
  { "action": "create", "logical_id": "callStanza2Tool", "type": "tool" },
  { "action": "create", "logical_id": "callStanza3Tool", "type": "tool" },
  { "action": "create", "logical_id": "callStanza4Tool", "type": "tool" },
  {
    "action": "create",
    "logical_id": "readFinalPoemTool",
    "type": "tool"
  },
  { "action": "create", "logical_id": "orchestrator", "type": "agent" }
]

Step 6 — Deploy the formation​

Create the formation. SOAT provisions all 14 resources in dependency order; the outputs section surfaces the orchestrator and poem document IDs. See Formations.

FORMATION=$(soat create-formation \
  --project_id "$PROJECT_ID" \
  --name "sonnet-workshop" \
  --template "$TEMPLATE")

FORMATION_ID=$(printf '%s' "$FORMATION" | jq -r '.id')
ORCHESTRATOR_ID=$(printf '%s' "$FORMATION" | jq -r '.outputs.orchestrator_id')
POEM_DOC_ID=$(printf '%s' "$FORMATION" | jq -r '.outputs.poem_doc_id')

echo "FORMATION_ID:    $FORMATION_ID"
echo "ORCHESTRATOR_ID: $ORCHESTRATOR_ID"
echo "POEM_DOC_ID:     $POEM_DOC_ID"

The formation object includes a resources map keyed by logical ID, each with its physical resource ID. You can inspect the full resource manifest:

soat get-formation --formation_id "$FORMATION_ID" | jq '{id, name, status, outputs}'

Step 7 — Run the orchestrator​

Trigger the orchestrator agent to run the full sonnet pipeline. The orchestrator calls each stanza agent in order via its fixed tools. See Agents — Generation.

RESULT=$(soat create-agent-generation --wait true \
  --agent-id "$ORCHESTRATOR_ID" \
  --messages '[{"role":"user","content":"Write a sonnet about the theme: artificial intelligence"}]')

printf '%s\n' "$RESULT" | jq '{status, trace_id}'
TRACE_ID=$(printf '%s\n' "$RESULT" | jq -r '.trace_id')

Expected output:

{
  "status": "completed",
  "trace_id": "trace_xxxxxxxxxxxx"
}

Step 8 — Read the poem document​

The stanza agents accumulated the sonnet in the shared poem document. Read it directly from the Documents store.

soat get-document --document-id "$POEM_DOC_ID" | jq -r '.content'

Expected output — a complete Shakespearean sonnet:

Silicon Dreams

In circuits bright where human thought takes form,
A mind emerges from the data's flow,
It learns through storms and weathers every storm,
And seeds of knowledge in its memory grow.

With second quatrain lines that build and rise,
Each layer deep connects what came before,
It reads the world through countless digital eyes,
And writes new knowledge, always seeking more.

Now in the third quatrain, patterns found
In vast arrays of numbers, text and light,
The third quatrain concludes with solid ground,
Where artificial minds approach their height.

And in this final couplet two lines close,
Where silicon and thought in union flows.

Step 9 — Inspect the trace tree​

The /tree endpoint returns the full execution tree rooted at the orchestrator trace. Each node is a trace record, and its children array contains the traces spawned by sub-agent tool calls.

soat get-trace-tree --trace-id "$TRACE_ID" | jq '{id, step_count, children_count: (.children | length)}'

Expected output — the orchestrator at the root with 4 stanza workers as children:

{
  "id": "trace_xxxxxxxxxxxx",
  "step_count": 5,
  "children_count": 4
}

List all traces for the project to see every agent that ran:

soat list-traces --project-id "$PROJECT_ID" | jq '.data[] | {id, agent_id, step_count, parent_trace_id}'

The orchestrator trace has parent_trace_id: null; each stanza worker trace references the orchestrator's trace ID as its parent.

Step 10 — Update the formation​

Supply a modified template; SOAT diffs it against the current state and applies only the required changes. Here we update the orchestrator's instructions. See Formations.

UPDATED_TEMPLATE=$(printf '%s' "$TEMPLATE" | jq \
  '.resources.orchestrator.properties.instructions = "Call tools in this exact order: call-stanza-1, call-stanza-2, call-stanza-3, call-stanza-4, then read-final-poem. Do not ask follow-up questions. Return ONLY the poem text. Focus on vivid imagery."')

soat update-formation \
  --formation_id "$FORMATION_ID" \
  --template "$UPDATED_TEMPLATE" | jq '{id, status}'

Step 11 — View operation events​

Each formation deployment and update appends events to the formation's event log. Use this to audit exactly which resources were created, updated, or deleted and in what order. See Formations.

soat list-formation-events --formation_id "$FORMATION_ID" | jq '.data[] | {operation_type, status}'

Expected output — one entry per deployment operation:

{ "operation_type": "create", "status": "succeeded" }
{ "operation_type": "update", "status": "succeeded" }

Step 12 — Delete the formation​

Deleting a formation removes managed resources in reverse dependency order — but it will not delete resources the platform guards on their own. This stack has four agents, and running the sonnet above gave each of them generation history, so teardown stops there rather than destroying that history implicitly. The delete fails with 409 FORMATION_DELETE_FAILED, naming every blocking resource in error.meta.failures, and leaves the formation in delete_failed. See Formations — Resource Lifecycle.

# → expect-fail
soat delete-formation --formation_id "$FORMATION_ID"

# The stack is left in delete_failed, with everything up to the agents removed.
soat get-formation --formation_id "$FORMATION_ID" | jq '{id, status}'

To finish the teardown, resolve the blockers and delete the formation again. For an agent that means deciding explicitly to discard its history — soat delete-agent --agent-id "$AGENT_ID" --force true — which is why teardown does not do it for you. Declare an agent with deletion_policy: retain if the stack should leave it standing instead.

Next Steps​