What Is Multi-Agent Orchestration? Python Guide

Multi-agent orchestration is the practice of coordinating multiple AI agents, each with its own tools, expertise, and scope, so they collaborate on a shared goal through structured handoffs and explicit control flow. Instead of one large agent doing everything, orchestration decomposes a complex task into sub-problems that specialized agents solve in parallel or sequence.

The key word is orchestration: who decides which agent handles what, when control passes from one agent to another, and how results are combined.

Why use multiple agents?

A single ReAct agent with unlimited tools has problems:

Context length: every tool result goes into the same context window
Focus: an agent trying to do everything often does nothing well
Parallelism: sequential tool calls are slow; specialized agents can run in parallel
Cost: a large reasoning model is expensive for simple subtasks

Multiple agents solve these by dividing responsibility: a supervisor decides what to do, specialists execute specific work, results are aggregated at the end.

Orchestration patterns

Supervisor + specialists

A supervisor agent receives the user’s goal and routes to specialist agents:

plaintext

User → Supervisor
           ├── Research agent (web search, summarize)
           ├── Code agent (write and run code)
           └── Writing agent (draft final output)

The supervisor does not do the work. It decomposes and delegates.

Swarm (peer-to-peer handoffs)

Agents hand off to each other directly based on context:

plaintext

User → Customer support agent
           → (escalate) Billing agent
           → (technical) Engineering agent

No central supervisor. Each agent decides when to hand off.

Parallel fan-out

A coordinator dispatches work to multiple agents simultaneously and aggregates results:

plaintext

User query → Coordinator
    ├── Agent A (source 1)    ─┐
    ├── Agent B (source 2)    ─┤→ Aggregator → Final answer
    └── Agent C (source 3)    ─┘

Building multi-agent systems with 10xGraph

Supervisor pattern

SupervisorTeamAgent builds the supervisor internally from a model name and routes among the workers you supply. Each worker is a pre-built Agent wrapped in a WorkerConfig with a description the supervisor uses to choose. Install with pip install "10xgraph[google-genai]".

Python

# Supervisor routing to two specialist workers
from tenxgraph.core import Agent, ToolNode
from tenxgraph.prebuilt.agent import SupervisorTeamAgent, WorkerConfig


def search_web(query: str) -> str:
    """Search the web."""
    return f"Search results for: {query}"


def run_python(code: str) -> str:
    """Execute Python code in a sandbox."""
    return "Output: (execution result)"


team = SupervisorTeamAgent(
    supervisor_model="gemini-2.5-flash",
    workers={
        "RESEARCHER": WorkerConfig(
            agent=Agent(
                model="gemini-2.5-flash",
                provider="google",
                system_prompt=[{"role": "system", "content": "You are a research specialist."}],
                tool_node=ToolNode([search_web]),
            ),
            description="Searches the web and returns factual information.",
        ),
        "CODER": WorkerConfig(
            agent=Agent(
                model="gemini-2.5-flash",
                provider="google",
                system_prompt=[{"role": "system", "content": "You are a coding specialist."}],
                tool_node=ToolNode([run_python]),
            ),
            description="Writes and executes Python code.",
        ),
    },
    max_rounds=8,
)

app = team.compile()

Explicit handoff between agents

For precise control, give each agent handoff tools. A call to transfer_to_<name> routes the graph to that node without running the tool body. See Route between agents with handoff for the full three-agent version.

Python

# Triage agent that can hand off to a billing agent
from tenxgraph.core import Agent, StateGraph, ToolNode
from tenxgraph.core.state import AgentState
from tenxgraph.prebuilt.tools import create_handoff_tool
from tenxgraph.utils import END


def has_tool_calls(state: AgentState) -> bool:
    """Return True if the last message contains tool calls."""
    return bool(state.context and state.context[-1].tools_calls)


triage_tools = ToolNode([create_handoff_tool("billing", "Hand off billing questions.")])

triage_agent = Agent(
    model="gemini-2.5-flash",
    provider="google",
    system_prompt=[{"role": "system", "content": "Triage support requests. Hand off billing questions to billing."}],
    tool_node="triage_tools",
)

billing_agent = Agent(
    model="gemini-2.5-flash",
    provider="google",
    system_prompt=[{"role": "system", "content": "Handle billing questions."}],
)

graph = StateGraph()
graph.add_node("triage", triage_agent)
graph.add_node("triage_tools", triage_tools)
graph.add_node("billing", billing_agent)
graph.set_entry_point("triage")
graph.add_conditional_edges(
    "triage",
    lambda state: "triage_tools" if has_tool_calls(state) else END,
    {"triage_tools": "triage_tools", END: END},
)
graph.add_edge("billing", END)

app = graph.compile()

Orchestration vs single agent

Item	Single agent	Multi-agent
Context window	Shared by all tasks	Scoped per agent
Tool count	Unlimited but noisy	Focused per specialist
Parallelism	Sequential by default	Agents can run in parallel
Debugging	One trace	Per-agent traces
Cost	Same model for all tasks	Cheap model for simple tasks

For most tasks under 10 tool calls, a single ReAct agent is simpler. Move to multi-agent when you hit context limits, need parallel execution, or specialists have meaningfully different capabilities.

Next steps

ReferenceSupervisorTeamAgent referenceConfigure a supervisor agent that routes work to specialist sub-agents.ReferenceSwarmAgent referencePeer agents that hand off to each other based on context.GuideHandoff between agentsHow to implement explicit agent handoffs with the Command primitive.TutorialMulti-agent tutorialA complete example of a multi-agent system with 10xGraph.

Frequently asked questions

What is the difference between a supervisor agent and a swarm?

A supervisor agent has explicit control: it receives the task, decides which agent handles it, and aggregates results. A swarm uses peer-to-peer handoffs: each agent decides whether to handle the request or pass it to a more appropriate peer. Supervisors are easier to debug; swarms are more flexible for open-ended routing.

How do agents share state in a multi-agent system?

In 10xGraph, agents in the same graph share a single AgentState object that flows through the graph. Each agent reads from and writes to this shared state. For agents running in separate graphs, state is passed through the message payload at handoff time.

Can multi-agent systems run agents in parallel?

Yes. 10xGraph's StateGraph supports parallel branches: you can fan out to multiple agent nodes simultaneously and merge results. The graph engine handles concurrent execution via Python's async runtime.

Is multi-agent orchestration the same as LangGraph's multi-agent support?

Both LangGraph and 10xGraph support multi-agent orchestration using graph-based routing. 10xGraph includes the production stack (API server, TypeScript client) needed to deploy these systems without additional configuration. See the 10xGraph vs LangGraph comparison for a detailed breakdown.

When should I use a single agent vs multiple agents?

Use a single agent for tasks with fewer than 10 to 15 tool calls that fit in one context window. Use multiple agents when: the task decomposes naturally into specialist roles, some subtasks can run in parallel, different subtasks need different models (cheap vs powerful), or one agent's context gets too long to reason well.