Introduction: Orchestrating Agents with State

Welcome back, aspiring AI architects! In our previous chapters, we explored the foundational concepts of AI agents, their components, and the challenges of building multi-step reasoning. We understood that truly intelligent agents often need to perform a sequence of actions, make decisions based on intermediate results, and even loop back to previous steps if needed. This is where the magic of orchestration frameworks comes into play.

This chapter introduces LangGraph, a powerful library designed to help you build robust, stateful, and cyclical agent workflows. Think of it as a sophisticated flowchart engine for your AI agents. You’ll learn how to define states, transitions, and nodes to create complex decision-making processes, enabling your agents to tackle much more intricate problems than simple one-shot prompts. By the end of this chapter, you’ll be able to design and implement dynamic multi-agent systems that can react intelligently to changing conditions.

Ready to bring structured decision-making to your agents? Let’s dive in!

Core Concepts: Understanding LangGraph’s Architecture

LangGraph is an extension of LangChain, specifically tailored for building stateful, multi-actor applications with cyclical graphs. This means it excels at scenarios where an agent needs to perform actions, observe outcomes, decide the next step, and potentially revisit earlier steps in a loop.

What is a State Machine?

At its heart, LangGraph leverages the concept of a state machine. Imagine a board game:

  • States are the squares on the board (e.g., “Start,” “Roll Dice,” “Buy Property,” “Jail”).
  • Transitions are the rules that move you from one square to another (e.g., “If you roll a 7, move 7 squares forward”).
  • Events are what trigger these transitions (e.g., “rolling the dice”).

In LangGraph, our “states” are the different stages of our agent’s workflow, and “transitions” are the decisions that move the workflow from one stage to the next, often based on the output of an LLM or a tool.

LangGraph’s Core Components

Let’s break down the key elements you’ll be working with:

  1. Graph State: This is the single source of truth for your entire workflow. It’s a dictionary-like object that holds all relevant information as your graph executes. Each node can read from and write to this state, allowing information to persist and evolve across steps.

  2. Nodes: These are the individual “steps” or “actions” in your workflow. A node can be:

    • An LLM call (e.g., asking an AI to generate text).
    • A tool invocation (e.g., calling an external API, performing a calculation).
    • A custom Python function (e.g., parsing data, making a conditional check). Each node takes the current Graph State as input and returns updates to that state.

  3. Edges: Edges define how your nodes are connected and how the workflow progresses.

    • Direct Edges: A simple, unconditional transition from one node to another. “After Node A, always go to Node B.”
    • Conditional Edges: These are the powerful decision-makers. They connect a source node to multiple potential target nodes, with a “router” function determining which path to take based on the current Graph State. “After Node A, if condition X is true, go to Node B; otherwise, go to Node C.”

  4. Checkpointers (Memory): For long-running or multi-turn conversations, LangGraph provides checkpointers. These allow you to save and restore the Graph State at any point, effectively giving your agent long-term memory across sessions. This is crucial for maintaining context in complex, interactive applications.

  5. Compiling the Graph: Once you’ve defined your nodes, edges, and initial state, you “compile” the graph. This transforms your definition into a runnable Runnable object, similar to those in LangChain Expression Language (LCEL).

Visualizing a LangGraph Workflow

Let’s imagine a simple research agent workflow:

flowchart TD Start[Start] --> Plan_Research{Plan Research} Plan_Research -->|Needs Web Search| Web_Search[Perform Web Search] Web_Search --> Summarize_Results[Summarize Results] Summarize_Results --> Evaluate_Summary{Evaluate Summary} Evaluate_Summary -->|Needs More Info| Plan_Research Evaluate_Summary -->|Satisfied| Generate_Report[Generate Report] Generate_Report --> End[End]

In this diagram:

  • Start, Plan Research, Web Search, Summarize Results, Evaluate Summary, Generate Report, End are all nodes.
  • The arrows are edges.
  • Plan Research and Evaluate Summary are conditional nodes because they have multiple outgoing edges based on decisions. Notice the loop from Evaluate Summary back to Plan Research – this is a core strength of LangGraph!

