Build Multi-Role Agents with Claude 4 & LangGraph

If you’re ready to move beyond simple chatbots and build truly autonomous AI systems, you have found the definitive guide. The combination of Anthropic’s powerful Claude 4 reasoning engine and the LangGraph orchestration framework represents the state-of-the-art stack for creating reliable, sophisticated, and controllable multi-agent systems.

A Quick Context for Beginners: What is a multi-agent system? Imagine instead of one AI trying to do everything, you create a specialized team. One agent is a “Project Manager,” another is an expert “Researcher,” and a third is a “Coder.” They collaborate, pass tasks to one another, and work together to achieve a complex goal. LangGraph is the framework that allows us to define the structure, communication channels, and workflow for this AI team.

In this comprehensive guide, we will dive deep into the practical steps, architectural patterns, and best practices for integrating Claude 4 with both AutoGen and CrewAI. We’ll cover everything from initial setup and step-by-step code examples to advanced strategies and troubleshooting common errors. This is your definitive resource for building next-generation AI agents.

Part 1: The Foundational Stack

To build a skyscraper, you need to understand your steel and your blueprints. For us, the steel is Claude 4’s reasoning power, and the blueprints are the structure provided by LangGraph.

The Claude 4 Reasoning Engine: Choosing Your Agent’s Brain

The first step in any agentic system is choosing the Large Language Model (LLM) that will act as the “brain” for your agents. The Claude 4 family offers two distinct options, and using them strategically is the key to building systems that are both highly capable and cost-effective.

Claude Opus 4 (The “Supervisor”): Think of Opus as the brilliant, experienced team lead. It has frontier-level reasoning capabilities, making it perfect for tasks that require deep analysis, strategic planning, or orchestrating other agents. You use Opus for your most important agent, the one that creates the plan and makes the high-level decisions.
Claude Sonnet 4 (The “Worker”): Think of Sonnet as the highly skilled, fast, and efficient specialist on your team. It has incredible performance for its price, excelling at executing well-defined tasks like web research, data extraction, or writing code for a specific function. You use Sonnet for the “worker” agents that receive instructions from the supervisor.

The Golden Rule of Architecture: The most effective and cost-efficient pattern is to use one Claude 4 Opus agent as the “supervisor” to manage the workflow and multiple Claude 4 Sonnet agents as “workers” to perform the individual tasks.

This table breaks down their key differences:

Feature	Claude 4 Opus	Claude 4 Sonnet
Primary Role	Supervisor, Planner, Orchestrator	Worker, Specialist, Sub-Agent
Reasoning	Frontier, for highly complex tasks	High-performance, for efficient execution
Speed	Slower (optimized for depth)	Faster (optimized for scale)
Cost	Premium (~$15 / $75 per 1M tokens)	Value (~$3 / $15 per 1M tokens)
Best For…	Task decomposition, strategic planning	Web research, tool execution, content drafting

LangGraph: The Orchestration Framework for Controllable Agents

If Claude is the brain, LangGraph is the nervous system. It lets us control how information flows and how decisions are made.

Why Graphs? A Necessary Shift

Early agent frameworks often used simple linear “chains.” This was like having a single to-do list. The problem is, real-world tasks aren’t linear. They have loops (“try again”), branches (“if this happens, do that”), and require collaboration.

LangGraph solves this by modeling workflows as a graph—a state machine. This forces you, the developer, to be explicit about your agent’s thought process. The result is a system that is far more controllable, predictable, and easier to debug than a “black box” agent.

The Core Concepts of LangGraph

LangGraph is built on three simple but powerful ideas:

State: This is the shared memory of your agent team, like a central whiteboard where all agents can read and write information. It’s defined as a simple Python object and holds everything important: the user’s request, the data found so far, the draft of a report, etc.
Nodes: These are the “workers” in your graph. Each node is a Python function that performs an action. One node might call an LLM, another might execute a tool (like a web search), and another might be a human waiting for approval.
Edges: These are the “pathways” that connect the nodes. They define the flow of control. A direct edge says, “After node A, always go to node B.” A conditional edge is where the magic happens; it says, “Look at the current state on the whiteboard, and based on what you see, decide whether to go to node B, C, or D.” This is how agents make decisions.

This structure is what allows you to build complex, looping behaviors and even include a human-in-the-loop to provide feedback or approve steps before the agent continues.

Part 2: Building a Multi-Agent Research Team with Claude 4 and LangGraph

Theory is great, but code is better. Let’s build a complete, multi-agent system that can research a topic and write a report. This is a practical, real-world use case that showcases the power of this stack.

Our Goal: To create an autonomous system that takes a topic from a user and produces a comprehensive report.

Our Agent Team:

