LangGraph Multi-Agent Collaboration in Practice: Designing Supervisor, Worker, and State Handoff

What This Guide Covers

• When does a LangGraph multi-agent system need a Supervisor?
• What are the respective responsibilities of a Supervisor Agent and Worker Agents?
• How can multiple agents share state without polluting each other’s context?
• What information should be passed during handoffs?
• How should thread_id, user_id, and session_id be designed?
• How to recover from task failures in a multi-agent system?

---

Who This Guide Is For

• Developers who have already built single-agent workflows using LangGraph
• Those looking to move AI agents from demos to production environments
• Engineers designing multi-agent systems for customer support, sales, finance, code review, etc.
• Full-stack developers dealing with state leakage, lost task handoffs, or agent infinite loops

---

1. Don’t Jump Straight Into Multi-Agent Architectures

Many developers, when first encountering AI agents, are drawn to the flashy effects of multi-agent collaboration and automatic dialogue. However, in real-world production environments, blindly introducing a multi-agent architecture is often the beginning of disaster.

We must clarify a core principle: not all complex tasks require multi-agent systems. Many tasks can be handled effectively by a single agent paired with a set of dynamic tools.

Advantages and Use Cases for Single-Agent Architectures

If your task fits the following characteristics, we recommend prioritizing a single-agent architecture:

1. Limited number of tools: Typically fewer than ten. The model can clearly understand the purpose and invocation timing of each tool, reducing the likelihood of hallucinations.
2. Short decision paths: Task progression does not require crossing multiple distinct professional domains.
3. Relatively simple state: Few state variables need to be maintained throughout the conversation or execution chain.
4. No strict role division: The executor does not need to assume drastically different social roles or security clearance levels.

In a single-agent mode, the system offers high determinism and low latency, while debugging and log tracing remain exceptionally straightforward.

When to Transition to a Multi-Agent System

The optimal time to adopt a multi-agent architecture is when your business complexity reaches a bottleneck that a single agent cannot support. Multi-agent systems provide irreplaceable value in the following scenarios:

• Tasks requiring multiple specialized roles: For example, in a software development agent system, you might need a Product Manager to break down requirements, an Architect to design interfaces, a Developer to write code, and a Tester to run tests. Each role has entirely different knowledge bases and prompt preferences.
• Need for explicit phased processing: Intermediate outputs differ significantly across stages, making it unsuitable to handle them mixed within a single context.
• Permission isolation and tool restrictions: Agents at different stages have completely different tool access permissions. For instance, a Finance Worker might have read-only database access, while a Transfer Worker has write access for fund allocation. Without strict role isolation, a single agent vulnerable to injection attacks could escalate privileges to call sensitive tools.
• Processes requiring human approval or failure recovery: In complex business chains, certain nodes may need to pause for human confirmation, or specific nodes may require targeted retries upon failure. Implementing this in a single agent makes state machine design exceptionally complex.

Official documentation states that multi-agent systems are used to coordinate specialized components to handle complex workflows. This indicates that multi-agents are not implemented for the sake of appearing advanced, but to physically isolate complexity.

---

2. What Problem Does the Supervisor / Worker Pattern Solve?

Among the various topologies of multi-agent systems, the Supervisor / Worker pattern (hierarchical multi-agent system) is the most aligned with enterprise organizational structures and the easiest to implement in production environments.

The essence of the Supervisor / Worker pattern is the physical separation of decision-making authority and execution authority.

Drawbacks of Traditional Group Chat Modes

In a Peer-to-Peer mesh chat mode without a Supervisor, agents collaborate in a flat structure. For example, after Agent A completes its task, it broadcasts the result to the channel, and the model autonomously decides which agent should take over next. This mode suffers from three fatal flaws:

1. Decision uncertainty: As the number of agents increases, the probability of hallucination in routing decisions rises exponentially, making it highly prone to situations where agents A and B pass the buck or fall into infinite loops.
2. Unbounded context growth: Every agent is forced to receive the full chat history, causing token consumption to grow quadratically.
3. Extremely difficult debugging: Without a central orchestrator, it is hard to determine whose responsibility a specific erroneous routing decision was.