This graph demonstrates a perception-action loop: the agent plans, acts (web search), perceives the result (summary), evaluates, and then decides to either iterate (more info) or conclude (generate report).

Step-by-Step Implementation: Building a Simple Agent Workflow

Let’s roll up our sleeves and build a basic LangGraph application. We’ll create a simple agent that decides whether to use a tool or directly answer a question.

1. Setup and Installation

First, ensure you have Python 3.9+ installed. We’ll install the necessary libraries.

# As of 2026-03-20
pip install langgraph==0.0.40  # Or the latest stable version
pip install langchain==0.1.13 # Or the latest stable version
pip install langchain-openai==0.1.1 # Or the latest stable version
pip install python-dotenv==1.0.1 # For managing API keys

Next, create a .env file in your project root to store your OpenAI API key:

OPENAI_API_KEY="your_openai_api_key_here"

Remember to replace "your_openai_api_key_here" with your actual key.

2. Define the Graph State

Our graph needs a way to store information that passes between nodes. We’ll use a TypedDict for this, which helps with type hinting and readability.

Create a new Python file, e.g., agent_workflow.py.

# agent_workflow.py
import os
from typing import TypedDict, Annotated, List
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# --- 1. Define the Graph State ---
# This defines the input and output types for our graph.
class AgentState(TypedDict):
    """
    Represents the state of our agent workflow.
    - `input`: The initial user query.
    - `chat_history`: A list of messages in the conversation.
    - `intermediate_steps`: Steps taken by the agent (e.g., tool calls, LLM responses).
    - `answer`: The final answer from the agent.
    """
    input: str
    chat_history: Annotated[List[str], "append"] # Use Annotated for list append behavior
    intermediate_steps: Annotated[List[tuple], "append"]
    answer: str

Explanation:

  • AgentState(TypedDict): We define a class inheriting from TypedDict to specify the structure of our graph’s state.
  • input: str: This will hold the user’s initial query.
  • chat_history: Annotated[List[str], "append"]: A list to store the ongoing conversation. The Annotated type with "append" tells LangGraph to append to this list when a node returns updates for it, rather than overwriting it. This is crucial for maintaining conversation history.
  • intermediate_steps: Annotated[List[tuple], "append"]: This will store a log of actions the agent takes (e.g., tool calls and their outputs).
  • answer: str: To store the final generated answer.

3. Define the Tools

Our agent needs capabilities! Let’s create a simple tool that can perform a mock “search.”

# Continue in agent_workflow.py

from langchain_core.tools import tool

# --- 2. Define Tools ---
@tool
def search_web(query: str) -> str:
    """
    Simulates searching the web for a given query.
    In a real application, this would call a search API.
    """
    print(f"\n--- Calling Tool: search_web with query: '{query}' ---")
    if "latest news" in query.lower():
        return "The stock market is up today, and a new AI model was just released."
    elif "weather in london" in query.lower():
        return "It's partly cloudy with a high of 15°C in London."
    else:
        return f"Found generic information for '{query}'. (Simulated result)"

tools = [search_web]

Explanation:

  • @tool: This decorator from langchain_core.tools turns a regular Python function into a tool that an LLM can understand and invoke.
  • search_web(query: str) -> str: Our mock search function. It takes a query string and returns a simulated string result. In a real scenario, this would integrate with a search engine API like Google Search or DuckDuckGo.

4. Define the LLM and Agent

Now, let’s set up our language model and define our agent. LangGraph agents often wrap LangChain agents.

# Continue in agent_workflow.py

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

# --- 3. Define the LLM ---
llm = ChatOpenAI(model="gpt-4o", temperature=0) # Using gpt-4o as of 2026-03-20

# --- 4. Define the Agent ---
# The prompt for our agent
prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a helpful AI assistant. You have access to the following tools: {tools}"),
        MessagesPlaceholder("chat_history"),
        ("human", "{input}"),
        MessagesPlaceholder("agent_scratchpad"),
    ]
)

