Multi-Agent Orchestration

What is an Orchestration?

An Orchestration is a container that groups multiple agents (entities) and runs them using a coordination strategy. Each entity agent has its own system prompt, tools, and knowledge bases, and the orchestration handles how they interact. You choose a strategy that matches your use case: Supervisor for autonomous delegation, Sequential for pipeline processing, or Parallel for concurrent execution with merged results.

Execution Strategies

Strategy	Pattern	How It Works	Best For
supervisor	Coordinator delegates	Multi-domain support (billing + tech + sales), complex routing, dynamic task decomposition
sequential	Pipeline	Entity agents run in order (sorted by position). Each agent receives the previous agent’s output as its input. The final agent’s output is the orchestration result.	Multi-stage processing: extract → analyze → summarize → format
parallel	Fan-out + merge	All entity agents run concurrently on the same input. If multiple agents produce results, a merge agent (gpt-4.1-mini) combines them into a single coherent response.	Independent analysis from multiple perspectives, parallel research tasks

Supervisor Strategy

The Supervisor strategy creates a coordinator agent that has access to a delegation tool for each entity agent. When a user message arrives, the coordinator reasons about which entity should handle it and calls the appropriate delegate_to_ tool with a task description. The entity agent runs with its own tools and knowledge bases (up to 10 ReAct steps by default) and returns its result. The coordinator can delegate to several entities in sequence, or feed the result of one delegation into the next. Its own ReAct loop runs for up to 25 steps.

Orchestration flow: User → Coordinator → delegates to Agent A and Agent B → results merge → Coordinator synthesizes → Final Response. — Supervisor strategy: coordinator delegates to specialized agents

Each delegation creates a child execution context with an incremented depth (max depth: 3, preventing infinite recursive delegation). The child context gets a budget allocation from the parent’s remaining token budget. Entity agents share the parent’s abort signal, so cancelling the orchestration cancels all active entity runs. The coordinator’s system prompt is auto-generated from the entity role descriptions. Write specific, non-overlapping role descriptions to help the coordinator make clear routing decisions. “Handles billing inquiries, invoices, and payment issues” routes better than “Handles customer questions.”

Sequential Strategy

The Sequential strategy runs entity agents one after another in position order. The first agent receives the user’s message as input. Each subsequent agent receives the previous agent’s output as its input. If any agent in the chain fails, the entire orchestration fails immediately. This is ideal for multi-stage processing pipelines where each stage transforms or enriches the data.

Example: Document processing pipelineAgent 1 (Extractor): extracts key facts from a document. Agent 2 (Analyzer): identifies risks and opportunities from the extracted facts. Agent 3 (Writer): produces a formatted executive summary from the analysis.

Parallel Strategy

The Parallel strategy runs all entity agents concurrently on the same input using a thread pool. Each agent processes the user’s message independently with its own tools and knowledge bases. If there is only one entity, its output is returned directly. If there are multiple entities, after all agents complete, a merge agent (gpt-4.1-mini by default, configurable via orchestration settings) combines their outputs into a single coherent response. If any agent fails, the entire orchestration fails.

Entity Configuration

Each entity in an orchestration has a role description and optional configuration. The role description is critical for the Supervisor strategy, since it tells the coordinator what the entity specializes in. For Sequential and Parallel, the role is descriptive metadata. Entity config can override max_steps (default 10) to control how many ReAct iterations the entity agent runs.

# Create an orchestration with the supervisor strategy
response = requests.post(
    f"{BASE_URL}/api/orchestrations",
    headers=headers,
    json={
        "name": "Customer Support Team",
        "strategy": "supervisor",
    },
)
orch = response.json()
orch_id = orch["id"]

# Add entity agents with clear role descriptions
requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": billing_agent_id,
        "role": "Handles billing inquiries, invoices, payments, and refund requests",
    },
)

requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": tech_agent_id,
        "role": "Handles technical issues, API errors, integration problems, and setup questions",
    },
)

// Create an orchestration with the supervisor strategy
const orchRes = await fetch(`${BASE_URL}/api/orchestrations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Customer Support Team",
    strategy: "supervisor",
  }),
});
const orch = await orchRes.json();

// Add entity agents with clear role descriptions
await fetch(`${BASE_URL}/api/orchestrations/${orch.id}/entities`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agent_id: billingAgentId,
    role: "Handles billing inquiries, invoices, payments, and refund requests",
  }),
});

await fetch(`${BASE_URL}/api/orchestrations/${orch.id}/entities`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agent_id: techAgentId,
    role: "Handles technical issues, API errors, integration problems, and setup questions",
  }),
});

# Create orchestration
curl -X POST '{BASE_URL}/api/orchestrations' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support Team", "strategy": "supervisor"}'

# Add billing agent entity
curl -X POST '{BASE_URL}/api/orchestrations/{orch_id}/entities' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "{billing_agent_id}", "role": "Handles billing inquiries, invoices, and payments"}'

Streaming Events

Orchestration streaming exposes the full execution flow via SSE. For the Supervisor strategy, you see delegation events as the coordinator routes tasks to entities. For Sequential, you see step events as each agent runs. For Parallel, events from concurrent agents may interleave.

Event	Description
start	Orchestration run started — includes run_id and session_id
orchestration_started	Execution has begun with the configured strategy
delegation_started	Supervisor: coordinator is delegating a task to an entity agent
delegation_completed	Supervisor: entity agent finished its subtask
sequential_step	Sequential: an agent in the pipeline has started/completed
tool_call / tool_result	An entity agent is calling/receiving a tool
chunk	Text chunk from the final response
complete	Orchestration run finished — includes content, usage, steps
error	An error occurred during execution

Limits

Constraint	Default	Notes
Coordinator max steps	25	Supervisor strategy: how many ReAct steps the coordinator gets
Entity max steps	10	Per-entity ReAct step limit, configurable in entity config
Max orchestration depth	3	Prevents recursive delegation loops (coordinator → entity → sub-delegation)
Parallel merge model	gpt-4.1-mini	Configurable via orchestration settings. Used to combine parallel agent outputs.

Next Steps

Orchestration Guide

Create an orchestration and run it step by step.

Agents & Tools

Understand the ReAct loop and tool system that powers each entity.

Workflows

For deterministic multi-step pipelines, use workflows instead.

Orchestrations API Reference

Full endpoint documentation.

Getting Started

Concepts

Guides

API Reference

Multi-Agent Orchestration

What is an Orchestration?

Execution Strategies

Supervisor Strategy

Sequential Strategy

Parallel Strategy

Entity Configuration

Streaming Events

Limits

Next Steps

Orchestration Guide

Agents & Tools

Workflows

Orchestrations API Reference

​What is an Orchestration?

​Execution Strategies

​Supervisor Strategy

​Sequential Strategy

​Parallel Strategy

​Entity Configuration

​Streaming Events

​Limits

​Next Steps

Orchestration Guide

Agents & Tools

Workflows

Orchestrations API Reference

What is an Orchestration?

Execution Strategies

Supervisor Strategy

Sequential Strategy

Parallel Strategy

Entity Configuration

Streaming Events

Limits

Next Steps