Langgraph Agent Patterns

LangGraph Agent Patterns

Implement and configure multi-agent coordination patterns for LangGraph applications.

Pattern Selection

Choose the right pattern based on your coordination needs:

Quick Decision:

• Dynamic routing needed? → Supervisor
• Tasks can run in parallel? → Orchestrator-Worker
• Simple categorization? → Router
• Linear sequence? → Handoffs

For detailed comparison: See references/pattern-comparison.md

Pattern Implementation Guides

Supervisor-Subagent Pattern

Overview: Central coordinator delegates to specialized subagents based on context.

Quick Start:

# Generate supervisor graph boilerplate
uv run scripts/generate_supervisor_graph.py my-team \
  --subagents "researcher,writer,reviewer"

# TypeScript
uv run scripts/generate_supervisor_graph.py my-team \
  --subagents "researcher,writer,reviewer" \
  --typescript

Key Components:

1. State with routing: next field for routing decisions
2. Supervisor node: Makes routing decisions based on context
3. Subagent nodes: Specialized agents with distinct capabilities
4. Conditional edges: Route from supervisor to subagents

Example Flow:

User Request → Supervisor → Researcher → Supervisor → Writer → Supervisor → FINISH

For complete implementation: See references/supervisor-subagent.md

Router Pattern

Overview: One-time routing to specialized agents based on initial request.

Key Components:

1. State with route: Single routing decision field
2. Router node: Categorizes request (keyword, LLM, or semantic)
3. Specialized agents: Independent agents for each category
4. Conditional routing: Route to agent, then END

Example Flow:

User Request → Router → Sales Agent → END
                   ├→ Support Agent → END
                   └→ Billing Agent → END

Routing Strategies:

• Keyword-based: Fast, simple string matching
• LLM-based: Semantic understanding, flexible
• Embedding-based: Similarity matching
• Model-based: Fine-tuned classifier

For complete implementation: See references/router-pattern.md

Orchestrator-Worker Pattern

Overview: Decompose task into parallel subtasks, aggregate results.

Key Components:

1. State with subtasks: Task decomposition and results accumulation
2. Orchestrator node: Splits task into independent subtasks
3. Worker nodes: Process subtasks in parallel
4. Aggregator node: Synthesizes results
5. Send fan-out: Return Send(...) objects from conditional edges and use a list reducer (for example Annotated[list[dict], operator.add]) so worker outputs accumulate

Example Flow:

Task → Orchestrator → Worker 1 ┐
                  → Worker 2  ├→ Aggregator → Result
                  → Worker 3 ┘

Best Practices:

• Ensure subtasks are independent
• Handle worker failures gracefully
• Limit concurrent workers for resource management
• Use LLM for result synthesis

For complete implementation: See references/orchestrator-worker.md

Handoffs Pattern

Overview: Sequential agent handoffs with context preservation.

Key Components:

1. State with context: Shared context across handoffs
2. Agent nodes: Each agent hands off to next
3. Handoff logic: Explicit or conditional handoffs
4. Context management: Preserve and pass information

Example Flow:

Request → Researcher → Writer → Editor → FINISH
         (with context preservation)

Handoff Strategies:

• Explicit: Agent declares next agent
• Conditional: Based on completion criteria
• Circular: Agents can hand back for revisions

For complete implementation: See references/handoffs.md

Examples

Runnable mini-projects (Python + JavaScript):

• assets/examples/supervisor-example/
• assets/examples/router-example/
• assets/examples/orchestrator-example/
• assets/examples/handoff-example/

State Design for Multi-Agent Patterns

Each pattern requires specific state schema design:

Supervisor Pattern:

class SupervisorState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    next: Literal["agent1", "agent2", "FINISH"]
    current_agent: str

Router Pattern:

class RouterState(TypedDict):
    messages: list[BaseMessage]
    route: Literal["category1", "category2"]

Orchestrator-Worker:

import operator
class OrchestratorState(TypedDict):
    task: str
    subtasks: list[dict]
    results: Annotated[list[dict], operator.add]

Handoffs:

class HandoffState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    next_agent: str
    context: dict

For detailed state patterns: See references/state-management-patterns.md

Validation and Visualization

Validate Graph Structure

# Validate agent graph for issues
uv run scripts/validate_agent_graph.py path/to/graph.py:graph

# Checks for:
# - Unreachable nodes
# - Cycles without termination
# - Dead ends
# - Invalid routing

Visualize Graph

# Generate Mermaid diagram
uv run scripts/visualize_graph.py path/to/graph.py:graph --output diagram.md

# View in browser or IDE with Mermaid support

Common Patterns and Anti-Patterns

Best Practices

1. Clear Agent Responsibilities

• Define non-overlapping capabilities
• Document each agent's purpose
• Avoid agent duplication

2. Loop Prevention

• Track iteration count in state
• Set maximum iterations
• Implement loop detection

3. Context Management

• Summarize context when it grows large
• Only pass necessary information
• Use structured context where possible

4. Error Handling

• Validate routing decisions
• Handle invalid routes gracefully
• Default to safe fallbacks

Anti-Patterns to Avoid

1. Over-Supervision

# ❌ Bad: Supervisor for simple linear flow
User → Supervisor → Agent1 → Supervisor → Agent2 → Supervisor

# ✅ Good: Use handoffs instead
User → Agent1 → Agent2 → FINISH

2. Complex Router Logic

# ❌ Bad: Complex routing rules in router
if complex_condition_A and (condition_B or condition_C):
    route = determine_complex_route()

# ✅ Good: Use supervisor with LLM
route = llm.invoke("Analyze and route: {query}")

3. Unmanaged State Growth

# ❌ Bad: Accumulating all messages forever
messages: list[BaseMessage]  # Grows unbounded

# ✅ Good: Summarize or limit
if len(messages) > 20:
    messages = summarize_context(messages)

Debugging Multi-Agent Systems

1. Trace Agent Flow

Use LangSmith to visualize agent interactions:

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "<your-api-key>"
os.environ["LANGSMITH_PROJECT"] = "multi-agent-debug"

result = graph.invoke(input_state)

2. Log Routing Decisions

Add logging to routing nodes:

def supervisor_node(state: SupervisorState) -> dict:
    decision = make_routing_decision(state)

    print(f"Supervisor routing to: {decision}")
    print(f"Current state: {len(state['messages'])} messages")
    print(f"Iteration: {state.get('iteration', 0)}")

    return {"next": decision}