Multi-Agent Orchestration

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

The current multi-agent pattern in Orqestra is built around:

• a parent agent step
• the built-in spawn_subagent tool
• child flows executed as separate subagent runs

This keeps multi-agent orchestration inside the normal release, policy, evidence, and runtime-control model. A child agent is not an unmanaged worker; it is a child flow execution with inherited workload, release, actor, workspace, and governance context.

Supported Pattern

User request
  -> parent agent reasons about the task
    -> parent agent calls spawn_subagent(flow_ref=...)
      -> child flow executes
        -> child result returns to parent agent
          -> parent agent decides whether to call another child or finish

This is the current supported supervisor model. Older examples that define subagents, routing, aggregation, or shared-memory blocks directly inside the flow step are not the current runtime contract.

spawn_subagent Arguments

The parent agent must include spawn_subagent in its tool list when a tools allowlist is present.

Agent Types

Use the narrowest archetype that fits the specialist’s job.

Parent Agent Example

steps:
  - id: supervisor
    type: agent
    goal: "Coordinate the request: {{trigger.query}}"
    system_prompt: |
      You are a supervisor agent.
      Call spawn_subagent with flow_ref=knowledge-specialist for policy or
      documentation questions.
      Call spawn_subagent with flow_ref=data-specialist for reporting or
      analytics questions.
      You may call more than one child flow before answering.
    tools:
      - spawn_subagent
    max_iterations: 6
    next: respond
 
  - id: respond
    type: return
    output:
      answer: "{{steps.supervisor.output.content}}"
      tools_called: "{{steps.supervisor.output.tools_called}}"

Child Flow Example

Child flows are ordinary flow assets:

name: Knowledge Specialist
description: Answer documentation questions
trigger:
  type: manual
entry_step: done
steps:
  - id: done
    type: return
    output:
      summary: "Knowledge specialist result"

What Happens At Runtime

When the parent agent calls spawn_subagent:

• the runtime fetches the child flow by flow_ref
• the child execution inherits the parent workload and release context
• the child execution inherits actor, organization, namespace, and workspace context
• runtime controls such as pause, kill, checkpointing, cancellation, hooks, and budget checks are passed through
• child evidence artifacts and retrieval events are merged back into the parent
• parent/child execution linkage is preserved
• a subagent_spawn evidence artifact is recorded on the parent

This makes multi-agent behavior observable rather than opaque.

Control Outcomes

If the child flow stops with a terminal control outcome, the parent tool call surfaces that outcome instead of pretending the child succeeded.

This is why child flows should return structured output through a return step and let runtime controls remain runtime controls.

When To Use It

Use the multi-agent pattern when:

• one agent should coordinate several specialist workflows
• you want child executions with their own evidence trails
• you need the parent agent to decide dynamically which specialists to use

Avoid it when a simple task, llm_call, or subflow step is sufficient.

Best Practices

Use child flows as the specialist boundary. Keep specialists as plain flows instead of inventing custom nested supervisor config.

Whitelist spawn_subagent deliberately. If the parent agent declares a tools list, include spawn_subagent explicitly.

Keep specialist responsibilities narrow. Routing works best when each child flow has a crisp purpose.

Inspect parent and child evidence together. The operational value of this pattern is that it stays governed and traceable even when orchestration becomes agentic.

Keep subflow depth bounded. Runtime subflow and subagent execution has a maximum depth to prevent accidental recursion.

Troubleshooting