> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-orgrol-1766173255-e2d754f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-agent

Multi-agent systems coordinate specialized components to tackle complex workflows. However, not every complex task requires this approach — a single agent with the right (sometimes dynamic) tools and prompt can often achieve similar results.

## Why multi-agent?

When developers say they need "multi-agent," they're usually looking for one or more of these capabilities:

* <Icon icon="brain" /> **Context management**: Provide specialized knowledge without overwhelming the model's context window. If context were infinite and latency zero, you could dump all knowledge into a single prompt — but since it's not, you need patterns to selectively surface relevant information.
* <Icon icon="users" /> **Distributed development**: Allow different teams to develop and maintain capabilities independently, composing them into a larger system with clear boundaries.
* <Icon icon="code-branch" /> **Parallelization**: Spawn specialized workers for subtasks and execute them concurrently for faster results.

Multi-agent patterns are particularly valuable when a single agent has too many [tools](/oss/python/langchain/tools) and makes poor decisions about which to use, when tasks require specialized knowledge with extensive context (long prompts and domain-specific tools), or when you need to enforce sequential constraints that unlock capabilities only after certain conditions are met.

<Tip>
  At the center of multi-agent design is **[context engineering](/oss/python/langchain/context-engineering)**—deciding what information each agent sees. The quality of your system depends on ensuring each agent has access to the right data for its task.
</Tip>

## Patterns

Here are the main patterns for building multi-agent systems, each suited to different use cases:

| Pattern                                                                  | How it works                                                                                                                                                                                        |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Subagents**](/oss/python/langchain/multi-agent/subagents)             | A main agent coordinates subagents as tools. All routing passes through the main agent, which decides when and how to invoke each subagent.                                                         |
| [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)               | Behavior changes dynamically based on state. Tool calls update a state variable that triggers routing or configuration changes, switching agents or adjusting the current agent's tools and prompt. |
| [**Skills**](/oss/python/langchain/multi-agent/skills)                   | Specialized prompts and knowledge loaded on-demand. A single agent stays in control while loading context from skills as needed.                                                                    |
| [**Router**](/oss/python/langchain/multi-agent/router)                   | A routing step classifies input and directs it to one or more specialized agents. Results are synthesized into a combined response.                                                                 |
| [**Custom workflow**](/oss/python/langchain/multi-agent/custom-workflow) | Build bespoke execution flows with [LangGraph](/oss/python/langgraph/overview), mixing deterministic logic and agentic behavior. Embed other patterns as nodes in your workflow.                    |

### Choosing a pattern

Use this table to match your requirements to the right pattern:

<div className="compact-first-col">
  | Pattern                                                      | Distributed development | Parallelization | Multi-hop | Direct user interaction |
  | ------------------------------------------------------------ | :---------------------: | :-------------: | :-------: | :---------------------: |
  | [**Subagents**](/oss/python/langchain/multi-agent/subagents) |          ⭐⭐⭐⭐⭐          |      ⭐⭐⭐⭐⭐      |   ⭐⭐⭐⭐⭐   |            ⭐            |
  | [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)   |            —            |        —        |   ⭐⭐⭐⭐⭐   |          ⭐⭐⭐⭐⭐          |
  | [**Skills**](/oss/python/langchain/multi-agent/skills)       |          ⭐⭐⭐⭐⭐          |       ⭐⭐⭐       |   ⭐⭐⭐⭐⭐   |          ⭐⭐⭐⭐⭐          |
  | [**Router**](/oss/python/langchain/multi-agent/router)       |           ⭐⭐⭐           |      ⭐⭐⭐⭐⭐      |     —     |           ⭐⭐⭐           |
</div>

* **Distributed development**: Can different teams maintain components independently?
* **Parallelization**: Can multiple agents execute concurrently?
* **Multi-hop**: Does the pattern support calling multiple subagents in series?
* **Direct user interaction**: Can subagents converse directly with the user?

<Tip>
  You can mix patterns! For example, a **subagents** architecture can invoke tools that invoke custom workflows or router agents. Subagents can even use the **skills** pattern to load context on-demand. The possibilities are endless!
</Tip>

### Visual overview

