Why LangGraph, Not "LangChain Agents"

If you Google "LangChain agent tutorial," half the results show the old AgentExecutor API. Ignore them. That API is essentially deprecated.

The modern way to build agents with LangChain is LangGraph — a library for building stateful, multi-step agent workflows as directed graphs. It shipped in early 2025 and has become the recommended approach for anything beyond a trivial single-tool agent.

Why the shift? AgentExecutor was a black box. You couldn't control the execution flow, couldn't easily add human-in-the-loop checkpoints, couldn't persist state across runs. LangGraph fixes all of that by making the agent's control flow explicit and inspectable.

Here's what we're building: a research agent that takes a topic, searches the web, reads relevant pages, and produces a structured summary. Four tools, state management, and error handling — a real agent you could extend into a production system.

Setup: Install the Stack

pip install langchain-core langchain-openai langgraph tavily-python

You'll need two API keys:

OPENAI_API_KEY — for GPT-4o (or swap for Claude/Gemini)
TAVILY_API_KEY — for web search (free tier: 1000 searches/month)

Set them as environment variables or in a .env file.

Step 1: Define Your Tools

Our research agent needs four capabilities: search the web, read a web page, take notes, and produce a final report.

from langchain_core.tools import tool
from tavily import TavilyClient
import requests
from bs4 import BeautifulSoup

tavily = TavilyClient()

@tool
def web_search(query: str) -> str:
    """Search the web for current information on a topic.
    Returns top 5 results with titles, URLs, and snippets."""
    results = tavily.search(query=query, max_results=5)
    formatted = []
    for r in results["results"]:
        formatted.append(f"Title: {r['title']}\nURL: {r['url']}\nSnippet: {r['content'][:200]}")
    return "\n\n".join(formatted)

@tool
def read_webpage(url: str) -> str:
    """Read and extract the main text content from a webpage URL.
    Returns the first 3000 characters of readable text."""
    try:
        resp = requests.get(url, timeout=10, headers={"User-Agent": "Mozilla/5.0"})
        soup = BeautifulSoup(resp.text, "html.parser")
        # Remove script and style elements
        for tag in soup(["script", "style", "nav", "footer"]):
            tag.decompose()
        text = soup.get_text(separator="\n", strip=True)
        return text[:3000]
    except Exception as e:
        return f"Error reading {url}: {str(e)}"

@tool
def save_note(content: str, source_url: str = "") -> str:
    """Save a research note with optional source URL.
    Use this to accumulate findings as you research."""
    # In production, this would persist to a database
    return f"Note saved: {content[:100]}... (source: {source_url})"

tools = [web_search, read_webpage, save_note]

Notice the docstrings. They're not just documentation — the LLM reads them to decide when to call each tool. "Search the web for current information" tells GPT-4o this is the right tool for finding recent data. "Read and extract the main text content" signals this tool goes deeper on a specific URL.

Step 2: Define the Agent State

LangGraph agents carry a state object through every step. This is your short-term memory:

from typing import TypedDict, Annotated, Sequence
from langchain_core.messages import BaseMessage
from langgraph.graph.message import add_messages

class ResearchState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]
    research_topic: str
    notes: list[str]
    sources: list[str]
    final_report: str

The Annotated[..., add_messages] syntax is LangGraph's reducer pattern — it tells the framework to append new messages instead of replacing the list. Without this, each node would overwrite the conversation history.

Step 3: Build the Agent Graph

Now the core: defining the execution flow as a directed graph.

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from langchain_core.messages import SystemMessage, HumanMessage

# Initialize the LLM with tool binding
llm = ChatOpenAI(model="gpt-4o", temperature=0)
llm_with_tools = llm.bind_tools(tools)

SYSTEM_PROMPT = """You are a thorough research agent. Your job:
1. Search for information on the given topic
2. Read the most promising sources
3. Save key findings as notes
4. When you have enough information (at least 3 sources), produce a final summary

Be systematic. Search first, then deep-dive into the best results.
Always cite your sources."""

def research_agent(state: ResearchState) -> dict:
    """The main agent node — decides what to do next."""
    messages = [SystemMessage(content=SYSTEM_PROMPT)] + list(state["messages"])
    response = llm_with_tools.invoke(messages)
    return {"messages": [response]}

def should_continue(state: ResearchState) -> str:
    """Route: if the last message has tool calls, execute them.
    Otherwise, the agent is done."""
    last_message = state["messages"][-1]
    if last_message.tool_calls:
        return "tools"
    return "end"

# Build the graph
graph = StateGraph(ResearchState)
graph.add_node("agent", research_agent)
graph.add_node("tools", ToolNode(tools))

graph.set_entry_point("agent")
graph.add_conditional_edges("agent", should_continue, {
    "tools": "tools",
    "end": END
})
graph.add_edge("tools", "agent")  # After tools run, go back to agent

# Compile
research_app = graph.compile()

This graph has two nodes: the agent (which thinks and decides) and the tool executor (which runs the tools). The conditional edge checks if the agent wants to call tools or is done.

Step 4: Run the Agent

# Run the research agent
result = research_app.invoke({
    "messages": [HumanMessage(content="Research the current state of AI agent frameworks in 2026. Compare LangGraph, CrewAI, and AutoGen.")],
    "research_topic": "AI agent frameworks 2026",
    "notes": [],
    "sources": [],
    "final_report": ""
})

# Print the final response
print(result["messages"][-1].content)

When you run this, watch what happens. The agent will:

Call web_search with a relevant query
Examine the results and pick 2-3 promising URLs
Call read_webpage on each URL
Call save_note to record key findings
Produce a structured summary with citations

This typically takes 5-8 LLM calls and 3-5 tool calls. Total cost: around $0.05-0.10 with GPT-4o.

Step 5: Add Safety Rails

The agent above works, but it has no limits. A confused agent could loop forever, burning tokens. Add these guardrails:

from langgraph.errors import GraphRecursionError

# Option 1: Set a recursion limit on the graph
research_app = graph.compile()
config = {"recursion_limit": 25}  # Max 25 node visits

try:
    result = research_app.invoke(initial_state, config=config)
except GraphRecursionError:
    print("Agent hit recursion limit — may need a more focused prompt")

# Option 2: Add step counting in state
class ResearchState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]
    research_topic: str
    step_count: int  # Track how many steps we've taken

def should_continue(state: ResearchState) -> str:
    if state.get("step_count", 0) > 15:
        return "end"  # Force stop after 15 steps
    last_message = state["messages"][-1]
    if last_message.tool_calls:
        return "tools"
    return "end"

What You Just Built

This research agent is a Level 2 tool agent — the most common production pattern. It doesn't pre-plan (L3) or delegate to sub-agents (L4). It simply observes, reasons, acts, and repeats.

But the architecture — state graph, tool binding, conditional routing — is the same foundation you'll use for more complex agents. In Lesson 4, we'll take this further with multi-agent collaboration using CrewAI.

For more tools and integrations to connect to your agent, explore the MCP server directory and AI tools directory on Skila AI.

Building Your First Agent with LangChain

Related Resources