Supervisor (Claude 4 Opus): The project manager. It creates the plan and delegates tasks.
Researcher (Claude 4 Sonnet): The information gatherer. It uses a web search tool.
Analyst (Claude 4 Sonnet): The data specialist. It analyzes data (in this example, conceptually).
Writer (Claude 4 Sonnet): The content creator. It drafts the final report.

Step-by-Step Implementation

Here is the full Python code. We will walk through each part to ensure you understand exactly what it’s doing.

Step 1: Setup and Dependencies

First, we need to install the necessary libraries and set up our API keys.

pip install -U langgraph "langchain[anthropic]" langchain tavily-python

# In your Python file or notebook
import os

# Best practice: Set your API keys as environment variables
os.environ["ANTHROPIC_API_KEY"] = "YOUR_ANTHROPIC_API_KEY"
os.environ["TAVILY_API_KEY"] = "YOUR_TAVILY_API_KEY"

Step 2: Defining the Shared State

This is our “whiteboard.” It’s a TypedDict that defines all the pieces of information our agents will share during the workflow.

from typing import List, Dict, Optional, Annotated
from typing_extensions import TypedDict
import operator
from langchain_core.messages import BaseMessage

class AgentState(TypedDict):
    # The initial task given by the user.
    task: str
    # The plan created by the supervisor.
    plan: str
    # The list of messages exchanged between agents.
    # The 'operator.add' means new messages will be appended to this list.
    messages: Annotated[List[BaseMessage], operator.add]
    # Data found by the researcher.
    research_data: List[str]
    # Output from the analyst.
    analysis_output: Optional[str]
    # The current draft of the report.
    draft: str
    # The final report.
    report: str
    # The name of the next agent to act.
    agent_name: str

Step 3: Creating Tools for Our Agents

Our Researcher agent needs a tool to search the web. We’ll use the Tavily Search API.

from langchain_core.tools import tool
from tavily.tavily import TavilyClient

tavily = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

@tool
def web_search(query: str) -> str:
    """Performs a web search using Tavily to find information on a topic."""
    try:
        results = tavily.search(query=query, max_results=5)
        return "\n".join([res['content'] for res in results['results']])
    except Exception as e:
        return f"Error during web search: {e}"

Step 4: Defining the Agent Nodes

Now we create the functions that represent our worker agents. Each node takes the current state, calls the efficient Claude 4 Sonnet model, and returns an update.

from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage
from langgraph.prebuilt import ToolNode

# Use the efficient Sonnet model for all worker agents
worker_model = ChatAnthropic(model="claude-sonnet-4-20250514")

# A helper function to create our agent nodes
def create_agent_node(model, tools, system_message):
    agent_runnable = model.bind_tools(tools)
    def agent_node(state: AgentState):
        response = agent_runnable.invoke(
            [HumanMessage(content=system_message), HumanMessage(content=state['task'], name=state['agent_name'])]
        )
        return {"messages": [response]}
    return agent_node

# Create the nodes for our researcher and writer
researcher_node = create_agent_node(worker_model, [web_search], "You are a web researcher. Use the web_search tool to find information.")
writer_node = create_agent_node(worker_model, [], "You are a technical writer. Draft a report based on the provided research.")

# The ToolNode is a pre-built node that executes our web_search tool
tool_node = ToolNode([web_search])

Step 5: Defining the Supervisor Node

This is the most important node. It uses the powerful Claude 4 Opus model. Its job isn’t to do the work, but to decide who does the work next.

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field

# Use the powerful Opus model for the supervisor
supervisor_model = ChatAnthropic(model="claude-opus-4-20250514")

# Define the structure of the supervisor's decision
class Route(BaseModel):
    next: str = Field(description="The name of the next agent to route to, or 'FINISH' to end the workflow.")

# Create a prompt template to guide the supervisor's decision
planner_prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a supervisor agent. Your job is to manage a team of agents to complete a task. "
                   "Based on the user's request and the current progress, decide which agent should act next. "
                   "Your options are: Researcher, Writer, or FINISH."),
        ("human", "Task: {task}\nCurrent progress:\n{state_str}\n\nWhat is the next step?"),
    ]
)

# Chain the prompt with the model to get structured routing decisions
supervisor_chain = planner_prompt | supervisor_model.with_structured_output(Route)

def supervisor_node(state: AgentState):
    # Get a summary of the current state to help the supervisor decide
    state_str = f"Research Data available: {'Yes' if state.get('research_data') else 'No'}\n" \
                f"Draft available: {'Yes' if state.get('draft') else 'No'}"
    # Invoke the supervisor chain to get the next agent's name
    route = supervisor_chain.invoke({"task": state['task'], "state_str": state_str})
    return {"agent_name": route.next}