How the Supervisor Mode Solves These Problems

A hierarchical architecture addresses these pain points by introducing a strong supervisor:

The Supervisor Agent is responsible for:

• Receiving and understanding the user’s ultimate goal, breaking it down into sub-tasks.
• Acting as a routing hub to explicitly dispatch specific Workers to execute sub-tasks.
• Reviewing results returned by Workers to determine if they meet interim delivery standards.
• Deciding the next step: whether to assign the next Worker, perform a local retry, terminate the process and output to the user, or proactively escalate to human intervention when unable to decide.

The Worker Agent is responsible for:

• Receiving specific task instructions and local context from the Supervisor.
• Focusing on executing tasks within a single specialized domain, calling upon that domain’s unique toolset.
• Returning structured, clean execution results to the Supervisor.
• Strictly avoiding system-level global flow control and refraining from unauthorized modifications to global routing states.

By dividing responsibilities this way, we concentrate complex routing decisions within the Supervisor’s prompts, while allowing Workers to remain highly focused and streamlined. This significantly enhances system stability and maintainability.

---

3. Minimal Architecture Topology

In LangGraph, the node topology of the Supervisor mode can be expressed through the following data flow:

       ┌────────── User ──────────┐
       │                          │ (输入 / 输出)
       ▼                          ▲
┌──────────────────────────────────────┐
│           Supervisor Node            │ (统一调度决策者)
└──────────────────┬───────────────────┘
                   │
                   │ (根据决策路由)
                   ▼
     ┌─────────────┴─────────────┐
     ▼                           ▼
┌──────────────┐           ┌──────────────┐
│ Research     │           │ Coding       │
│ Worker Node  │           │ Worker Node  │ (专项执行 Worker)
└──────┬───────┘           └──────┬───────┘
       │                          │
       └─────────────┬────────────┘
                     │ (返回结构化产物)
                     ▼
┌──────────────────────────────────────┐
│         State Merger / Edge          │ (状态规整与回传)
└──────────────────────────────────────┘

In this minimal architecture, the inputs and outputs of all Workers are routed back to the Supervisor. The Supervisor then determines whether to transition to the END state, proceed to another Worker, or instruct the original Worker to re-execute.

---

4. How Should State Be Designed?

In multi-agent systems, State is not simply a list of chat messages (Message List); it is a business object that flows across nodes.

In LangGraph, State is typically a Python dictionary inheriting from TypedDict. A well-designed, production-ready State for multi-agent systems should feature a layered and modular structure.

Recommended Global State Structure Design

from typing import TypedDict, List, Dict, Any, Annotated
from langchain_core.messages import BaseMessage
from langgraph.graph.message import add_messages

class GlobalAgentState(TypedDict):
    # 基础物理元数据
    user_id: str
    thread_id: str
    session_id: str

    # 任务控制流
    task_goal: str
    current_step: str
    assigned_worker: str

    # 全局对话历史（仅 Supervisor 共享）
    messages: Annotated[List[BaseMessage], add_messages]

    # 结构化业务产物（Worker 将结果写入此处，避免污染 message 历史）
    worker_outputs: Dict[str, Any]

    # 审计与异常记录
    error_log: List[str]
    approval_status: str  # pending | approved | rejected
    final_answer: str

The Iron Rules of State Design

To prevent state corruption during multi-agent collaboration, you must adhere to the following three iron rules:

1. Do not allow Workers to directly modify global workflow state

A Worker’s responsibility is to produce data, not control the workflow. In LangGraph, a Worker node should return only its locally computed business fields (e.g., a subset of worker_outputs). The Supervisor node should then read these outputs to decide whether to modify current_step or proceed with subsequent routing.

2. Do not pass the entire message history verbatim to every Worker

