Build a correct LangGraph 1.0 ReAct agent with `create_react_agent` — typed tools,
error propagation, recursion caps, and stop conditions that actually stop. Use when
writing your first tool-calling agent, migrating from `AgentExecutor` / `initialize_agent`,
or diagnosing an agent that loops on vague prompts.
Trigger with "langgraph agent", "create_react_agent", "langgraph tool calling",
"AgentExecutor migration", "agent loop cost".
Build a correct LangGraph 1.0 ReAct agent with `create_react_agent` — typed tools,
error propagation, recursion caps, and stop conditions that actually stop. Use when
writing your first tool-calling agent, migrating from `AgentExecutor` / `initialize_agent`,
or diagnosing an agent that loops on vague prompts.
Trigger with "langgraph agent", "create_react_agent", "langgraph tool calling",
"AgentExecutor migration", "agent loop cost".
Designed for Claude Code, also compatible with Codex
LangChain LangGraph Agents (Python)
Overview
Two failure modes hit every team writing their first LangGraph 1.0 ReAct agent:
Loop-to-cap on vague prompts (P10).create_react_agent defaults to
recursion_limit=25. A prompt like "help me with my account" never converges —
the model calls a retrieval tool, gets irrelevant results, calls another tool,
and repeats until GraphRecursionError: Recursion limit of 25 reached without hitting a stop condition fires. Cost dashboards show the damage after the
fact: $5-$15 per runaway loop on Sonnet with a 3-tool agent, assuming no tool
is itself expensive.
Silent tool errors on legacy AgentExecutor (P09). The legacy executor
defaults handle_parsing_errors=True and catches tool exceptions, feeding the
error string back as the next observation. When the error serializes to empty
(e.g., a ValueError("") or an HTTP 500 with no body), the loop continues with
no signal. The agent says "I couldn't find the answer" — which was actually a
silent crash three tool calls ago.
This skill walks through defining typed tools with @tool + Pydantic; building
an agent with create_react_agent(model, tools, checkpointer=MemorySaver());
invoking with {"messages": [...]} and a thread-scoped config; setting
recursion_limit per expected agent depth (5-10 interactive, 20-30 planner);
adding middleware for a per-session token budget; and raise-by-default error
propagation. Pin: langgraph >= 1.0, < 2.0, langchain-core >= 1.0, < 2.0.
Pain-catalog anchors: P09, P10, P11, P32, P41, P42, P63.
"""Fetch an account record by UUID. Returns status, plan, and owner email."""
if
not
raise
"account_id is required"
# raised → agent sees real error
return
"id"
"status"
"active"
"plan"
"pro"
"owner"
"a@b.co"
Two rules that catch teams off-guard:
Docstring is the tool description the provider sees. Keep it under
1024 chars (P11). Anthropic truncates at ~1024; OpenAI's effective cap is
softer but still bites on tool descriptions over ~2KB. Long docstrings with
examples should move into a system prompt, not the tool description.
Raise real exceptions. Unlike the legacy AgentExecutor, LangGraph's
create_react_agent does not silently swallow tool errors — the exception
propagates and surfaces in your observability layer. See Step 6.
For async tools, use @tool on an async def — LangGraph invokes it via
await. For structured return types, annotate the return with a Pydantic model.
See Tool Definition Patterns for the
@tool vs tool() decision, async tools, and the args_schema vs
auto-inferred trade-off.
Step 2 — Build the agent with create_react_agent
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from langchain_anthropic import ChatAnthropic
model = ChatAnthropic(
model="claude-sonnet-4-6",
temperature=0,
timeout=30,
max_retries=2,
)
agent = create_react_agent(
model=model,
tools=[lookup_account],
checkpointer=MemorySaver(), # required for stateful invocations
)
create_react_agent is the LangGraph 1.0 replacement for the removed
initialize_agent factory (P41). Under the hood it builds a StateGraph with
a model node and a ToolNode, plus a conditional edge that routes to
END when the model emits no tool calls. The checkpointer persists state
per-thread — required for multi-turn conversations and for resuming after
interruption.
Step 3 — Invoke with a thread-scoped config
config = {"configurable": {"thread_id": "user-42"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "look up account uuid-abc"}]},
config=config,
)
print(result["messages"][-1].content)
Key contracts:
Input is {"messages": [...]} — a list of message dicts or LangChain
HumanMessage / SystemMessage objects. You append to this list across turns.
thread_id scopes the checkpointer. Reusing it resumes the conversation.
Output is the full updated state. result["messages"] is the complete
message list; the final assistant message is at index -1.
Step 4 — Set recursion_limit to your expected agent depth
create_react_agent defaults to recursion_limit=25. In LangGraph one
"recursion step" is one node visit, and each tool round-trip is two visits
(model node + tool node), so 25 means ~12 tool calls. For most workloads this
is too generous and hides bugs:
Agent kind
Suggested recursion_limit
Rationale
Interactive chat with 1-3 tools
5-10
One tool call + one final answer is 3 visits. Cap low to expose loops.
When the limit fires, LangGraph raises GraphRecursionError — catch it and
surface a user-facing message; do not retry without a cost guard.
Step 5 — Add a per-session token budget via middleware
recursion_limit alone does not bound cost. A single tool call that returns a
large document and triggers a long model response can cost more than 10 cheap
tool calls. Cap tokens explicitly:
A per-session budget of 50K tokens on Sonnet is roughly $0.25 — a safe cap for
interactive agents. For background planners raise to 200K-500K. See
Loop Caps and Budgets for a
repeated-tool-call early-stop node and a middleware pattern that terminates on
the N-th identical call.
Step 6 — Propagate tool errors; do not silently swallow
LangGraph's default is to raise. Legacy AgentExecutor(handle_parsing_errors=True)
swallowed everything. The new defaults are safer but different:
# Tool raises → the exception propagates out of agent.invoke()try:
result = agent.invoke({"messages": [{"role": "user", "content": "..."}]}, config=config)
except ValueError as e:
# Your tool's own ValueError — log + user-facing message
...
When you want tolerant behavior (e.g., the tool is a flaky third-party API
and you want the model to try a different approach), wrap the tool itself:
from langchain_core.tools import tool
@tooldefsearch_kb(query: str) -> str:
"""Search the internal knowledge base. Returns hits or a 'no results' string."""try:
return _real_search(query)
except HTTPError as e:
returnf"search_kb unavailable: {e.response.status_code}. Try a different query."
The key insight: the tool decides to degrade gracefully by returning a string
the model can reason about. The agent never silently drops an error. See
Error Propagation for a custom error-handler
node that routes tool failures to a fallback tool.
Step 7 — Choose create_react_agent vs custom StateGraph vs legacy
You need named nodes, explicit conditional edges, typed state
Multi-agent supervisor
create_supervisor + workers built with create_react_agent
Built-in routing, per-worker checkpointing
New code in 2026+
Never use AgentExecutor or initialize_agent
Removed / deprecated in 1.0 (P41); shape changes in intermediate_steps (P42)
For a single forced-tool single-shot (e.g., "always classify into one of these
buckets"), skip agents entirely: use model.bind_tools([Schema], tool_choice={"type": "tool", "name": "Schema"}). But never loop a forced
tool_choice (P63) — the model cannot emit stop_reason="end_turn" under
forced tool_choice, so the agent never terminates.
Output
Agent built with create_react_agent(model, tools, checkpointer=MemorySaver())
Tools defined with @tool + Pydantic args_schema, docstrings under 1024 chars
Use tool_choice="auto" for agent loops; reserve forced choice for one-shot calls
Agent hallucinates a tool name like exec that is not in tools=[...]
Older free-text ReAct parser accepts any string (P32)
Use create_react_agent — it relies on provider-native tool calling; the allowlist is wire-enforced
RuntimeError: Token budget exceeded
Your TokenBudget callback fired
Working as intended; raise the cap or shorten the agent's scope
Tool description truncated, model calls with wrong args
Docstring exceeded 1024-char cap (P11)
Shorten docstring; move examples into system prompt
Examples
Migrating a legacy AgentExecutor agent
Before (LangChain 0.2):
from langchain.agents import initialize_agent, AgentType
agent = initialize_agent(
tools, llm, agent=AgentType.OPENAI_FUNCTIONS,
handle_parsing_errors=True, return_intermediate_steps=True,
)
result = agent.invoke({"input": "..."})
for action, observation in result["intermediate_steps"]:
print(action.tool, observation) # .tool attribute
After (LangGraph 1.0):
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
agent = create_react_agent(llm, tools, checkpointer=MemorySaver())
result = agent.invoke(
{"messages": [{"role": "user", "content": "..."}]},
config={"configurable": {"thread_id": "t1"}, "recursion_limit": 10},
)
# intermediate steps are now ToolMessage entries in the messages listfor m in result["messages"]:
if m.type == "tool":
print(m.name, m.content) # .name, not .tool
See AgentExecutor Migration for the
full before/after including handle_parsing_errors, return_intermediate_steps,
and max_iterations translations.
Interactive agent with a strict cost cap
A customer-support agent with two tools, 10-step recursion cap, and a 30K
token budget. See Loop Caps and Budgets
for the full example with a repeated-tool-call early-stop node.
