concept

LangGraph Multi-Agent Patterns

created 2026-04-27 updated 2026-05-28 ai · langgraph · multi-agent · architecture · handoffs · subagents · skills

LangGraph Multi-Agent Patterns

Five formal multi-agent patterns in LangGraph, each solving different limitations of the basic ReAct Pattern. See AI Agent Architectures for the full decision framework.

Pattern Comparison

PatternCalls (1-shot)StateParallelContext IsolationBest For
Handoffs3PersistentNoNo (shared)Sequential workflows
Subagents4StatelessYesYesMulti-domain, large context
Skills3PersistentNoNo (loaded)Single agent, many specializations
Router3StatelessYesYesClear input classification
CustomVariesVariesVariesVariesComplex orchestration

1. Handoffs

Agent-to-agent control transfer via state variables. The Command primitive combines state updates with routing.

Single agent + middleware (preferred):

  • One agent, middleware dynamically swaps prompt and tools based on current_step
  • Message history flows naturally
  • Simpler to debug

Multiple subgraph agents:

  • Separate agent nodes in a parent graph
  • Use Command(goto="target", graph=Command.PARENT) for navigation
  • Must manually pass context between agents (include AIMessage + ToolMessage pair)
  • Better when agents need bespoke graph logic (reflection, retrieval steps)

Critical rule: Always include a ToolMessage with matching tool_call_id when transferring. Without it, conversation history becomes malformed.

2. Subagents (Agent-as-Tool)

Supervisor delegates to specialized workers. Each subagent runs in isolated context.

Two tool patterns:

  • Tool-per-agent: Dedicated wrapper function for each subagent. Fine-grained input/output control.
  • Single dispatch: One task(agent_name, description) tool that routes to any subagent. Simpler but less control.

Context engineering:

  • Use ToolRuntime to pass parent state to subagents
  • Return Command from tool to update parent state with subagent results
  • Subagents are stateless by default (fresh per invocation)

Subagent discovery (for large registries):

  • System prompt enumeration (<10 agents)
  • Enum constraint (type-safe)
  • Discovery tool (progressive disclosure for large registries)

3. Skills

Prompt-driven specializations loaded on-demand. Lighter than subagents.

How they work:

  1. Agent checks skill descriptions against user request
  2. Matched skill’s full content (SKILL.md) is loaded into context
  3. Agent follows the skill’s instructions
  4. Skill may also register new tools dynamically

Directory structure:

skills/
├── article-editor/
│   ├── SKILL.md        # Instructions + examples
│   └── templates/      # Supporting files
└── financial-analysis/
    ├── SKILL.md
    └── analyze.py      # Executable script

Key difference from subagents: Skills augment the current agent’s context. Subagents run in isolation. Skills are better for repeat requests (state persists). Subagents are better for large-context domains (no bloat).

4. Router

Initial classification step directs to specialists. Supports parallel execution.

5. Custom Workflow

Bespoke LangGraph graphs mixing deterministic logic with agentic behavior. Can embed any other pattern as a node.

The Command Primitive

Central to all multi-agent routing in LangGraph:

from langgraph.types import Command

# Update state and route
Command(update={"key": "value"}, goto="target_node")

# Navigate from subgraph to parent
Command(goto="target", graph=Command.PARENT)

# Resume after interrupt
Command(resume={"answer": "approved"})

Type annotations enforce valid targets:

def my_node(state) -> Command[Literal["agent_a", "agent_b"]]:
    ...

Production Reference: Vibe-Trading

vibe-trading ships 29 swarm presets as DAG-based custom-workflow agents (pattern 5). See Multi-Agent Finance Workflows for a catalog of preset shapes (investment committee, equities desk, technical analysis panel, risk committee). Each preset is a parallel-then-merge DAG: specialists fan out, synthesizer fans in. Confirms that “custom workflow” is the dominant production pattern once teams are real (>3 agents, mixed parallel/sequential).

Production Reference: ai-hedge-fund

ai-hedge-fund is the cleanest legible LangGraph StateGraph reference at scale (58k+ stars on GitHub as of 2026-05-04). create_workflow() in src/main.py is ~30 lines of explicit add_node + add_edge for a 19-agent parallel-fan-out → fan-in shape. Worth reading if you want to see “production LangGraph for a multi-agent system” without YAML or framework abstraction layers in the way. Uses Pydantic-structured output as the coordination glue (each agent emits {signal, confidence, reasoning} — see Agent Persona Pattern for why this composes so well).