If the global messages list is passed directly as a parameter to a Research Worker, the model will be interfered with by the extensive, irrelevant reasoning processes from other Workers (such as a Coding Worker). This not only increases the risk of noisy hallucinations but also results in significant token waste. Each Worker should receive only the context fragments directly relevant to its current subtask.

3. Do not allow different users to share a thread_id

When designing global state storage, ensure that each independent task thread has a unique identifier. If concurrent user requests share the same thread_id, LangGraph’s state will suffer from severe state overwrites and data cross-contamination in multi-process or multi-thread environments.

---

5. What to Pass During Handoff State Transitions?

Handoff is the most fragile aspect of multi-agent collaboration. If information is opaque during the handoff, the next Agent loses context; if the information is redundant, it causes confusion for the model.

Handoff does not involve dumping all context crudely to the next Agent; rather, it involves passing the minimal context required to complete the task.

Fields That Should Be Included in a Handoff

When the Supervisor decides to assign a task to a Worker, it should construct a concise input payload:

• Clear task objective: For example, write unit test code compliant with the api.py interface specification.
• Explicit conclusion from the previous step: Such as the third-party API data dictionary retrieved by the Research Worker.
• Clear responsibilities for the current Worker: The core task for this specific invocation.
• Allowed tools and constraints: To prevent the model from executing actions beyond its defined boundaries.
• Expected output structure: Instruct the model to return JSON in a specific format, facilitating parsing by the Supervisor.

Pseudocode Example for State Transition Payload

# Supervisor 节点在路由分流时，为 Worker 封装的专用上下文
def route_to_worker(state: GlobalAgentState) -> Dict[str, Any]:
    current_worker = state["assigned_worker"]
    last_output = state["worker_outputs"].get("previous_step_result", "")

    # 构建专属于该 Worker 的 Handoff 上下文
    return {
        "messages": [
            {
                "role": "system",
                "content": f"你是一个专业的 {current_worker}。上一步的执行结果是：{last_output}。请基于此结果完成以下目标。"
            },
            {
                "role": "user",
                "content": state["task_goal"]
            }
        ]
    }

Content Strictly Prohibited from Passing

During the Handoff phase, the following sensitive or redundant data must be physically filtered out:

• Complete, unfiltered global chat history: Exclude irrelevant chatter from other Agents.
• Intermediate high-dimensional vectors from other Workers, large log files, or unrelated database dumps.
• Sensitive system-level credentials and session identity information belonging to other users.
• The model’s Chain of Thought (CoT) reasoning drafts from the previous stage. Only retain the final structured output.

---

6. How to Prevent State Leakage?

When multi-agent systems are deployed in production environments facing high-concurrency user requests, state leakage is the most frequent and severe issue. It is absolutely unacceptable in enterprise applications for User A to access User B’s private data, or for User A’s task to inadvertently incorporate User B’s conversational context.

State leakage typically does not stem from issues with model inference, but rather from chaotic physical isolation design involving thread_id, session_id, and user_id.

Rigorous Definitions Across Five Physical Dimensions

To completely eliminate the risk of state leakage at the system design level, the system’s hierarchical relationships must be clearly defined:

• user_id: Identifies a unique end-user (e.g., usr_98231). It serves as the underlying basis for billing, rate limiting, and basic data access control checks.
• session_id: Identifies a login instance or session lifecycle (e.g., sess_00971). It isolates the context for a single user interaction, typically expiring when the user closes the window or after a timeout.
• thread_id: Identifies the unique thread of a LangGraph state machine instance (e.g., thread_127a90bc). It acts as the physical key for the Checkpointer to read and write State.
• run_id: Identifies the lifecycle of a specific execution. This covers the single run cycle of a task from being awakened, executing, pausing, to completion.
• request_id: Identifies a specific network interaction or external tool invocation interface. It is used for full-chain log aggregation in distributed tracing systems (such as OpenTelemetry).

Production-Grade High-Concurrency Architecture to Prevent State Leakage