# Create an OpenAI tools agent
agent_runnable = create_openai_tools_agent(llm, tools, prompt)

# Define the agent node function
def agent_node(state: AgentState):
    """
    A node that executes the agent's logic (LLM call + tool usage).
    """
    print("\n--- Executing Agent Node ---")
    # Convert chat_history strings to HumanMessage objects for the agent
    messages = [HumanMessage(content=msg) if i % 2 == 0 else HumanMessage(content=msg) for i, msg in enumerate(state["chat_history"])]
    messages.append(HumanMessage(content=state["input"])) # Add current input

    # The agent_runnable expects a dict with 'input', 'chat_history', 'agent_scratchpad'
    result = agent_runnable.invoke(
        {"input": state["input"], "chat_history": messages, "agent_scratchpad": state["intermediate_steps"]}
    )
    # The result from create_openai_tools_agent is a dict, we need to extract the 'output' or 'tool_calls'
    # For simplicity, we'll append the full result to intermediate_steps.
    # In a real scenario, you might parse this to check for tool calls.
    return {"intermediate_steps": [(result.tool_calls, result.content)]}

Explanation:

  • llm = ChatOpenAI(...): We initialize our LLM. gpt-4o is a good choice for general reasoning and tool use as of early 2026. temperature=0 makes it more deterministic.
  • prompt: A ChatPromptTemplate defines how the LLM receives its instructions and context.
    • MessagesPlaceholder("chat_history"): This is crucial for maintaining conversation turns.
    • MessagesPlaceholder("agent_scratchpad"): Where the agent keeps track of its internal thoughts and tool outputs.
  • create_openai_tools_agent: A convenient LangChain utility to create an agent that can intelligently use OpenAI’s function calling capabilities with our defined tools.
  • agent_node(state: AgentState): This is our first actual node function for LangGraph.
    • It takes the AgentState as input.
    • It constructs the messages for the LLM, including the current input and chat_history.
    • It invokes the agent_runnable (our LLM agent).
    • It returns a dictionary of updates to the AgentState. Here, we’re appending the agent’s thought process/tool calls to intermediate_steps.

5. Define a Tool Node

When the agent decides to use a tool, we need a separate node to actually execute it.

# Continue in agent_workflow.py

from langchain.agents import AgentFinish
from langchain_core.agents import AgentAction, AgentFinish

# --- 5. Define Tool Node ---
def tool_node(state: AgentState):
    """
    A node that executes tool calls identified by the agent.
    """
    print("\n--- Executing Tool Node ---")
    # The agent_node returns a list of (tool_calls, content). We only care about tool_calls here.
    last_step_output = state["intermediate_steps"][-1][0] # Get the tool_calls from the last step

    if not last_step_output:
        # If no tool calls, something went wrong or agent decided not to use tool.
        # This case should ideally be handled by the router.
        return {"answer": "Agent did not make a tool call."}

    tool_outputs = []
    for tool_call in last_step_output:
        if tool_call.tool == "search_web":
            output = search_web.invoke(tool_call.args)
            tool_outputs.append((tool_call, output))
        else:
            tool_outputs.append((tool_call, f"Tool '{tool_call.tool}' not found."))
    return {"intermediate_steps": tool_outputs}

Explanation:

  • tool_node(state: AgentState): This node’s job is to take the tool calls identified by the LLM and execute them.
  • It extracts the tool_calls from the intermediate_steps of the previous agent_node output.
  • It iterates through the tool_calls and invokes the corresponding tool function (e.g., search_web.invoke).
  • The results are then added back to intermediate_steps, which will be fed back to the LLM in the next agent_node run.

6. Define the Router Node (Conditional Logic)

This is where the state machine’s decision-making happens. Our router decides whether the agent needs to call a tool, or if it has finished its task.

# Continue in agent_workflow.py