<Tabs>
  <Tab title="Subagents">
    A main agent coordinates subagents as tools. All routing passes through the main agent.

    ```mermaid theme={null}
    graph LR
        U([User request]) --> M[Main Agent]
        M --> A[Subagent A]
        M --> B[Subagent B]
        M --> C[Subagent C]
        A --> M
        B --> M
        C --> M
        M --> R([Response])
    ```
  </Tab>

  <Tab title="Handoffs">
    Agents transfer control to each other via tool calls. Each agent can hand off to others or respond directly to the user.

    ```mermaid theme={null}
    graph LR
        U([User request]) --> A
        subgraph Agents
            direction TB
            A[Agent A] <--> B[Agent B]
            B <--> C[Agent C]
            A <--> C
        end
        A --> R([Response])
        B --> R
        C --> R
        A ~~~ B ~~~ C
    ```
  </Tab>

  <Tab title="Skills">
    A single agent loads specialized prompts and knowledge on-demand while staying in control.

    ```mermaid theme={null}
    graph LR
        U([User request]) --> A[Agent]
        A --> S1[Skill A]
        A --> S2[Skill B]
        A --> S3[Skill C]
        A --> R([Response])
    ```
  </Tab>

  <Tab title="Router">
    A routing step classifies input and directs it to specialized agents. Results are synthesized.

    ```mermaid theme={null}
    graph LR
        U([User request]) --> R[Router]
        R --> A[Agent A]
        R --> B[Agent B]
        R --> C[Agent C]
        A --> S[Synthesize]
        B --> S
        C --> S
        S --> O([Response])
    ```
  </Tab>
</Tabs>

## Performance comparison

Different patterns have different performance characteristics. Understanding these tradeoffs helps you choose the right pattern for your latency and cost requirements.

**Key metrics:**

* **Model calls**: Number of LLM invocations. More calls = higher latency (especially if sequential) and higher per-request API costs.
* **Tokens processed**: Total [context window](/oss/python/langchain/context-engineering) usage across all calls. More tokens = higher processing costs and potential context limits.

### One-shot request

> **User:** "Buy coffee"

A specialized coffee agent/skill can call a `buy_coffee` tool.

| Pattern                                                      | Model calls | Best fit |
| ------------------------------------------------------------ | :---------: | :------: |
| [**Subagents**](/oss/python/langchain/multi-agent/subagents) |      4      |          |
| [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)   |      3      |     ✅    |
| [**Skills**](/oss/python/langchain/multi-agent/skills)       |      3      |     ✅    |
| [**Router**](/oss/python/langchain/multi-agent/router)       |      3      |     ✅    |

<Tabs>
  <Tab title="Subagents">
    **4 model calls:**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Main Agent
        participant Coffee Subagent
        participant buy_coffee tool

        User->>Main Agent: "Buy coffee"
        Note over Main Agent: Call 1
        Main Agent->>Coffee Subagent: coffee_subagent()
        Note over Coffee Subagent: Call 2
        Coffee Subagent->>buy_coffee tool: buy_coffee()
        buy_coffee tool-->>Coffee Subagent: Done
        Note over Coffee Subagent: Call 3
        Coffee Subagent-->>Main Agent: "Bought coffee"
        Note over Main Agent: Call 4
        Main Agent-->>User: "I bought coffee for you"
    ```
  </Tab>

  <Tab title="Handoffs">
    **3 model calls:**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Main Agent
        participant Coffee Agent
        participant buy_coffee tool

        User->>Main Agent: "Buy coffee"
        Note over Main Agent: Call 1
        Main Agent->>Coffee Agent: transfer_to_coffee_agent()
        Note over Coffee Agent: Call 2
        Coffee Agent->>buy_coffee tool: buy_coffee()
        buy_coffee tool-->>Coffee Agent: Done
        Note over Coffee Agent: Call 3
        Coffee Agent-->>User: "I bought coffee for you"
    ```
  </Tab>

  <Tab title="Skills">
    **3 model calls:**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Agent
        participant load_skill tool
        participant buy_coffee tool

        User->>Agent: "Buy coffee"
        Note over Agent: Call 1
        Agent->>load_skill tool: load_skill("coffee")
        load_skill tool-->>Agent: Coffee skill context
        Note over Agent: Call 2
        Agent->>buy_coffee tool: buy_coffee()
        buy_coffee tool-->>Agent: Done
        Note over Agent: Call 3
        Agent-->>User: "I bought coffee for you"
    ```
  </Tab>

  <Tab title="Router">
    **3 model calls:**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Router LLM
        participant Coffee Agent
        participant buy_coffee tool

        User->>Router LLM: "Buy coffee"
        Note over Router LLM: Call 1: Route to coffee agent
        Router LLM->>Coffee Agent: Invoke with query
        Note over Coffee Agent: Call 2
        Coffee Agent->>buy_coffee tool: buy_coffee()
        buy_coffee tool-->>Coffee Agent: Done
        Note over Coffee Agent: Call 3
        Coffee Agent-->>User: "I bought coffee for you"
    ```
  </Tab>
