Multi-agent

Multi-agent systems break a complex application into multiple specialized agents that work together to solve problems. Instead of relying on a single agent to handle every step, multi-agent architectures allow you to compose smaller, focused agents into a coordinated workflow.

Multi-agent systems are useful when:

• A single agent has too many tools and makes poor decisions about which to use.
• Context or memory grows too large for one agent to track effectively.
• Tasks require specialization (e.g., a planner, researcher, math expert).
• You need to enforce sequential constraints — unlocking capabilities only after certain conditions are met.
• Different teams need to develop and maintain agents independently.

Architectures

There are four main architectures for building multi-agent systems, each suited to different use cases:

Architecture	How it works	Best for
Supervisor	A central agent calls sub-agents as tools	Task orchestration, parallel execution
Dynamic agent	One agent with dynamically changing prompts/tools based on state	Multi-stage conversations, sequential unlocking
Workflow	Agents connected via deterministic transitions	Pipelines, structured processing
Skills	Specialized prompts invoked on-demand	Progressive disclosure, team distribution

You can mix architectures! For example, a supervisor can manage workflow sub-graphs, or a dynamic agent can invoke skills at certain stages.

Choosing an architecture

The right architecture depends on how your agents need to interact with users and each other. Start with these questions to narrow down your choice:

Do sub-agents need to converse directly with users?

Use Dynamic agent if you need to enforce sequential constraints (e.g., collect a warranty ID before processing a refund).

Use Skills if sub-agents can be invoked freely without strict ordering.

Do you need deterministic, predictable flow between agents?

Use Workflow. This gives you explicit control over transitions and makes execution easy to debug.

Do sub-agents need to run in parallel?

Use Supervisor. The supervisor can invoke multiple sub-agents simultaneously and coordinate their results.

Do you need to persist state across sub-agent interactions?

Use Dynamic agent. State survives across conversation turns, enabling multi-step flows.

Alternatively, use Supervisor with stateful tools if you need centralized orchestration.

Will different teams develop and maintain agents independently?

Use Skills. Each skill can be developed, tested, and deployed separately.

Do you need centralized orchestration without direct user interaction?

Use Supervisor. Sub-agents return results to the supervisor, which handles all user communication.

Supervisor

In the supervisor architecture, a central supervisor agent coordinates sub-agents by calling them as tools. The supervisor decides which sub-agent to invoke, what input to provide, and how to combine results.

Key characteristics:

• Centralized control: All routing passes through the supervisor
• Sub-agents as tools: Each sub-agent is wrapped as a callable tool
• No direct user interaction: Sub-agents return results to the supervisor, not the user
• Parallel execution: The supervisor can invoke multiple sub-agents in a single turn

Use the supervisor pattern when you have multiple distinct domains (e.g., calendar, email, CRM, database), sub-agents don’t need to converse directly with users, or you want centralized workflow control. For simpler cases with just a few tools, use a single agent.

Tutorial: Build a supervisor agent

Learn how to build a personal assistant using the supervisor pattern, where a central supervisor agent coordinates specialized worker agents.

Learn more

Example

The example below shows how a main agent is given access to a single sub-agent via a tool definition:

from langchain.tools import tool
from langchain.agents import create_agent


subagent1 = create_agent(model="...", tools=[...])

@tool(
    "subagent1_name",
    description="subagent1_description"
)
def call_subagent1(query: str):
    result = subagent1.invoke({
        "messages": [{"role": "user", "content": query}]
    })
    return result["messages"][-1].content

agent = create_agent(model="...", tools=[call_subagent1])

In this pattern:

1. The main agent invokes call_subagent1 when it decides the task matches the sub-agent’s description.
2. The sub-agent runs independently and returns its result.
3. The main agent receives the result and continues orchestration.

Where to customize

There are several points where you can control how context is passed between the main agent and its subagents:

1. Sub-agent name ("subagent1_name"): This is how the main agent refers to the sub-agent. Since it influences prompting, choose it carefully.
2. Sub-agent description ("subagent1_description"): This is what the main agent knows about the sub-agent. It directly shapes how the main agent decides when to call it.
3. Input to the sub-agent: You can customize this input to better shape how the sub-agent interprets tasks. In the example above, we pass the agent-generated query directly.
4. Output from the sub-agent: This is the response passed back to the main agent. You can adjust what is returned to control how the main agent interprets results. In the example above, we return the final message text, but you could return additional state or metadata.