When deploying production-grade multi-agent systems, the following anti-leakage mechanisms must be strictly followed:

# 每次客户端请求到达时，网关必须强校验 user_id 与当前 thread_id 的绑定关系
def execute_agent_workflow(client_request: Dict[str, Any]):
    user_id = client_request["user_id"]
    thread_id = client_request["thread_id"]

    # 安全屏障：校验此 thread_id 是否确实属于该 user_id，防止伪造 thread_id 越权访问
    verify_thread_ownership(user_id, thread_id)

    # 传入显式的 config 字典，LangGraph 会通过 thread_id 物理隔离持久化状态
    config = {
        "configurable": {
            "thread_id": thread_id,
            "user_id": user_id
        }
    }

    # 唤醒图执行
    app.invoke(
        {"task_goal": client_request["prompt"]},
        config=config
    )

In system logs, all print or log outputs from every node must include the current context’s thread_id and request_id. This allows developers to clearly filter out each user’s state machine trajectory via a logging service (such as ELK) when multiple users’ Agent nodes are executing concurrently, preventing them from becoming mixed together.

---

7. What Role Does the Checkpointer Play in Multi-Agent Systems?

In single-agent systems, we might still rely on memory variables to track short-term conversation history. However, in multi-agent systems, a complex task may run for minutes, hours, or even span several days (for example, an approval workflow that includes human review).

Without a Checkpointer (persistent checkpoint), it is difficult to resume a multi-agent system at the correct node after an interruption.

Core Application Scenarios for the Checkpointer

The Checkpointer acts as the physical database layer in hierarchical multi-agent collaboration, addressing the following production challenges:

• Human-in-the-loop approval: When the Supervisor routes to a “transfer to human” node, the Graph execution flow needs to be physically suspended, and the State must be safely written to the database. When an administrator clicks “approve” in the backend, the system reads the checkpoint corresponding to thread_id and seamlessly resumes execution without needing to re-run the preceding Workers.
• Long-task resumption from breakpoints: If the Research Worker crashes due to a network interface timeout while processing the tenth step, the system can wake up from the ninth-step Checkpoint instead of pulling data again from the first step, avoiding the repeated consumption of expensive Token costs.
• Task execution retry: When a specific Worker execution error is detected and meets the retry policy, the system can roll back to the last intact Checkpoint to perform stateful self-repair.

We have already explored the implementation mechanisms of the Checkpointer in our previous article, LangGraph Memory and Checkpointing for Production AI Agents. For actual deployment, we recommend using persistent checkpoints based on databases such as SQLite or PostgreSQL.

In Supervisor mode, when a high-risk operation is detected (e.g., a fund transfer Worker is assigned), you can configure interrupt_before between Graph nodes:

# 构建 Graph 时，在执行资金划转节点前，物理暂停以待人工审批
workflow.compile(
    checkpointer=memory_saver,
    interrupt_before=["wire_transfer_worker"]
)

---

8. Common Errors and Error Logs

1. Error: LoopLimitReached (Infinite Loop)

• Symptom: An error occurs when running a multi-agent graph in either Astro or Python, indicating that the maximum execution step limit has been exceeded.
• Error message:

  langgraph.errors.GraphRecursionError: Recursion limit of 25 reached.
  

• Cause: The Supervisor gets lost between Worker A and Worker B. For example, if the result format provided by Worker A is invalid and the Supervisor cannot parse it, but there is no fallback strategy, it will keep repeatedly assigning tasks to Worker A.
• Solution: Set a strict rule counter in the Supervisor routing node, or forcibly route control to human intervention or a fallback node before recursion_limit reaches its threshold.

2. Error: StateKeyMismatch (Worker Overwrites Global State)

• Symptom: After a Worker Node finishes running, data originally generated by other Workers in the global State is physically erased or set to null.
• Cause: The Worker returned a dictionary containing a global field with the same name but an empty value, causing LangGraph’s default state update merge strategy to overwrite existing data.
• Solution: Carefully design the State merge mechanism, or use the custom append/merge method from Annotated for global fields. For example, use add_messages or a Dict merge function with deduplication logic.