# --- 6. Define the Router Node ---
def router_node(state: AgentState):
    """
    This node decides whether the agent should continue, call a tool, or finish.
    """
    print("\n--- Executing Router Node ---")
    # Get the last output from the agent_node
    last_agent_output = state["intermediate_steps"][-1][0] # This is the tool_calls part

    if last_agent_output: # If there are tool calls
        print("Router: Detected tool calls. Moving to tool_node.")
        return "call_tool"
    else: # If there are no tool calls, the agent has likely finished its reasoning
        print("Router: No tool calls. Moving to finish.")
        return "end"

Explanation:

  • router_node(state: AgentState): This function receives the current AgentState.
  • It inspects the intermediate_steps to see if the last output from the agent_node contained any tool_calls.
  • If tool_calls exist, it returns "call_tool". This string will match a key in our conditional edges, directing the flow to the tool_node.
  • If no tool_calls are present, it means the agent has likely generated a final answer or decided it doesn’t need tools, so it returns "end".

7. Build and Compile the Graph

Now, let’s assemble all these pieces into a graph!

# Continue in agent_workflow.py

from langgraph.graph import StateGraph, END

# --- 7. Build and Compile the Graph ---
workflow = StateGraph(AgentState)

# Add nodes to the graph
workflow.add_node("agent", agent_node)
workflow.add_node("tool", tool_node)

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

# Add edges
# From agent node, we go to the router to decide next step
workflow.add_edge("agent", "router_node") # Direct edge to router

# The router_node will conditionally transition
workflow.add_conditional_edges(
    "router_node",
    router_node, # The function that determines the next node
    {
        "call_tool": "tool",  # If router_node returns "call_tool", go to "tool" node
        "end": END            # If router_node returns "end", terminate the graph
    }
)

# After a tool call, we always want to go back to the agent to process the tool's output
workflow.add_edge("tool", "agent")

# Compile the graph
app = workflow.compile()

print("\n--- Graph Compiled Successfully ---")
# You can visualize the graph using app.get_graph().draw_mermaid_sr()
# For simplicity, we'll just run it.

Explanation:

  • workflow = StateGraph(AgentState): We instantiate our graph, telling it what type of state it will manage.
  • workflow.add_node("agent", agent_node): Adds our agent function as a node named “agent”.
  • workflow.add_node("tool", tool_node): Adds our tool execution function as a node named “tool”.
  • workflow.set_entry_point("agent"): Specifies that the workflow always starts by calling the “agent” node.
  • workflow.add_edge("agent", "router_node"): After the “agent” node runs, it always transitions to our router_node. Note that router_node itself is not a node in the graph, but a function used by add_conditional_edges.
  • workflow.add_conditional_edges("router_node", router_node, {...}): This is the heart of the conditional logic.
    • The first argument ("router_node") specifies the source of the conditional edges.
    • The second argument (router_node) is our Python function that returns a string indicating the next node.
    • The dictionary maps the return value of router_node to the actual target node names or END.
      • If router_node returns "call_tool", the graph transitions to the tool node.
      • If router_node returns "end", the graph terminates (END).
  • workflow.add_edge("tool", "agent"): After the tool_node executes, we always send control back to the agent node. This allows the LLM agent to see the tool’s output and decide what to do next (e.g., provide a final answer, or call another tool).
  • app = workflow.compile(): This finalizes the graph definition, making it ready to run.

8. Run the Graph

Let’s test our agent!

# Continue in agent_workflow.py

# --- 8. Run the Graph ---
print("\n--- Running Graph ---")

# Example 1: A query that requires a tool
print("\n--- Query 1: What is the weather in London? ---")
inputs_1 = {"input": "What is the weather in London?", "chat_history": []}
for s in app.stream(inputs_1):
    print(s)
    print("---")

# Example 2: A query that the agent can answer directly
print("\n--- Query 2: What is 2 + 2? ---")
inputs_2 = {"input": "What is 2 + 2?", "chat_history": []}
for s in app.stream(inputs_2):
    print(s)
    print("---")

# Example 3: A query that requires a tool and then a final answer
print("\n--- Query 3: Tell me the latest news. ---")
inputs_3 = {"input": "Tell me the latest news.", "chat_history": []}
for s in app.stream(inputs_3):
    print(s)
    print("---")