Control the input to the sub-agent

There are two main levers to control the input that the main agent passes to a sub-agent:

• Modify the prompt: Adjust the main agent’s prompt or the tool metadata (i.e., sub-agent’s name and description) to better guide when and how it calls the sub-agent.
• Context injection: Add input that isn’t practical to capture in a static prompt (e.g., full message history, prior results, task metadata) by adjusting the tool call to pull from the agent’s state.

from langchain.agents import AgentState
from langchain.tools import tool, ToolRuntime

class CustomState(AgentState):
    example_state_key: str

@tool(
    "subagent1_name",
    description="subagent1_description"
)
def call_subagent1(query: str, runtime: ToolRuntime[None, CustomState]):
    # Apply any logic needed to transform the messages into a suitable input
    subagent_input = some_logic(query, runtime.state["messages"])
    result = subagent1.invoke({
        "messages": subagent_input,
        # You could also pass other state keys here as needed.
        # Make sure to define these in both the main and subagent's
        # state schemas.
        "example_state_key": runtime.state["example_state_key"]
    })
    return result["messages"][-1].content

Control the output from the sub-agent

Two common strategies for shaping what the main agent receives back from a sub-agent:

• Modify the prompt: Refine the sub-agent’s prompt to specify exactly what should be returned.
  • Useful when outputs are incomplete, too verbose, or missing key details.
  • A common failure mode is that the sub-agent performs tool calls or reasoning but does not include the results in its final message. Remind it that the controller (and user) only see the final output, so all relevant info must be included there.
• Custom output formatting: Adjust or enrich the sub-agent’s response in code before handing it back to the main agent.
  • Example: pass specific state keys back to the main agent in addition to the final text.
  • This requires wrapping the result in a Command (or equivalent structure) so you can merge custom state with the sub-agent’s response.

from typing import Annotated
from langchain.agents import AgentState
from langchain.tools import InjectedToolCallId
from langgraph.types import Command


@tool(
    "subagent1_name",
    description="subagent1_description"
)
# We need to pass the `tool_call_id` to the sub agent so it can use it to respond with the tool call result
def call_subagent1(
    query: str,
    tool_call_id: Annotated[str, InjectedToolCallId],
# You need to return a `Command` object to include more than just a final tool call
) -> Command:
    result = subagent1.invoke({
        "messages": [{"role": "user", "content": query}]
    })
    return Command(update={
        # This is the example state key we are passing back
        "example_state_key": result["example_state_key"],
        "messages": [
            ToolMessage(
                content=result["messages"][-1].content,
                # We need to include the tool call id so it matches up with the right tool call
                tool_call_id=tool_call_id
            )
        ]
    })

Dynamic agent

In the dynamic agent architecture, you have a single agent whose behavior (prompt, tools, and capabilities) changes dynamically based on state. Under the hood, this is a state machine implemented via middleware that performs handoffs through tool calls.

Key characteristics:

• Single agent, multiple configurations: The agent identity changes based on state
• State-driven behavior: Prompts and tools are selected based on a state variable (e.g., active_agent)
• Direct user interaction: The active agent configuration handles user messages directly
• Persistent state: State survives across conversation turns

Use the dynamic agent pattern when you need to enforce sequential constraints (unlock capabilities only after preconditions are met), sub-agents need to converse directly with the user, or you’re building multi-stage conversational flows. This pattern is particularly valuable for customer support scenarios where you need to collect information in a specific sequence — for example, collecting a warranty ID before processing a refund.

Tutorial: Build a customer support agent with handoffs

Learn how to build a customer support workflow using the dynamic agent pattern, where agents pass control through state transitions.

Learn more

Design dynamic agent flows carefully to avoid creating rigid, frustrating experiences. Users should be able to correct mistakes, change the conversation flow, and navigate back to previous steps. Overly restrictive flows can feel like poorly designed phone trees.

At the core, the dynamic agent pattern relies on persistent state that survives across conversation turns:

1. State variable: A field in your state schema (e.g., active_agent: str) tracks which agent configuration is currently active.
2. State update tool: The agent uses a tool to change the value of active_agent when transitioning to a new stage.
3. Dynamic configuration: On each turn, the graph entry point reads active_agent from the persisted state and dynamically configures the appropriate system prompt, tools, and behavior.

This pattern creates a state machine where each configuration represents a distinct state with its own behavior and capabilities.

Example

Here’s an example showing how agents transition between configurations:

from langchain.agents import AgentState, create_agent
from langchain.tools import tool, ToolRuntime
from langgraph.types import Command

class SupportState(AgentState):
    """Track which agent is currently active."""
    current_agent: str = "triage"

@tool
def transfer_to_specialist(
    runtime: ToolRuntime[None, SupportState]
) -> Command:
    """Transfer conversation to a specialist agent."""
    return Command(update={"current_agent": "specialist"})

# Each agent configuration has different prompts/tools
agent = create_agent(
    model,
    tools=[transfer_to_specialist, ...],
    state_schema=SupportState
)

The key mechanism is using Command to update state fields that control which agent configuration is active. Middleware can then read this state and dynamically configure the agent’s behavior.

Workflow

In the workflow architecture, agents are connected via deterministic transitions defined at graph construction time. The flow between agents is explicit and predictable.

Key characteristics:

• Deterministic flow: Transitions are defined explicitly via graph edges
• Predictable execution: You always know which agent runs next
• No LLM routing decisions: The graph structure controls flow, not LLM calls
• Pipeline-style processing: Each agent processes and passes to the next

Use the workflow pattern when you have a fixed sequence of processing steps, agents are independent and don’t need to be aware of each other, or you want predictable, debuggable execution. Common examples include content pipelines (research → draft → edit → publish) and data processing (extract → validate → transform → load).

Example

This example shows a content pipeline where each node is a full agent with its own tools:

from langgraph.graph import StateGraph, MessagesState, START
from langchain.agents import create_agent

# Create specialized agents for each stage
research_agent = create_agent(
    model="openai:gpt-4o",
    tools=[web_search, fetch_url],
    prompt="You are a research assistant. Search for and gather relevant information on the topic.",
    name="researcher"
)

writing_agent = create_agent(
    model="openai:gpt-4o",
    tools=[create_outline, write_section],
    prompt="You are a writer. Create content based on the research provided.",
    name="writer"
)

editing_agent = create_agent(
    model="openai:gpt-4o",
    tools=[check_grammar, check_style],
    prompt="You are an editor. Refine and improve the content for clarity and correctness.",
    name="editor"
)

# Define the workflow with explicit edges
workflow = (
    StateGraph(MessagesState)
    .add_node("research", research_agent)
    .add_node("write", writing_agent)
    .add_node("edit", editing_agent)
    .add_edge(START, "research")
    .add_edge("research", "write")
    .add_edge("write", "edit")
    .compile()
)

result = workflow.invoke({
    "messages": [{"role": "user", "content": "Write an article about AI agents"}]
})

Skills

In the skills architecture, specialized capabilities are packaged as invokable “skills” that augment an agent’s behavior. Skills are primarily prompt-driven specializations that an agent can invoke on-demand.

Key characteristics:

• Prompt-driven specialization: Skills are primarily defined by specialized prompts
• Progressive disclosure: Skills become available based on context or user needs
• Team distribution: Different teams can develop and maintain skills independently
• Lightweight composition: Skills are simpler than full sub-agents

Use the skills pattern when you want a single agent with many possible specializations, you don’t need to enforce specific constraints between skills, or different teams need to develop capabilities independently. Common examples include coding assistants (skills for different languages or tasks), knowledge bases (skills for different domains), and creative assistants (skills for different formats).

Skills documentation is coming soon. This pattern is being developed as part of the deep-agents project.

Customize agent context

At the center of multi-agent design is context engineering - deciding what information each agent sees. LangChain gives you fine-grained control over:

• Which parts of the conversation or state are passed to each agent.
• Specialized prompts tailored to sub-agents.
• Inclusion/exclusion of intermediate reasoning.
• Customizing input/output formats per agent.

The quality of your system depends on context engineering. The goal is to ensure that each agent has access to the correct data it needs to perform its task, whether it’s acting as a tool or as an active agent.

---

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.