Multi-Agent Orchestration

Orchestrations let you combine specialized agents into a team. A coordinator agent decides which entity agent should handle each part of a user’s request, enabling complex multi-domain conversations.

Prerequisites:

Two or more agents created (see Build an Agent guide)

Create the orchestration

Define an orchestration with a name and strategy. The supervisor strategy creates a coordinator that delegates to entity agents.Endpoint: POST /api/orchestrations

response = requests.post(
    f"{BASE_URL}/api/orchestrations",
    headers=headers,
    json={
        "name": "Customer Support Team",
        "strategy": "supervisor",
        "orchestrator_config": {
            "additional_instructions": "Route billing questions to the Billing agent and technical questions to the Tech Support agent.",
        },
    },
)
orch = response.json()
orch_id = orch["id"]

Add agents as entities

Add each agent to the orchestration with a role description that helps the coordinator decide when to delegate.Endpoint: POST /api/orchestrations/{id}/entities

# Add billing agent
requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": billing_agent_id,
        "role": "Handles billing, invoices, and payment questions",
    },
)

# Add tech support agent
requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": tech_agent_id,
        "role": "Handles technical issues, bugs, and setup questions",
    },
)

Run the orchestration

Send a message to the orchestration. The coordinator delegates to the appropriate agent. Events include delegation_started and delegation_completed.Endpoint: POST /api/orchestrations/{id}/run/stream

Additional SSE events for orchestrations: delegation_started (agent name + child run ID), delegation_completed (agent name + usage stats).

response = requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/run/stream",
    headers=headers,
    json={"message": "I have a question about my last invoice"},
    stream=True,
)

for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        event = json.loads(text[6:])
        if event["event"] == "delegation_started":
            print(f"Delegating to: {event['agent']}")
        elif event["event"] == "chunk":
            print(event["content"], end="")
        elif event["event"] == "complete":
            print("\nDone.")

What’s Next