</Tabs>

**Key insight:** Handoffs, Skills, and Router are most efficient for single tasks (3 calls each). Subagents adds one extra call because results flow back through the main agent—this overhead provides centralized control.

### Repeat request

> **Turn 1:** "Buy coffee"
> **Turn 2:** "Buy coffee again"

The user repeats the same request in the same conversation.

<div className="compact-first-col">
  | Pattern                                                      | Turn 2 calls | Total (both turns) | Best fit |
  | ------------------------------------------------------------ | :----------: | :----------------: | :------: |
  | [**Subagents**](/oss/python/langchain/multi-agent/subagents) |       4      |          8         |          |
  | [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)   |       2      |          5         |     ✅    |
  | [**Skills**](/oss/python/langchain/multi-agent/skills)       |       2      |          5         |     ✅    |
  | [**Router**](/oss/python/langchain/multi-agent/router)       |       3      |          6         |          |
</div>

<Tabs>
  <Tab title="Subagents">
    **4 calls again → 8 total**

    * Subagents are **stateless by design**—each invocation follows the same flow
    * The main agent maintains conversation context, but subagents start fresh each time
    * This provides strong context isolation but repeats the full flow
  </Tab>

  <Tab title="Handoffs">
    **2 calls → 5 total**

    * The coffee agent is **still active** from turn 1 (state persists)
    * No handoff needed—agent directly calls `buy_coffee` tool (call 1)
    * Agent responds to user (call 2)
    * **Saves 1 call by skipping the handoff**
  </Tab>

  <Tab title="Skills">
    **2 calls → 5 total**

    * The skill context is **already loaded** in conversation history
    * No need to reload—agent directly calls `buy_coffee` tool (call 1)
    * Agent responds to user (call 2)
    * **Saves 1 call by reusing loaded skill**
  </Tab>

  <Tab title="Router">
    **3 calls again → 6 total**

    * Routers are **stateless**—each request requires an LLM routing call
    * Turn 2: Router LLM call (1) → Milk agent calls buy\_coffee (2) → Milk agent responds (3)
    * Can be optimized by wrapping as a tool in a stateful agent
  </Tab>
</Tabs>

**Key insight:** Stateful patterns (Handoffs, Skills) save 40-50% of calls on repeat requests. Subagents maintain consistent cost per request—this stateless design provides strong context isolation but at the cost of repeated model calls.

### Multi-domain

> **User:** "Compare Python, JavaScript, and Rust for web development"

Each language agent/skill contains \~2000 tokens of documentation. All patterns can make parallel tool calls.

| Pattern                                                      | Model calls | Total tokens | Best fit |
| ------------------------------------------------------------ | :---------: | :----------: | :------: |
| [**Subagents**](/oss/python/langchain/multi-agent/subagents) |      5      |     \~9K     |     ✅    |
| [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)   |      7+     |    \~14K+    |          |
| [**Skills**](/oss/python/langchain/multi-agent/skills)       |      3      |     \~15K    |          |
| [**Router**](/oss/python/langchain/multi-agent/router)       |      5      |     \~9K     |     ✅    |