# You can inspect the final state for more details
# final_state = app.invoke(inputs_1)
# print("\nFinal State for Query 1:", final_state)

Explanation:

  • app.stream(inputs): This method allows you to stream the output of each node as the graph executes, giving you visibility into the agent’s thought process.
  • We provide different inputs to demonstrate both tool usage and direct answers. Observe the print statements from the agent_node, tool_node, and router_node to follow the execution flow.

Complete agent_workflow.py 

import os
from typing import TypedDict, Annotated, List
from dotenv import load_dotenv

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.messages import BaseMessage, HumanMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.tools import tool
from langgraph.graph import StateGraph, END
from langchain_core.agents import AgentAction, AgentFinish

# Load environment variables
load_dotenv()

# --- 1. Define the Graph State ---
class AgentState(TypedDict):
    """
    Represents the state of our agent workflow.
    - `input`: The initial user query.
    - `chat_history`: A list of messages in the conversation.
    - `intermediate_steps`: Steps taken by the agent (e.g., tool calls, LLM responses).
    - `answer`: The final answer from the agent.
    """
    input: str
    chat_history: Annotated[List[str], "append"]
    intermediate_steps: Annotated[List[tuple], "append"]
    answer: str

# --- 2. Define Tools ---
@tool
def search_web(query: str) -> str:
    """
    Simulates searching the web for a given query.
    In a real application, this would call a search API.
    """
    print(f"\n--- Calling Tool: search_web with query: '{query}' ---")
    if "latest news" in query.lower():
        return "The stock market is up today, and a new AI model was just released."
    elif "weather in london" in query.lower():
        return "It's partly cloudy with a high of 15°C in London."
    else:
        return f"Found generic information for '{query}'. (Simulated result)"

tools = [search_web]

# --- 3. Define the LLM ---
llm = ChatOpenAI(model="gpt-4o", temperature=0) # Using gpt-4o as of 2026-03-20

# --- 4. Define the Agent Node ---
prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a helpful AI assistant. You have access to the following tools: {tools}"),
        MessagesPlaceholder("chat_history"),
        ("human", "{input}"),
        MessagesPlaceholder("agent_scratchpad"),
    ]
)

agent_runnable = create_openai_tools_agent(llm, tools, prompt)

def agent_node(state: AgentState):
    """
    A node that executes the agent's logic (LLM call + tool usage).
    """
    print("\n--- Executing Agent Node ---")
    messages = [HumanMessage(content=msg) for i, msg in enumerate(state["chat_history"])]
    messages.append(HumanMessage(content=state["input"]))

    result = agent_runnable.invoke(
        {"input": state["input"], "chat_history": messages, "agent_scratchpad": state["intermediate_steps"]}
    )
    # The result from create_openai_tools_agent is an AgentAction or AgentFinish
    # We append it to intermediate_steps for the router to inspect.
    # If it's an AgentAction, it means tool calls are requested.
    # If it's an AgentFinish, it means the agent has a final answer.
    if isinstance(result, AgentAction):
        # The result.tool_calls field will be populated for AgentAction
        return {"intermediate_steps": [(result.tool_calls, result.log)]}
    elif isinstance(result, AgentFinish):
        # The agent has a final answer
        return {"answer": result.return_values["output"]}
    else:
        # Fallback for unexpected types
        return {"intermediate_steps": [(None, str(result))]}


# --- 5. Define Tool Node ---
def tool_node(state: AgentState):
    """
    A node that executes tool calls identified by the agent.
    """
    print("\n--- Executing Tool Node ---")
    # The agent_node returns a list of (tool_calls, content) or just AgentFinish
    # We need to correctly extract the tool calls from the last step.
    last_step_output = state["intermediate_steps"][-1][0] # This should be a list of tool_calls or None

    if not last_step_output:
        # This case should ideally be caught by the router, but as a safeguard
        return {"answer": "Agent did not make a tool call, or tool calls were not correctly identified."}

    tool_outputs = []
    for tool_call in last_step_output: # Iterate through the actual tool calls
        if tool_call.tool == "search_web":
            output = search_web.invoke(tool_call.args)
            tool_outputs.append((tool_call, output))
        else:
            tool_outputs.append((tool_call, f"Tool '{tool_call.tool}' not found."))

    # After tool execution, we append the tool_outputs to intermediate_steps
    # This will be fed back to the agent in the next cycle.
    return {"intermediate_steps": tool_outputs}


