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".
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.