Step 6: Constructing and Compiling the Graph

Now we assemble our nodes and edges into a complete, runnable workflow.

from langgraph.graph import StateGraph, END

workflow = StateGraph(AgentState)

# Add all the nodes to the graph
workflow.add_node("Supervisor", supervisor_node)
workflow.add_node("Researcher", researcher_node)
workflow.add_node("Writer", writer_node)
workflow.add_node("call_tool", tool_node)

# Set the entry point of the graph
workflow.set_entry_point("Supervisor")

# Define the conditional edges from the supervisor
# This is the core routing logic
workflow.add_conditional_edges(
    "Supervisor",
    lambda x: x["agent_name"],
    {
        "Researcher": "Researcher",
        "Writer": "Writer",
        "FINISH": END,
    },
)

# Define the edges from the workers
workflow.add_edge("Researcher", "call_tool") # After researcher, call the tool
workflow.add_edge("call_tool", "Supervisor")  # After tool use, go back to supervisor
workflow.add_edge("Writer", "Supervisor")     # After writer, go back to supervisor

# Compile the graph into a runnable object
graph = workflow.compile()

You have now built a complete, multi-agent system! To run it, you would simply call graph.stream() with an initial task.

Part 3: Production and Advanced Strategy

Building a prototype is one thing; deploying a reliable, cost-effective production service is another.

Debugging with LangSmith is Not Optional

With complex, looping agent workflows, print() statements are not enough. LangSmith is an observability platform that is essential for building with LangGraph. It gives you a detailed trace of every single run, showing you exactly what each agent did, what tools it called, and what the state was at every step. It is the single most important tool for debugging and understanding your agent’s behavior.

Building for Failure: Error Handling in the Graph

Your agents will eventually fail. An API will time out, a tool will return an error. A production-ready graph must anticipate this. The best practice is to build error handling directly into your graph’s structure:

Track Errors in the State: Add an error field to your AgentState.
Catch Exceptions: Wrap your node logic in a try...except block.
Route to a Recovery Node: Use a conditional edge to check if the error field is populated. If it is, route to a special “error_handler” node that can decide whether to retry the step, use a different tool, or ask a human for help.

Conclusion: You Are Now an AI Architect

You’ve learned the fundamentals of the Claude 4 and LangGraph stack, and you’ve walked through the construction of a complete multi-agent system. The key principles to remember are:

Specialize Your Agents: Use a powerful “supervisor” (Opus) to plan and efficient “workers” (Sonnet) to execute.
Control the Flow: Use LangGraph’s explicit state, nodes, and edges to build predictable, reliable, and debuggable workflows.
Observe Everything: Use LangSmith from day one. You cannot fix what you cannot see.

By applying these engineering-focused principles, you can move beyond simple prompts and start architecting the truly autonomous, valuable AI systems that will define the next generation of software.

FREQUENTLY ASKED QUESTIONS (FAQ)

QUESTION: Why should I use LangGraph instead of a simpler LangChain AgentExecutor?

ANSWER: AgentExecutor is great for simple, single-agent workflows where an LLM uses tools in a loop. LangGraph is designed for building complex, multi-agent systems. It gives you explicit control over the workflow (the “graph”), allows for cycles and branching, provides robust state management, and makes it possible to orchestrate teams of specialized agents. Use LangGraph when you need reliability, control, and multi-agent collaboration.

QUESTION: How does state management in LangGraph actually work?

ANSWER: LangGraph’s state management is centered on a shared Python object, often a TypedDict or Pydantic model, that you define. This “state object” is passed to every node in the graph. When a node finishes its work, it returns a dictionary containing only the pieces of the state it wants to update. LangGraph then automatically merges this update into the main state object before passing it to the next node. This provides a single, persistent source of truth for the entire workflow.

QUESTION: What’s the best way to handle an agent getting stuck in a loop?

ANSWER: This is a common problem. The best solution is to set a recursion limit when you compile and run your graph (e.g., graph.stream(..., {"recursion_limit": 15})). This acts as a safety stop, preventing infinite loops. Additionally, your supervisor’s prompt should include clear instructions to output a “FINISH” command when the task is fully completed, providing a logical exit point.

QUESTION: Can I really mix Claude Opus and Sonnet models in the same graph?

ANSWER: Yes, absolutely. This is the recommended “best practice” architecture for building with LangGraph and Claude. You create different ChatAnthropic clients—one configured for “claude-opus-4…” and another for “claude-sonnet-4…”—and pass the appropriate client to each node. Your supervisor node gets the powerful Opus client, and your worker nodes get the efficient Sonnet client.

Build Multi-Role Agents with Claude AI & LangGraph