3. Error: Invalid Thread Context (State Contamination)

• Symptom: In high-concurrency environments, logs show the following multi-tenant conflict error.
• Error message:

  ValueError: Thread context collision detected. Thread id '102983' already owned by user 'A', request came from user 'B'.
  

• Cause: The code did not perform ownership validation on the thread_id checkpoint passed in by the client, resulting in different users sharing the same checkpoint.
• Solution: Enforce an authorization interceptor at the API entry layer to prevent cross-user access to checkpoints.

---

9. When Not to Use Multi-Agent Architectures

Multi-agent architectures are definitely not a silver bullet. In the following scenarios, it is strongly recommended to avoid using multi-agent systems:

• Tasks requiring only a single external tool call: For example, simply asking a large language model to query the weather and format it into a table.
• Extremely short business decision trees: The workflow is highly fixed, and standard conditional logic (If-Else) suffices, making autonomous routing via LLMs unnecessary.
• No physical permission isolation between roles: All subtasks execute within the same permission context, posing no risk of sensitive data leakage.
• Extremely strict response time requirements: Multi-agent collaboration increases the number of model interaction calls, causing network latency and computational overhead to multiply.

---

FAQ

What is the difference between LangGraph multi-agent and CrewAI?

CrewAI is more akin to role-based collaboration, suitable for quickly building task-oriented agents; its internal coordination logic primarily relies on natural language prompts. LangGraph, on the other hand, functions more like a directed graph state machine, making it better suited for production-grade complex systems that require precise control over workflows, custom states, and physical checkpoint recovery paths.

Must the Supervisor Agent use an expensive large model?

Not necessarily. If your task routing logic is highly fixed, you can use standard Python rule-based code (such as conditional statements or keyword classifiers) to act as the Supervisor. This is known as static routing. Only when the routing logic requires high-dimensional semantic understanding should you use a large model as the Supervisor.

Can Worker Agents directly call all available tools?

It is not recommended. You should follow the principle of least privilege. Each Worker should possess only the minimal set of tools required to complete its specific tasks. This serves as a physical firewall against prompt injection attacks.

Should multiple Agents share the complete chat history?

It is not recommended. The core of multi-agent collaboration is state normalization. Workers should pass prior conclusions to each other through structured State fields (such as Handoff Payloads), rather than dumping thousands of tokens of chat history to every model.

Does the Checkpointer mechanism impact performance under high concurrency?

Yes. Reading and writing high-frequency State to a relational database (such as PostgreSQL) introduces I/O latency. To balance performance and security, you can implement a write cache layer using Redis, or restrict persistent disk writes to only critical Handoff and suspension nodes.

---

Series Navigation

LangGraph Production-Grade Agent Orchestration Series:

• Part 1: Supervisor / Worker
• Part 2: State Isolation
• Part 3: Human-in-the-loop
• Part 4: Failure Recovery
• Part 5: Observability
• Part 6: Checkpointer
• Part 7: Subgraph

Continue Reading

• LangGraph Memory and Checkpointing for Production AI Agents
• CrewAI vs LangGraph: 2 Core Considerations for AI Agent Orchestration Selection5
• AI Agent Memory System: Building an AI Agent System with Long-Term Memory
• MCP OAuth Authentication in Practice: Why Remote MCP Servers Can’t Be Exposed Without Protection
• MCP Streamable HTTP in Practice: From Local stdio Server to Remote MCP Service Deployment
• AI Practical Guide: MCP, LangGraph, AI Agents, and Boosting AI Development Efficiency - XBSTACK

Topic path / LangGraph

Continue through the production LangGraph learning path

The LangGraph hub organizes state isolation, checkpointing, human approval, retries, observability, supervisors, subgraphs and memory into one reviewable path.

Open LangGraph hub → Start with state isolation Subscribe for updates