<Tabs>
  <Tab title="Subagents">
    **5 calls, \~9K tokens**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Main Agent
        participant Python Subagent
        participant JS Subagent
        participant Rust Subagent
        User->>Main Agent: "Compare Python, JS, Rust"
        Note over Main Agent: Call 1 (1K)
        par Parallel execution
            Main Agent->>Python Subagent: python_subagent()
            Note over Python Subagent: Call 2 (2K)
            Python Subagent-->>Main Agent: Python analysis
        and
            Main Agent->>JS Subagent: js_subagent()
            Note over JS Subagent: Call 3 (2K)
            JS Subagent-->>Main Agent: JS analysis
        and
            Main Agent->>Rust Subagent: rust_subagent()
            Note over Rust Subagent: Call 4 (2K)
            Rust Subagent-->>Main Agent: Rust analysis
        end
        Note over Main Agent: Call 5 (2K)
        Main Agent-->>User: Synthesized comparison
    ```

    Each subagent works in **isolation** with only its relevant context. Total: **9K tokens**.
  </Tab>

  <Tab title="Handoffs">
    **7+ calls, \~14K+ tokens**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Main Agent
        participant Python Agent
        participant JS Agent
        participant Rust Agent
        User->>Main Agent: "Compare Python, JS, Rust"
        Note over Main Agent: Call 1 (1K)
        Main Agent->>Python Agent: transfer_to_python()
        Note over Python Agent: Calls 2-3 (2K each)
        Python Agent->>JS Agent: transfer_to_js()
        Note over JS Agent: Calls 4-5 (2K each)
        JS Agent->>Rust Agent: transfer_to_rust()
        Note over Rust Agent: Calls 6-7 (2K each)
        Rust Agent-->>User: Combined comparison
    ```

    Handoffs executes **sequentially**—can't research all three languages in parallel. Growing conversation history adds overhead. Total: **\~14K+ tokens**.
  </Tab>

  <Tab title="Skills">
    **3 calls, \~15K tokens**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Agent
        participant load_skill tool
        User->>Agent: "Compare Python, JS, Rust"
        Note over Agent: Call 1 (1K)
        Agent->>load_skill tool: load_skill("python", "js", "rust")
        load_skill tool-->>Agent: +6K context (2K each)
        Note over Agent: Call 2 (7K: 1K base + 6K skills)
        Note over Agent: Call 3 (7K: 1K base + 6K skills)
        Agent-->>User: Synthesized comparison
    ```

    After loading, **every subsequent call processes all 6K tokens of skill documentation**. Subagents processes 67% fewer tokens overall due to context isolation. Total: **15K tokens**.
  </Tab>

  <Tab title="Router">
    **5 calls, \~9K tokens**

    ```mermaid theme={null}
    sequenceDiagram
        participant User
        participant Router LLM
        participant Python Agent
        participant JS Agent
        participant Rust Agent
        participant Synthesis LLM
        User->>Router LLM: "Compare Python, JS, Rust"
        Note over Router LLM: Call 1 (1K)
        par Parallel execution
            Router LLM->>Python Agent: Route to Python
            Note over Python Agent: Call 2 (2K)
            Python Agent-->>Synthesis LLM: Python analysis
        and
            Router LLM->>JS Agent: Route to JS
            Note over JS Agent: Call 3 (2K)
            JS Agent-->>Synthesis LLM: JS analysis
        and
            Router LLM->>Rust Agent: Route to Rust
            Note over Rust Agent: Call 4 (2K)
            Rust Agent-->>Synthesis LLM: Rust analysis
        end
        Note over Synthesis LLM: Call 5 (2K)
        Synthesis LLM-->>User: Combined comparison
    ```

    Router uses an **LLM for routing**, then invokes agents in parallel. Similar to Subagents but with explicit routing step. Total: **9K tokens**.
  </Tab>
</Tabs>

**Key insight:** For multi-domain tasks, patterns with parallel execution (Subagents, Router) are most efficient. Skills has fewer calls but high token usage due to context accumulation. Handoffs is inefficient here—it must execute sequentially and can't leverage parallel tool calling for consulting multiple domains simultaneously.

### Summary

Here's how patterns compare across all three scenarios:

<div className="compact-first-col">
  | Pattern                                                      | One-shot | Repeat request |      Multi-domain     |
  | ------------------------------------------------------------ | :------: | :------------: | :-------------------: |
  | [**Subagents**](/oss/python/langchain/multi-agent/subagents) |  4 calls |  8 calls (4+4) |   5 calls, 9K tokens  |
  | [**Handoffs**](/oss/python/langchain/multi-agent/handoffs)   |  3 calls |  5 calls (3+2) | 7+ calls, 14K+ tokens |
  | [**Skills**](/oss/python/langchain/multi-agent/skills)       |  3 calls |  5 calls (3+2) |  3 calls, 15K tokens  |
  | [**Router**](/oss/python/langchain/multi-agent/router)       |  3 calls |  6 calls (3+3) |   5 calls, 9K tokens  |
</div>

**Choosing a pattern:**

<div className="compact-first-col">
  | Optimize for          | [Subagents](/oss/python/langchain/multi-agent/subagents) | [Handoffs](/oss/python/langchain/multi-agent/handoffs) | [Skills](/oss/python/langchain/multi-agent/skills) | [Router](/oss/python/langchain/multi-agent/router) |
  | --------------------- | :------------------------------------------------------: | :----------------------------------------------------: | :------------------------------------------------: | :------------------------------------------------: |
  | Single requests       |                                                          |                            ✅                           |                          ✅                         |                          ✅                         |
  | Repeat requests       |                                                          |                            ✅                           |                          ✅                         |                                                    |
  | Parallel execution    |                             ✅                            |                                                        |                                                    |                          ✅                         |
  | Large-context domains |                             ✅                            |                                                        |                                                    |                          ✅                         |
  | Simple, focused tasks |                                                          |                                                        |                          ✅                         |                                                    |
</div>

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/multi-agent/index.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
</Callout>

<Tip icon="terminal" iconType="regular">
  [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Tip>