Scenario: Build a Multi-Agent Supervisor

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

This scenario shows the current supported supervisor pattern:

a parent agent step acts as the coordinator
the parent agent calls the built-in spawn_subagent tool
child flows run as subagents and produce their own execution evidence

What You’ll Build

A Support Supervisor workflow that:

receives a user question
decides which specialist child flow to invoke
can invoke multiple child flows during the same reasoning loop
returns a unified answer
preserves parent/child execution linkage in evidence

Prerequisites

completed Build an Autonomous Agent
an active release with model_policy and policy_bundle
optional guardrail_config if you want safety controls on agent goals and responses

Step 1: Create The Specialist Child Flows

These child flows are ordinary flow assets. They do not need custom supervisor syntax.

Knowledge Specialist


name: Knowledge Specialist
description: Answer knowledge-base questions
trigger:
  type: manual
entry_step: respond
steps:
  - id: respond
    type: return
    output:
      summary: "Knowledge specialist placeholder result"

Data Specialist


name: Data Specialist
description: Answer reporting or analytics questions
trigger:
  type: manual
entry_step: respond
steps:
  - id: respond
    type: return
    output:
      summary: "Data specialist placeholder result"

Create them:


orqestractl flow create --slug knowledge-specialist --owner team:support --file knowledge.yaml
orqestractl flow create --slug data-specialist --owner team:support --file data.yaml

In a real workload, those child flows can contain llm_call, task, retrieval, or other supported steps.

Step 2: Create The Supervisor Flow

The supervisor is a normal agent step whose tool list includes spawn_subagent:


name: Support Supervisor
description: Route customer questions to specialist child flows
 
trigger:
  type: api_request
  inputs_schema:
    type: object
    required: [query]
    properties:
      query:
        type: string
 
observability:
  trace_all: true
  metrics: [latency, token_count, cost]
 
entry_step: coordinate
 
steps:
  - id: coordinate
    type: agent
    goal: "Coordinate the user request: {{trigger.query}}"
    system_prompt: |
      You are a support supervisor.
      Use spawn_subagent with flow_ref=knowledge-specialist for policy,
      product, or procedure questions.
      Use spawn_subagent with flow_ref=data-specialist for reporting,
      metrics, or account-analysis questions.
      If both are needed, you may call both before answering.
    tools:
      - spawn_subagent
    max_iterations: 6
    next: respond
 
  - id: respond
    type: return
    output:
      answer: "{{steps.coordinate.output.content}}"
      tools_called: "{{steps.coordinate.output.tools_called}}"
      turns_used: "{{steps.coordinate.output.turns_used}}"

Create it:


orqestractl flow create --slug support-supervisor --owner team:support --file supervisor.yaml

Step 3: Create The Workload And Release


orqestractl workload create --slug support-hub --owner team:support
orqestractl release create --workload $WORKLOAD_ID --environment production

Bind the release:


orqestractl release bind $RELEASE_ID --asset-version $SUPERVISOR_FLOW_V1 --role orchestration_flow
orqestractl release bind-model-policy $RELEASE_ID --asset-version $MODEL_POLICY_V1
orqestractl release bind $RELEASE_ID --asset-version $POLICY_V1 --role policy_bundle

Optional:


orqestractl release bind $RELEASE_ID --asset-version $GUARDRAIL_V1 --role guardrail_config

Promote the release:


orqestractl release transition $RELEASE_ID --to review_ready
orqestractl release transition $RELEASE_ID --to approved
orqestractl release transition $RELEASE_ID --to active

Step 4: Test The Supervisor

Try prompts such as:

What is our return policy?
How many open support tickets do we have?
Explain our escalation process and current backlog.

The supervisor agent will decide whether to call one or more child flows through spawn_subagent.

Step 5: Inspect Parent/Child Evidence


orqestractl execution get $EXECUTION_ID --format json

Look for:

tools_called containing spawn_subagent
reasoning trace entries showing the subagent calls
child executions linked to the parent execution
merged evidence and retrieval events from child flows

What You Learned

the current supervisor pattern uses spawn_subagent, not custom nested subagents flow syntax
child flows are ordinary flow assets
multi-agent orchestration remains governed because the parent release still controls model, policy, and optional guardrail context