# --- 6. Define the Router Node ---
def router_node(state: AgentState):
    """
    This node decides whether the agent should continue, call a tool, or finish.
    """
    print("\n--- Executing Router Node ---")
    # Check if the agent's last output was an AgentFinish (meaning it has a final answer)
    if state.get("answer"): # If 'answer' is populated, the agent has finished
        print("Router: Agent has a final answer. Moving to finish.")
        return "end"

    # Otherwise, check if the agent requested tool calls in its last intermediate_steps
    # last_step_output is expected to be a tuple (tool_calls, log) from agent_node
    last_step_output = state["intermediate_steps"][-1][0] # Get the tool_calls part

    if last_step_output: # If there are tool calls
        print("Router: Detected tool calls. Moving to tool_node.")
        return "call_tool"
    else:
        # This case implies the agent node ran but didn't provide tool calls or a final answer.
        # This could be an error or an edge case. For now, we'll try to go back to agent.
        # In a more robust system, you might have an 'error_node' here.
        print("Router: Agent did not provide tool calls or final answer. Looping back to agent.")
        return "continue_agent_reasoning"


# --- 7. Build and Compile the Graph ---
workflow = StateGraph(AgentState)

# Add nodes to the graph
workflow.add_node("agent", agent_node)
workflow.add_node("tool", tool_node)

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

# Add conditional edges from the router node
workflow.add_conditional_edges(
    "agent", # The node *before* the router logic
    router_node, # The function that determines the next node
    {
        "call_tool": "tool",  # If router_node returns "call_tool", go to "tool" node
        "end": END,           # If router_node returns "end", terminate the graph
        "continue_agent_reasoning": "agent" # Loop back to agent if needed
    }
)

# After a tool call, we always want to go back to the agent to process the tool's output
workflow.add_edge("tool", "agent")

# Compile the graph
app = workflow.compile()

print("\n--- Graph Compiled Successfully ---")

# --- 8. Run the Graph ---
print("\n--- Running Graph ---")

# Example 1: A query that requires a tool
print("\n--- Query 1: What is the weather in London? ---")
inputs_1 = {"input": "What is the weather in London?", "chat_history": [], "intermediate_steps": [], "answer": ""}
for s in app.stream(inputs_1):
    print(s)
    print("---")
# After the loop, the final state will be available in the 's' variable if the stream completes.
# Or, you can explicitly call app.invoke for the final state.
final_state_1 = app.invoke(inputs_1)
print(f"Final Answer 1: {final_state_1.get('answer', 'No final answer.')}\n")


# Example 2: A query that the agent can answer directly
print("\n--- Query 2: What is 2 + 2? ---")
inputs_2 = {"input": "What is 2 + 2?", "chat_history": [], "intermediate_steps": [], "answer": ""}
for s in app.stream(inputs_2):
    print(s)
    print("---")
final_state_2 = app.invoke(inputs_2)
print(f"Final Answer 2: {final_state_2.get('answer', 'No final answer.')}\n")


# Example 3: A query that requires a tool and then a final answer
print("\n--- Query 3: Tell me the latest news. ---")
inputs_3 = {"input": "Tell me the latest news.", "chat_history": [], "intermediate_steps": [], "answer": ""}
for s in app.stream(inputs_3):
    print(s)
    print("---")
final_state_3 = app.invoke(inputs_3)
print(f"Final Answer 3: {final_state_3.get('answer', 'No final answer.')}\n")

Important Note on AgentAction vs. AgentFinish: In LangChain’s create_openai_tools_agent, the invoke method can return either an AgentAction (indicating tool calls) or an AgentFinish (indicating a final answer). I’ve updated the agent_node and router_node to correctly handle these types, ensuring the workflow terminates when a final answer is generated.

Running the Code

Save the code above as agent_workflow.py and run it from your terminal:

python agent_workflow.py

Observe the output! You’ll see the agent’s thought process, tool calls, and final answers.

Mini-Challenge: Enhance the Agent’s Capabilities

You’ve built a solid foundation. Now, let’s expand its intelligence!

Challenge: Add a new tool to our agent’s arsenal that can perform simple arithmetic calculations. Modify the agent and graph to allow it to use this new tool when appropriate.

Steps:

  1. Define a new @tool function, e.g., calculator(expression: str) -> float. Make it perform basic eval() for simplicity (with a warning about security in real apps!).
  2. Add this new tool to the tools list.
  3. The agent_node and router_node should automatically adapt because create_openai_tools_agent and our router logic already handle arbitrary tool calls. However, you might need to adjust the tool_node to specifically invoke your new calculator tool.
  4. Test with a new query, e.g., “What is 123 * 456?”.

Hint: Remember to update the tool_node to include a elif tool_call.tool == "calculator": branch to correctly invoke your new tool.

What to observe/learn: How easily you can extend an agent’s capabilities by adding new tools and how LangGraph manages the flow between the agent’s reasoning and tool execution.

Common Pitfalls & Troubleshooting

Working with state machines and agents can introduce new complexities. Here are some common issues:

  1. Overly Complex Router Logic: As your workflows grow, your router_node can become a tangled mess of if/elif/else statements. This is a sign that you might need to:

    • Break down your workflow into smaller, more manageable sub-graphs.
    • Use more sophisticated decision-making within the router, possibly even an LLM-based router for complex choices.
    • Ensure each node clearly updates the state in a predictable way that the router can easily interpret.

  2. State Management Issues (Forgetting Updates): If nodes don’t correctly update the AgentState, subsequent nodes or the router might operate on outdated or missing information.

    • Troubleshooting: Use print(state) within each node to inspect the state at different points in the execution. Ensure your Annotated[List[..., "append"]] types are used correctly for lists you want to grow, not overwrite.

  3. Infinite Loops: Poorly defined conditional edges can lead to the graph cycling indefinitely between nodes without reaching an END state.

    • Example: An agent that repeatedly calls a tool, but the tool’s output never satisfies the condition to exit the loop.
    • Troubleshooting: Carefully design your router_node conditions. Introduce counters in the state to limit iterations, or add fallback paths to an END state after a certain number of loops. The app.stream() method is invaluable here for observing the loop.

  4. Token Usage and Cost: Each LLM call consumes tokens. Complex LangGraph workflows with many loops or extensive history in the state can quickly rack up API costs.

    • Best Practice: Optimize prompts, summarize chat_history or intermediate_steps for the LLM, and cache common LLM responses where appropriate.

Summary

Congratulations! You’ve successfully navigated the world of LangGraph and built a dynamic, stateful AI agent workflow. Let’s recap the key takeaways:

  • LangGraph is a powerful library for orchestrating multi-step, stateful, and cyclical AI agent applications using graph-based state machines.
  • State Machines provide a structured way to define complex workflows with States (nodes) and Transitions (edges).
  • The Graph State is the central repository of information, evolving as the workflow progresses.
  • Nodes are the individual steps (LLM calls, tool invocations, custom functions) that read from and write to the state.
  • Edges define the flow, with Conditional Edges (driven by router functions) enabling intelligent decision-making and looping.
  • You learned how to define tools, integrate an LLM-powered agent, and build the graph step-by-step.

LangGraph empowers you to move beyond linear agent chains to create truly adaptive and robust AI applications.

What’s Next?

In the next chapter, we’ll shift our focus to AutoGen, a framework that emphasizes multi-agent conversations and collaborative problem-solving, offering a different paradigm for orchestrating intelligent agents. Get ready to explore how agents can talk to each other to achieve complex goals!

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.