Skip to content
LgPy

LangGraph: Advanced Recipes & Real-World Patterns

Real-world LangGraph recipes: RAG with quality control, support routing, research fan-out, memory, map-reduce, tool interceptors, channels, the Functional API, tracing and per-tool streaming.

Checked against langgraph 1.2.22 and langchain 1.5.0 (2026-11-19). Each recipe is a complete program unless it says otherwise. Recipes 1–6 share the setup block below; the later recipes define their own imports. Examples were run with a stub chat model, so they show the control flow; answers from a real model will differ.

Retry, timeout and cache policies are not repeated here; see Node policies.

# Shared setup for recipes 1–6
import json
import operator
from typing import Annotated
from typing_extensions import TypedDict
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
model = init_chat_model("anthropic:claude-sonnet-5-5")

Retrieval-Augmented Generation with automatic re-retrieval and refinement:

from langgraph.graph import StateGraph, START, END
from langgraph.types import Send
from typing_extensions import TypedDict
from typing import Annotated
from langgraph.graph.message import add_messages
import json
def semantic_search(query: str, index: str, top_k: int = 5) -> list[dict]:
"""Stand-in for your vector store (for example a Store with an index, or a retriever)."""
corpus = [{"id": "doc-1", "content": "Install LangGraph with pip install langgraph."},
{"id": "doc-2", "content": "Compile a StateGraph before invoking it."}]
return corpus[:top_k]
class RAGState(TypedDict):
question: str
messages: Annotated[list, add_messages]
retrieved_docs: list[dict]
relevance_score: float
generation_attempt: int
final_answer: str
source_citations: list[str]
def retrieve_documents(state: RAGState) -> dict:
"""Retrieve relevant documents."""
question = state["question"]
# Use semantic search
docs = semantic_search(
query=question,
index="knowledge_base",
top_k=5
)
return {
"retrieved_docs": docs,
"messages": [{
"role": "system",
"content": f"Retrieved {len(docs)} documents"
}]
}
def grade_documents(state: RAGState) -> dict:
"""Grade relevance of retrieved documents."""
docs = state["retrieved_docs"]
question = state["question"]
# Use LLM to grade
graded = []
for doc in docs:
grade_prompt = f"""
Question: {question}
Document: {doc['content']}
Is this document relevant to the question? (yes/no)
Explain your reasoning.
"""
response = model.invoke(grade_prompt)
is_relevant = "yes" in response.content.lower()
if is_relevant:
graded.append(doc)
avg_relevance = len(graded) / len(docs) if docs else 0
return {
"retrieved_docs": graded,
"relevance_score": avg_relevance
}
def decide_strategy(state: RAGState) -> str:
"""Decide whether to generate, re-retrieve, or escalate."""
relevance = state["relevance_score"]
attempt = state["generation_attempt"]
if relevance > 0.7:
return "generate"
elif attempt < 2:
return "refine_query"
else:
return "escalate"
def refine_query(state: RAGState) -> dict:
"""Refine query for better retrieval."""
original_query = state["question"]
failed_attempt = state["retrieved_docs"]
refine_prompt = f"""
Original question: {original_query}
The retrieval wasn't successful. Rephrase the question to:
1. Be more specific
2. Include key terms
3. Clarify the intent
Provide only the refined question.
"""
response = model.invoke(refine_prompt)
refined_query = response.content
return {
"question": refined_query,
"generation_attempt": state["generation_attempt"] + 1,
"messages": [{
"role": "assistant",
"content": f"Query refined: {refined_query}"
}]
}
def generate_answer(state: RAGState) -> dict:
"""Generate answer from retrieved documents."""
question = state["question"]
docs = state["retrieved_docs"]
context = "\n\n".join([
f"Source {i+1} ({doc.get('title', 'Unknown')}):\n{doc['content']}"
for i, doc in enumerate(docs)
])
prompt = f"""
Question: {question}
Context from documents:
{context}
Provide a comprehensive answer based on the context.
Cite sources by referencing the source numbers (e.g., [1], [2]).
"""
response = model.invoke(prompt)
# Extract citations
citations = []
for i, doc in enumerate(docs):
source_id = f"[{i+1}]"
if source_id in response.content:
citations.append(f"{i+1}. {doc.get('title', 'Unknown')}")
return {
"final_answer": response.content,
"source_citations": citations,
"messages": [{
"role": "assistant",
"content": response.content
}]
}
def escalate(state: RAGState) -> dict:
"""Escalate to human when unable to answer."""
return {
"final_answer": "Unable to find relevant information. Escalating to human support.",
"source_citations": [],
"messages": [{
"role": "assistant",
"content": "This question requires human expert review."
}]
}
# Build RAG graph
rag_builder = StateGraph(RAGState)
rag_builder.add_node("retrieve", retrieve_documents)
rag_builder.add_node("grade", grade_documents)
rag_builder.add_node("generate", generate_answer)
rag_builder.add_node("refine", refine_query)
rag_builder.add_node("escalate", escalate)
rag_builder.add_edge(START, "retrieve")
rag_builder.add_edge("retrieve", "grade")
rag_builder.add_conditional_edges(
"grade",
decide_strategy,
{
"generate": "generate",
"refine_query": "refine",
"escalate": "escalate"
}
)
rag_builder.add_edge("generate", END)
rag_builder.add_edge("escalate", END)
rag_builder.add_edge("refine", "retrieve") # Loop back
rag_graph = rag_builder.compile(checkpointer=InMemorySaver())
# Usage
result = rag_graph.invoke(
{"question": "How do I set up LangGraph?", "generation_attempt": 0},
{"configurable": {"thread_id": "rag-1"}},
)
print(f"Answer: {result['final_answer']}")
print(f"Sources: {result['source_citations']}")

Recipe 2: Customer Support Ticket Classifier & Router

Section titled “Recipe 2: Customer Support Ticket Classifier & Router”

Classify support tickets and route to appropriate handler:

from enum import Enum
class TicketPriority(Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
CRITICAL = "critical"
class TicketCategory(Enum):
BILLING = "billing"
TECHNICAL = "technical"
FEATURE_REQUEST = "feature_request"
BUG = "bug"
OTHER = "other"
class SupportTicketState(TypedDict):
ticket_id: str
customer_email: str
subject: str
description: str
priority: TicketPriority
category: TicketCategory
assigned_to: str
response: str
needs_escalation: bool
def classify_ticket(state: SupportTicketState) -> dict:
"""Classify ticket priority and category."""
ticket_text = f"{state['subject']}\n{state['description']}"
classification_prompt = f"""
Classify this support ticket:
{ticket_text}
Respond with JSON:
{{
"priority": "low|medium|high|critical",
"category": "billing|technical|feature_request|bug|other",
"summary": "one line summary"
}}
"""
response = model.invoke(classification_prompt)
# Parse JSON response
import json
try:
result = json.loads(response.content)
priority = TicketPriority[result["priority"].upper()]
category = TicketCategory[result["category"].upper()]
except:
priority = TicketPriority.MEDIUM
category = TicketCategory.OTHER
return {
"priority": priority,
"category": category
}
def route_ticket(state: SupportTicketState) -> str:
"""Route to appropriate handler."""
if state["priority"] == TicketPriority.CRITICAL:
return "escalate"
elif state["category"] == TicketCategory.BILLING:
return "billing_handler"
elif state["category"] == TicketCategory.TECHNICAL:
return "tech_handler"
elif state["category"] == TicketCategory.BUG:
return "bug_handler"
else:
return "general_handler"
def billing_handler(state: SupportTicketState) -> dict:
"""Handle billing issues."""
prompt = f"""
Customer billing inquiry:
{state['description']}
Provide helpful guidance on billing.
"""
response = model.invoke(prompt)
return {
"response": response.content,
"assigned_to": "billing-team"
}
def tech_handler(state: SupportTicketState) -> dict:
"""Handle technical issues."""
prompt = f"""
Technical support request:
{state['description']}
Provide step-by-step technical guidance.
Suggest debugging steps.
"""
response = model.invoke(prompt)
return {
"response": response.content,
"assigned_to": "technical-support"
}
def bug_handler(state: SupportTicketState) -> dict:
"""Handle bug reports."""
prompt = f"""
Bug report:
{state['description']}
Acknowledge the bug.
Request additional information if needed.
Provide workaround if available.
"""
response = model.invoke(prompt)
return {
"response": response.content,
"assigned_to": "engineering"
}
def general_handler(state: SupportTicketState) -> dict:
"""Handle general inquiries."""
prompt = f"""
Customer inquiry:
{state['description']}
Provide helpful response.
"""
response = model.invoke(prompt)
return {
"response": response.content,
"assigned_to": "general-support"
}
def escalate(state: SupportTicketState) -> dict:
"""Escalate critical issues."""
escalation_prompt = f"""
Critical support ticket needs immediate attention:
Priority: {state['priority'].value}
Category: {state['category'].value}
Description: {state['description']}
Prepare escalation brief for management.
"""
response = model.invoke(escalation_prompt)
return {
"response": response.content,
"assigned_to": "management",
"needs_escalation": True
}
# Build support graph
support_builder = StateGraph(SupportTicketState)
support_builder.add_node("classify", classify_ticket)
support_builder.add_node("billing", billing_handler)
support_builder.add_node("technical", tech_handler)
support_builder.add_node("bug", bug_handler)
support_builder.add_node("general", general_handler)
support_builder.add_node("escalate", escalate)
support_builder.add_edge(START, "classify")
support_builder.add_conditional_edges(
"classify",
route_ticket,
{
"billing_handler": "billing",
"tech_handler": "technical",
"bug_handler": "bug",
"general_handler": "general",
"escalate": "escalate"
}
)
support_builder.add_edge("billing", END)
support_builder.add_edge("technical", END)
support_builder.add_edge("bug", END)
support_builder.add_edge("general", END)
support_builder.add_edge("escalate", END)
support_graph = support_builder.compile(checkpointer=InMemorySaver())
# Usage
result = support_graph.invoke(
{
"ticket_id": "TKT-001",
"customer_email": "user@example.com",
"subject": "Billing charge issue",
"description": "I was charged twice this month. Please help!",
},
{"configurable": {"thread_id": "TKT-001"}},
)
print(f"Priority: {result['priority'].value}")
print(f"Category: {result['category'].value}")
print(f"Response: {result['response']}")
print(f"Assigned to: {result['assigned_to']}")

Recipe 3: Research Agent with Parallel Data Sources

Section titled “Recipe 3: Research Agent with Parallel Data Sources”

Generate a few queries, search three kinds of source for each query in parallel, then write one report with citations. Each (source, query) pair is its own Send task, so nine searches run in the same super-step; the results key has an operator.add reducer so their writes combine.

The search function uses Tavily (pip install tavily-python, TAVILY_API_KEY): topic="news" for news, and include_domains to restrict “academic” searches to paper sites. Without a key it returns placeholder results, so the graph also runs offline.

import os
from pydantic import BaseModel
from langgraph.types import Send
class Queries(BaseModel):
queries: list[str]
class ResearchState(TypedDict, total=False):
topic: str
research_queries: list[str]
results: Annotated[list[dict], operator.add] # every search task appends here
synthesized_report: str
citations: list[dict]
class SearchTask(TypedDict):
source: str # "web" | "academic" | "news"
query: str
def search(source: str, query: str, max_results: int = 3) -> list[dict]:
"""Return [{"title", "url", "content"}] for one source."""
if not os.getenv("TAVILY_API_KEY"):
url = f"https://example.com/{source}?q={query.replace(' ', '+')}"
return [{"title": f"{source} result for {query}", "url": url, "content": "placeholder"}]
from tavily import TavilyClient
client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
kwargs: dict = {"max_results": max_results}
if source == "news":
kwargs["topic"] = "news"
elif source == "academic":
kwargs["include_domains"] = ["arxiv.org", "semanticscholar.org", "acm.org"]
response = client.search(query, **kwargs)
return [{"title": r["title"], "url": r["url"], "content": r["content"]} for r in response["results"]]
def generate_queries(state: ResearchState) -> dict:
"""Ask the model for three queries; fall back to the topic itself."""
try:
planned = model.with_structured_output(Queries).invoke(
f"Write three web search queries to research: {state['topic']}. "
"One for an overview, one for recent developments, one for expert opinion."
)
queries = planned.queries[:3] or [state["topic"]]
except Exception: # model refused or returned bad JSON
queries = [state["topic"]]
return {"research_queries": queries}
def fan_out(state: ResearchState) -> list[Send]:
return [
Send("search_source", {"source": source, "query": q})
for q in state["research_queries"]
for source in ("web", "academic", "news")
]
def search_source(task: SearchTask) -> dict:
hits = search(task["source"], task["query"])
return {"results": [{**h, "source": task["source"], "query": task["query"]} for h in hits]}
def synthesize_report(state: ResearchState) -> dict:
by_source: dict[str, list[dict]] = {}
for r in state["results"]:
by_source.setdefault(r["source"], []).append(r)
sections = "\n\n".join(
f"{source.title()} results:\n" + "\n".join(f"- {r['title']}: {r['content'][:200]}" for r in hits[:5])
for source, hits in by_source.items()
)
response = model.invoke(
f"Topic: {state['topic']}\n\n{sections}\n\n"
"Write a short research report: overview, key findings, recent developments, open questions. "
"Cite sources by title."
)
seen, citations = set(), []
for r in state["results"]:
if r["url"] not in seen:
seen.add(r["url"])
citations.append({"title": r["title"], "url": r["url"], "source": r["source"]})
return {"synthesized_report": response.content, "citations": citations}
research_graph = (
StateGraph(ResearchState)
.add_node("generate_queries", generate_queries)
.add_node("search_source", search_source)
.add_node("synthesize", synthesize_report)
.add_edge(START, "generate_queries")
.add_conditional_edges("generate_queries", fan_out, ["search_source"])
.add_edge("search_source", "synthesize") # runs once, after all nine searches
.add_edge("synthesize", END)
.compile()
)
result = research_graph.invoke({"topic": "AI safety evaluations"})
print(len(result["results"]), "search hits")
print(result["synthesized_report"][:500])
for i, cite in enumerate(result["citations"][:5], 1):
print(f"{i}. [{cite['source']}] {cite['title']} {cite['url']}")

Notes:

  • search_source receives only its SearchTask payload, not the whole state. That keeps the parallel tasks independent; everything they need is in the Send.
  • A failing search fails the run, because an error_handler does not catch failures in parallel tasks. Wrap the call in try/except inside search_source and return an error entry if partial results are acceptable.
  • To cap concurrent API calls, pass {"max_concurrency": 3} in the config.

Autonomous agent that reasons and acts:

import uuid
from langgraph.prebuilt import ToolNode, tools_condition
from langchain_core.tools import tool
# Define specialized tools
@tool
def search_knowledge_base(query: str) -> str:
"""Search internal knowledge base."""
# Replace with your search backend
docs = {"returns": "Items can be returned within 30 days.", "shipping": "Orders ship in 2 days."}
return "\n".join(text for key, text in docs.items() if key in query.lower()) or "No matching articles."
@tool
def check_inventory(product_id: str) -> dict:
"""Check product inventory."""
return {
"product_id": product_id,
"in_stock": True,
"quantity": 50
}
@tool
def submit_order(user_id: str, items: list[dict]) -> dict:
"""Submit an order."""
order_id = f"ORD-{uuid.uuid4().hex[:8].upper()}"
return {
"order_id": order_id,
"status": "confirmed",
"total": 99.99
}
@tool
def send_email(to: str, subject: str, body: str) -> str:
"""Send email notification."""
# Send email
return f"Email sent to {to}"
tools = [
search_knowledge_base,
check_inventory,
submit_order,
send_email
]
# The model must be bound to the tools, or it can never call them
model_with_tools = model.bind_tools(tools)
# Build custom agent for more control
class AgentState(TypedDict):
messages: Annotated[list, add_messages]
user_request: str
reasoning: str
action_taken: bool
def agent_reasoning_node(state: AgentState) -> dict:
"""Agent reasons about what to do."""
system_prompt = (
"You are a helpful shopping assistant. Analyse user requests, decide what "
"actions to take, and use the available tools to help the customer."
)
response = model_with_tools.invoke([("system", system_prompt), *state["messages"]])
# Capture reasoning
reasoning = response.content
has_tool_calls = hasattr(response, 'tool_calls') and len(response.tool_calls) > 0
return {
"messages": [response],
"reasoning": reasoning,
"action_taken": has_tool_calls
}
# Build agentic graph
agent_builder = StateGraph(AgentState)
agent_builder.add_node("reasoning", agent_reasoning_node)
agent_builder.add_node("tools", ToolNode(tools))
agent_builder.add_edge(START, "reasoning")
# Use tools_condition for automatic routing
agent_builder.add_conditional_edges(
"reasoning",
tools_condition,
{"tools": "tools", END: END}
)
agent_builder.add_edge("tools", "reasoning") # Loop back
agentic_graph = agent_builder.compile(checkpointer=InMemorySaver())
# Usage
config = {"configurable": {"thread_id": "customer-123"}}
result = agentic_graph.invoke({
"messages": [{
"role": "user",
"content": "I want to buy 2 units of product ABC123"
}],
"user_request": "Purchase items",
"reasoning": ""
}, config=config)
print("Final response:", result["messages"][-1].content)

Multi-stage document processing with quality checks:

from enum import Enum
class DocumentType(Enum):
PDF = "pdf"
DOCX = "docx"
JSON = "json"
TEXT = "text"
class ProcessingState(TypedDict):
document_id: str
document_content: str
document_type: DocumentType
extraction_result: dict
validation_result: dict
enrichment_result: dict
processing_status: str
error_message: str
def extract_content(state: ProcessingState) -> dict:
"""Extract structured content from document."""
try:
if state["document_type"] == DocumentType.PDF:
# PDF extraction
content = extract_text_from_pdf(state["document_content"])
elif state["document_type"] == DocumentType.DOCX:
# DOCX extraction
content = extract_text_from_docx(state["document_content"])
else:
content = state["document_content"]
# Use LLM to structure the content
extraction_prompt = f"""
Extract structured information from this document:
{content[:2000]} # First 2000 chars
Extract:
1. Title
2. Key sections
3. Main topics
4. Metadata (author, date, etc)
Return as JSON.
"""
response = model.invoke(extraction_prompt)
import json
extracted = json.loads(response.content)
return {
"extraction_result": extracted,
"processing_status": "extracted"
}
except Exception as e:
return {
"error_message": str(e),
"processing_status": "extraction_failed"
}
def validate_content(state: ProcessingState) -> dict:
"""Validate extracted content quality."""
if state["processing_status"] == "extraction_failed":
return {"validation_result": {"valid": False}}
extracted = state["extraction_result"]
validation_prompt = f"""
Validate this extracted content:
{json.dumps(extracted, indent=2)}
Check:
1. Completeness - all expected fields present
2. Accuracy - information makes sense
3. Format - proper structure
Return: {{"valid": true/false, "issues": ["list of issues"]}}
"""
response = model.invoke(validation_prompt)
import json
validation = json.loads(response.content)
return {"validation_result": validation}
def enrich_content(state: ProcessingState) -> dict:
"""Enrich content with additional insights."""
if not state["validation_result"].get("valid"):
return {"enrichment_result": {}}
extracted = state["extraction_result"]
enrichment_prompt = f"""
Enrich this document with:
1. Summary
2. Key entities (people, organizations, concepts)
3. Related topics
4. Action items
5. Risk assessment (if applicable)
Content:
{json.dumps(extracted, indent=2)}
Return as JSON.
"""
response = model.invoke(enrichment_prompt)
import json
enrichment = json.loads(response.content)
return {
"enrichment_result": enrichment,
"processing_status": "complete"
}
# Build document processing pipeline
doc_builder = StateGraph(ProcessingState)
doc_builder.add_node("extract", extract_content)
doc_builder.add_node("validate", validate_content)
doc_builder.add_node("enrich", enrich_content)
doc_builder.add_edge(START, "extract")
doc_builder.add_edge("extract", "validate")
doc_builder.add_edge("validate", "enrich")
doc_builder.add_edge("enrich", END)
doc_pipeline = doc_builder.compile()
# Usage
result = doc_pipeline.invoke({
"document_id": "doc-001",
"document_content": "Your PDF/document content here",
"document_type": DocumentType.PDF
})
if result["processing_status"] == "complete":
print("Extraction:", result["extraction_result"])
print("Enrichment:", result["enrichment_result"])
else:
print("Error:", result["error_message"])

Recipe 6: Conversation with Long-term Memory

Section titled “Recipe 6: Conversation with Long-term Memory”

Keep a per-user profile and searchable memories in a store, so a new conversation (a new thread_id) can use what earlier ones learned. The checkpointer keeps each thread’s messages; the store keeps what outlives a thread.

Nodes reach the store through runtime.store (InjectedStore is for tools run by ToolNode, not for nodes). The example uses InMemoryStore with a toy embedding so it runs anywhere; in production pass AsyncPostgresStore (or SqliteStore) with a real embedding model to compile(store=...) and nothing else changes.

import asyncio
import uuid
from datetime import datetime, timezone
from langgraph.runtime import Runtime
from langgraph.store.memory import InMemoryStore
def toy_embed(texts: list[str]) -> list[list[float]]:
"""Deterministic stand-in for an embedding model (replace in production)."""
return [[len(t) / 100.0, sum(map(ord, t)) % 97 / 97.0] for t in texts]
store = InMemoryStore(index={"dims": 2, "embed": toy_embed, "fields": ["content"]})
class ConversationState(TypedDict, total=False):
user_id: str
messages: Annotated[list, add_messages]
user_profile: dict
relevant_memories: list[str]
async def load_context(state: ConversationState, runtime: Runtime) -> dict:
user_id = state["user_id"]
profile_item = await runtime.store.aget(("users", user_id), "profile")
profile = profile_item.value if profile_item else {"name": user_id, "conversation_count": 0}
hits = await runtime.store.asearch(
("users", user_id, "memories"), query=state["messages"][-1].content, limit=3
)
return {"user_profile": profile, "relevant_memories": [h.value["content"] for h in hits]}
async def chat(state: ConversationState) -> dict:
profile = state["user_profile"]
memories = "\n".join(f"- {m}" for m in state.get("relevant_memories", [])) or "- none yet"
system = (
f"You are a helpful assistant talking to {profile['name']} "
f"(conversation #{profile['conversation_count'] + 1}).\n"
f"Relevant notes from earlier conversations:\n{memories}"
)
response = await model.ainvoke([{"role": "system", "content": system}, *state["messages"]])
return {"messages": [response]}
async def save_memory(state: ConversationState, runtime: Runtime) -> dict:
user_id = state["user_id"]
user_msg, reply = state["messages"][-2].content, state["messages"][-1].content
await runtime.store.aput(
("users", user_id, "memories"),
f"mem-{uuid.uuid4().hex[:8]}",
{"content": f"User said: {user_msg} | Assistant said: {reply}",
"at": datetime.now(timezone.utc).isoformat()},
)
profile = {**state["user_profile"], "conversation_count": state["user_profile"]["conversation_count"] + 1}
await runtime.store.aput(("users", user_id), "profile", profile)
return {}
conversation_graph = (
StateGraph(ConversationState)
.add_node("load_context", load_context)
.add_node("chat", chat)
.add_node("save_memory", save_memory)
.add_edge(START, "load_context")
.add_edge("load_context", "chat")
.add_edge("chat", "save_memory")
.add_edge("save_memory", END)
.compile(checkpointer=InMemorySaver(), store=store)
)
async def main() -> None:
# Two separate conversations (threads) for the same user.
for thread, text in [("conv-1", "I'm planning a trip to Kyoto in April."),
("conv-2", "What was I planning?")]:
result = await conversation_graph.ainvoke(
{"user_id": "alice", "messages": [{"role": "user", "content": text}]},
{"configurable": {"thread_id": thread}},
)
print(thread, "memories used:", result["relevant_memories"])
profile = await store.aget(("users", "alice"), "profile")
print(profile.value) # {'name': 'alice', 'conversation_count': 2}
asyncio.run(main())

The second conversation starts with an empty message history but finds the first conversation’s note through the store. For production memory, summarise what is worth keeping (with a model call, or in a background job) rather than storing every exchange verbatim.


Recipe 7: Cached Multi-Agent Research System

Section titled “Recipe 7: Cached Multi-Agent Research System”

Uses: CachePolicy, InMemoryCache, InMemoryStore, parallel Send fan-out

# Imports verified against langgraph==1.2.22
import operator
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Send, RetryPolicy, CachePolicy
from langgraph.store.memory import InMemoryStore
from langgraph.cache.memory import InMemoryCache
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.runtime import Runtime
# ---------------------------------------------------------------------------
# State schema
# ---------------------------------------------------------------------------
class ResearchState(TypedDict):
user_id: str
topic: str
search_queries: list[str]
# reducer: all parallel researcher writes are accumulated
research_results: Annotated[list[dict], operator.add]
final_report: str
class WorkerState(TypedDict):
"""Narrow state used by each parallel worker node."""
query: str
# ---------------------------------------------------------------------------
# Nodes
# ---------------------------------------------------------------------------
def load_prefs_and_plan(state: ResearchState, runtime: Runtime) -> dict:
"""Load user preferences from the store and generate search queries."""
store = runtime.store
user_id = state["user_id"]
# Read stored preferences (or use defaults)
prefs_item = store.get(("users", user_id), "research_prefs") if store else None
prefs = prefs_item.value if prefs_item else {
"depth": "standard", # or "comprehensive"
"max_queries": 3,
}
topic = state["topic"]
n = prefs.get("max_queries", 3)
# In production: call an LLM to generate queries
queries = [f"{topic} - aspect {i+1}" for i in range(n)]
return {"search_queries": queries}
def fan_out(state: ResearchState) -> list[Send]:
"""Conditional edge: launch one researcher per query in parallel."""
return [Send("researcher", {"query": q}) for q in state["search_queries"]]
def researcher(state: WorkerState) -> dict:
"""Research a single query — runs in parallel (one per Send).
Results are merged into research_results via the operator.add reducer.
"""
query = state["query"]
# In production: call a search API or LLM here
result = {
"query": query,
"summary": f"[stub] findings for '{query}'",
"sources": [f"https://example.com/search?q={query.replace(' ', '+')}"],
}
return {"research_results": [result]}
def synthesise(state: ResearchState, runtime: Runtime) -> dict:
"""Combine all parallel results into a final report and save to store."""
store = runtime.store
all_results = state["research_results"]
bullets = "\n".join(f"- {r['query']}: {r['summary']}" for r in all_results)
report = f"## Research Report: {state['topic']}\n\n{bullets}"
# Persist for future look-up
if store:
store.put(
("users", state["user_id"], "reports"),
state["topic"],
{"report": report, "query_count": len(all_results)},
)
return {"final_report": report}
# ---------------------------------------------------------------------------
# Graph construction
# ---------------------------------------------------------------------------
builder = StateGraph(ResearchState)
builder.add_node(
"plan",
load_prefs_and_plan,
)
builder.add_node(
"researcher",
researcher,
# Retry transient errors; cache results for 10 minutes per unique query
retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.5),
cache_policy=CachePolicy(ttl=600),
)
builder.add_node("synthesise", synthesise)
builder.add_edge(START, "plan")
builder.add_conditional_edges("plan", fan_out) # dynamic fan-out
builder.add_edge("researcher", "synthesise")
builder.add_edge("synthesise", END)
# Pass both store (long-term memory) and cache (node result caching)
store = InMemoryStore()
cache = InMemoryCache()
checkpointer = InMemorySaver()
research_graph = builder.compile(
checkpointer=checkpointer,
store=store,
cache=cache,
)
# ---------------------------------------------------------------------------
# Usage
# ---------------------------------------------------------------------------
cfg = {"configurable": {"thread_id": "research-session-1"}}
result = research_graph.invoke(
{"user_id": "alice", "topic": "AI in healthcare", "search_queries": [], "research_results": [], "final_report": ""},
cfg,
)
print(result["final_report"])
# Second run: identical queries hit the cache (CachePolicy ttl=600)
result2 = research_graph.invoke(
{"user_id": "alice", "topic": "AI in healthcare", "search_queries": [], "research_results": [], "final_report": ""},
cfg,
)
print(result2["final_report"]) # same content, returned from cache

Recipe 8: Smart Shopping Assistant with agent middleware

Section titled “Recipe 8: Smart Shopping Assistant with agent middleware”

Uses: create_agent with a custom state schema, @dynamic_prompt and @after_model middleware, tools that read state through ToolRuntime and update it with Command.

from typing import Any
from typing_extensions import NotRequired
from langchain.agents import create_agent, AgentState
from langchain.agents.middleware import after_model, dynamic_prompt, ModelRequest
from langchain.messages import ToolMessage
from langchain.tools import tool, ToolRuntime
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.runtime import Runtime
from langgraph.types import Command
class ShoppingState(AgentState):
user_id: NotRequired[str]
cart: NotRequired[list[dict]]
total: NotRequired[float]
tokens_used: NotRequired[int]
@tool
def add_to_cart(product_name: str, price: float, quantity: int, runtime: ToolRuntime) -> Command:
"""Add a product to the shopping cart."""
state = runtime.state
item = {"name": product_name, "price": price, "qty": quantity}
return Command(update={
"cart": [*state.get("cart", []), item],
"total": state.get("total", 0.0) + price * quantity,
# A tool that returns a Command must include the ToolMessage itself
"messages": [ToolMessage(f"Added {quantity} x {product_name}", tool_call_id=runtime.tool_call_id)],
})
@tool
def view_cart(runtime: ToolRuntime) -> str:
"""Show the current cart."""
cart = runtime.state.get("cart", [])
if not cart:
return "Your cart is empty."
lines = [f"- {i['name']} x{i['qty']} ${i['price'] * i['qty']:.2f}" for i in cart]
return "\n".join(lines) + f"\nTotal: ${runtime.state.get('total', 0.0):.2f}"
@tool
def search_products(category: str) -> list[dict]:
"""Search products in a category."""
catalogue = {
"laptop": [{"name": "MacBook Pro 16", "price": 2499.0}, {"name": "Dell XPS 15", "price": 1799.0}],
"monitor": [{"name": "LG 27in 4K", "price": 499.0}],
}
return catalogue.get(category.lower(), [])
@dynamic_prompt
def cart_context(request: ModelRequest) -> str:
"""Put the cart summary in the system prompt for every model call."""
s = request.state
return (f"You are a shopping assistant for user {s.get('user_id', 'unknown')}. "
f"Cart: {len(s.get('cart', []))} item(s), total ${s.get('total', 0.0):.2f}.")
@after_model(state_schema=ShoppingState)
def track_tokens(state: ShoppingState, runtime: Runtime) -> dict[str, Any]:
usage = getattr(state["messages"][-1], "usage_metadata", None) or {}
return {"tokens_used": state.get("tokens_used", 0) + usage.get("total_tokens", 0)}
shopping_agent = create_agent(
"anthropic:claude-sonnet-5-5",
tools=[add_to_cart, view_cart, search_products],
state_schema=ShoppingState,
middleware=[cart_context, track_tokens],
checkpointer=InMemorySaver(),
)
cfg = {"configurable": {"thread_id": "shopper-123"}, "recursion_limit": 25}
result = shopping_agent.invoke(
{"messages": [{"role": "user", "content": "Find me a laptop for programming and add the best one."}],
"user_id": "shopper-123"},
cfg,
)
print("Cart:", result.get("cart", []))
print(f"Total: ${result.get('total', 0.0):.2f}")
print("Tokens used:", result.get("tokens_used", 0))
print("Reply:", result["messages"][-1].content)

Notes:

  • The state schema subclasses langchain.agents.AgentState, which already has messages. (The older create_react_agent needed a remaining_steps key in a custom schema; create_agent does not.)
  • A tool that returns a Command must include a ToolMessage for its own call in update["messages"]; otherwise the model sees a tool call with no result.
  • @dynamic_prompt rebuilds the system prompt on every model call, so it always reflects the current cart without adding messages to the history.

Recipe 9: Intelligent Workflow Coordinator

Section titled “Recipe 9: Intelligent Workflow Coordinator”

Uses: Command routing, Send fan-out, defer=True node, RetryPolicy

# Imports verified against langgraph==1.2.22
import operator
from typing import Annotated, Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, Send, RetryPolicy
from langgraph.checkpoint.memory import InMemorySaver
# ---------------------------------------------------------------------------
# State schema
# ---------------------------------------------------------------------------
TASK_TYPES = ["data", "training", "validation"]
class WorkflowState(TypedDict):
workflow_id: str
tasks: list[dict] # list of {"id":..., "type":..., "priority":...}
completed: Annotated[list[str], operator.add] # reducer: accumulate completed task ids
failed: Annotated[list[str], operator.add] # reducer: accumulate failed task ids
workflow_status: str
class TaskState(TypedDict):
"""Narrow state injected into each worker by Send."""
task_id: str
task_type: str
# ---------------------------------------------------------------------------
# Nodes
# ---------------------------------------------------------------------------
def coordinator(state: WorkflowState) -> Command[Literal["run_task", "__end__"]]:
"""Decide whether to launch tasks or finish.
Returns Command(goto=[Send(...), ...]) while there are pending tasks,
or Command(goto=END, update={"workflow_status": "complete"}) when done.
"""
completed = state.get("completed", [])
failed = state.get("failed", [])
done = completed + failed
pending = [t for t in state["tasks"] if t["id"] not in done]
if not pending:
return Command(
goto=END,
update={"workflow_status": f"done — {len(completed)} ok, {len(failed)} failed"},
)
# goto accepts a list of Send objects: one parallel run_task per pending task
return Command(goto=[Send("run_task", {"task_id": t["id"], "task_type": t["type"]}) for t in pending])
def run_task(state: TaskState) -> dict:
"""Execute a single task. Runs in parallel — one instance per Send.
Results accumulate back into WorkflowState via the operator.add reducer
on 'completed' / 'failed'.
"""
task_id = state["task_id"]
task_type = state["task_type"]
# Simulate work — replace with real logic
success = task_type != "validation" # pretend validation fails
if success:
print(f" [task] {task_id} ({task_type}) OK")
return {"completed": [task_id]}
else:
print(f" [task] {task_id} ({task_type}) FAILED")
return {"failed": [task_id]}
# ---------------------------------------------------------------------------
# Graph construction
#
# Key features demonstrated:
# - coordinator uses Command for dynamic routing (no static edges from it)
# - coordinator returns Command(goto=[Send, ...]) for variable-width parallelism
# - run_task uses retry_policy so transient failures are retried automatically
# - defer=True on the aggregate node means it runs AFTER all parallel run_task
# instances in the same super-step finish
# ---------------------------------------------------------------------------
def aggregate(state: WorkflowState) -> dict:
"""Summarise. Runs only after all parallel run_task nodes complete
because it is registered with defer=True.
"""
return {
"workflow_status": (
f"aggregated: {len(state.get('completed', []))} completed, "
f"{len(state.get('failed', []))} failed"
)
}
builder = StateGraph(WorkflowState)
builder.add_node("coordinator", coordinator)
builder.add_node(
"run_task",
run_task,
retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.1),
)
builder.add_node(
"aggregate",
aggregate,
defer=True, # waits for all non-deferred nodes in the same super-step
)
builder.add_edge(START, "coordinator")
# coordinator -> run_task edges come from its Command(goto=[Send(...)])
builder.add_edge("run_task", "aggregate")
builder.add_edge("aggregate", "coordinator") # loop back — coordinator will exit via END
# ---------------------------------------------------------------------------
# Usage
# ---------------------------------------------------------------------------
graph = builder.compile(checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "workflow-001"}}
result = graph.invoke(
{
"workflow_id": "ml-pipeline-001",
"tasks": [
{"id": "data_task", "type": "data", "priority": 1},
{"id": "training_task", "type": "training", "priority": 2},
{"id": "validation_task", "type": "validation", "priority": 3},
],
"completed": [],
"failed": [],
"workflow_status": "pending",
},
{**cfg, "recursion_limit": 50}, # recursion_limit goes in the same config dict
)
print(f"Workflow Status: {result['workflow_status']}")
print(f"Completed tasks: {result['completed']}")
print(f"Failed tasks: {result['failed']}")
# Workflow Status: done — 2 ok, 1 failed

Recipe 10: Long-Term Memory with Vector Search and InMemoryStore

Section titled “Recipe 10: Long-Term Memory with Vector Search and InMemoryStore”

Uses: InMemoryStore with vector index, Runtime context injection, per-user memory namespaces

A complete chatbot that persists and retrieves user preferences using InMemoryStore with optional vector search. The Runtime object carries both the store and a typed context object so nodes stay pure functions.

from langgraph.store.memory import InMemoryStore
from langgraph.graph.message import MessagesState, add_messages
from langgraph.graph import StateGraph, START, END
from langgraph.runtime import Runtime
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
from typing import Annotated
from typing_extensions import TypedDict
from dataclasses import dataclass
# Store with vector search. In production pass an embedding model, for example
# {"dims": 1536, "embed": "openai:text-embedding-3-small"}. A toy embedding keeps
# this example offline.
def embed_fn(texts: list[str]) -> list[list[float]]:
return [[float(len(t)), float(t.count(" ")), 1.0] for t in texts]
store = InMemoryStore(index={"dims": 3, "embed": embed_fn, "fields": ["content"]})
# Typed context carried through the run
@dataclass
class UserContext:
user_id: str
class ChatState(MessagesState):
pass
def recall_memories(state: ChatState, runtime: Runtime[UserContext]) -> dict:
"""Load relevant memories from long-term store."""
user_id = runtime.context.user_id
# Get last user message for search
last_msg = state["messages"][-1].content if state["messages"] else ""
# Search for relevant memories
memories = runtime.store.search(
("memories", user_id),
query=last_msg,
limit=3
)
if memories:
mem_text = "\n".join(f"- {m.value['content']}" for m in memories)
system = SystemMessage(content=f"User memories:\n{mem_text}")
return {"messages": [system]}
return {}
def save_memory(state: ChatState, runtime: Runtime[UserContext]) -> dict:
"""Save important facts to long-term store."""
user_id = runtime.context.user_id if runtime.context else "anon"
last_ai = state["messages"][-1] if state["messages"] else None
if not last_ai:
return {}
import uuid
runtime.store.put(
("memories", user_id),
str(uuid.uuid4()),
{"content": last_ai.content[:500]}
)
return {}
def call_model(state: ChatState) -> dict:
# model invocation
return {"messages": [AIMessage(content="Response...")]}
builder = StateGraph(ChatState, context_schema=UserContext)
builder.add_node("recall", recall_memories)
builder.add_node("agent", call_model)
builder.add_node("save", save_memory)
builder.add_edge(START, "recall")
builder.add_edge("recall", "agent")
builder.add_edge("agent", "save")
builder.add_edge("save", END)
graph = builder.compile(store=store)
# Pass run context with the context= keyword (not inside "configurable")
result = graph.invoke(
{"messages": [HumanMessage("I prefer dark mode")]},
context=UserContext(user_id="alice"),
)
print(result["messages"][-1].content)
# On subsequent runs the recalled memories are injected as a SystemMessage
# before the agent node, so the model always has the user's preferences in
# its context window.

Key points:

  • InMemoryStore accepts an index dict to enable semantic (vector) search via store.search(..., query=...). Omit it for key-only lookup.
  • Runtime[UserContext] is injected automatically by LangGraph when declared as a node parameter; it exposes .context, .store, and .stream_writer.
  • context_schema=UserContext on StateGraph declares the type of runtime.context; pass the value with invoke(..., context=UserContext(...)).

Recipe 11: Parallel Map-Reduce with Send and BinaryOperatorAggregate

Section titled “Recipe 11: Parallel Map-Reduce with Send and BinaryOperatorAggregate”

Uses: Send for fan-out, Annotated[list, operator.add] reducer for fan-in, ToolRuntime inside a tool

A document-analysis pipeline that dispatches each document to a parallel analyze_doc node, then reduces all results in a single reduce_results node.

import operator
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Send
from langgraph.prebuilt.tool_node import ToolRuntime
from langgraph.store.base import BaseStore
from langchain_core.tools import tool
# ── State ────────────────────────────────────────────────────────────────────
class PipelineState(TypedDict):
documents: list[str] # raw document texts to process
# BinaryOperatorAggregate: each parallel branch appends its slice
analysis_results: Annotated[list[dict], operator.add]
summary: str
# ── Parallel branch state (sent via Send) ────────────────────────────────────
class DocState(TypedDict):
doc_text: str
analysis_results: Annotated[list[dict], operator.add]
# ── Tool that uses ToolRuntime to access the store ───────────────────────────
@tool
def save_insight(
doc_id: str,
insight: str,
runtime: ToolRuntime,
) -> str:
"""Persist an insight from a document into the shared store."""
if runtime.store:
import uuid
runtime.store.put(
("insights",),
str(uuid.uuid4()),
{"doc_id": doc_id, "insight": insight}
)
if runtime.stream_writer:
runtime.stream_writer({"saved_insight": insight})
return f"Saved insight for {doc_id}"
# ── Nodes ────────────────────────────────────────────────────────────────────
def fan_out(state: PipelineState) -> list[Send]:
"""Create one Send per document — each runs analyze_doc in parallel."""
return [
Send("analyze_doc", {"doc_text": doc, "analysis_results": []})
for doc in state["documents"]
]
def analyze_doc(state: DocState) -> dict:
"""Analyse a single document (runs in parallel for every document)."""
text = state["doc_text"]
# Simulated analysis — replace with real LLM / extraction logic
result = {
"length": len(text),
"preview": text[:80],
"sentiment": "positive" if "good" in text.lower() else "neutral",
}
return {"analysis_results": [result]} # appended by reducer
def reduce_results(state: PipelineState) -> dict:
"""Runs only after ALL analyze_doc branches have completed (fan-in)."""
results = state["analysis_results"]
avg_length = sum(r["length"] for r in results) / max(len(results), 1)
sentiments = [r["sentiment"] for r in results]
summary = (
f"Processed {len(results)} documents. "
f"Avg length: {avg_length:.0f} chars. "
f"Sentiments: {', '.join(set(sentiments))}."
)
return {"summary": summary}
# ── Graph ────────────────────────────────────────────────────────────────────
builder = StateGraph(PipelineState)
builder.add_node("analyze_doc", analyze_doc)
builder.add_node("reduce_results", reduce_results)
# fan_out returns a list[Send] — LangGraph dispatches each in parallel
builder.add_conditional_edges(START, fan_out, ["analyze_doc"])
# All analyze_doc branches converge here
builder.add_edge("analyze_doc", "reduce_results")
builder.add_edge("reduce_results", END)
pipeline = builder.compile()
result = pipeline.invoke({
"documents": [
"This is a good product review.",
"The service was okay.",
"Great experience overall — good work!"
],
"analysis_results": [],
"summary": ""
})
print(result["summary"])
# Processed 3 documents. Avg length: 37 chars. Sentiments: positive, neutral.

Key points:

  • Annotated[list, operator.add] is a BinaryOperatorAggregate channel. Each parallel branch writes {"analysis_results": [single_item]} and LangGraph concatenates them automatically; no explicit merge node is needed.
  • Send("node_name", partial_state) lets you dynamically create parallel branches at runtime. The partial state is merged into the branch’s state before the node runs.
  • ToolRuntime is injected by ToolNode when a @tool declares it as a parameter. It exposes .store, .state, .stream_writer, and .tool_call_id — giving tools read/write access to cross-thread memory without coupling them to a specific state schema.

Recipe 12: State-Aware Shopping Agent with InjectedState + InjectedStore

Section titled “Recipe 12: State-Aware Shopping Agent with InjectedState + InjectedStore”

This recipe demonstrates how InjectedState and InjectedStore let tools access graph state and persistent storage without exposing internal details to the LLM.

from typing import Any, Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END, MessagesState
from langgraph.prebuilt import ToolNode, InjectedState, InjectedStore, tools_condition
from langgraph.store.memory import InMemoryStore
from langchain_core.tools import tool
from langchain_anthropic import ChatAnthropic
# Extend MessagesState with domain-specific fields
class ShopState(MessagesState):
user_id: str
cart: list[dict] # [{"id": str, "name": str, "price": float}]
user_tier: str # "standard" | "premium"
# ── Tools ────────────────────────────────────────────────────────────────────
@tool
def add_to_cart(
product_id: str,
product_name: str,
price: float,
# Injected from state — invisible to LLM
cart: Annotated[list, InjectedState("cart")],
user_tier: Annotated[str, InjectedState("user_tier")],
) -> str:
"""Add a product to the shopping cart."""
discount = 0.20 if user_tier == "premium" else 0.0
final_price = price * (1 - discount)
# Note: returning a string here; ToolNode wraps it in ToolMessage
return (
f"Added {product_name!r} at ${final_price:.2f}"
f"{' (20% premium discount applied)' if discount else ''}. "
f"Cart now has {len(cart) + 1} item(s)."
)
@tool
def view_cart(
state: Annotated[dict, InjectedState()],
) -> str:
"""View the current cart contents."""
cart = state.get("cart", [])
tier = state.get("user_tier", "standard")
if not cart:
return f"Cart is empty ({tier} account)."
lines = [f" • {item['name']}: ${item['price']:.2f}" for item in cart]
return f"Cart ({tier}, {len(cart)} items):\n" + "\n".join(lines)
@tool
def save_preference(
key: str,
value: str,
user_id: Annotated[str, InjectedState("user_id")],
store: Annotated[Any, InjectedStore()],
) -> str:
"""Save a shopping preference (e.g. favourite brand, size)."""
store.put(("preferences", user_id), key, {"value": value})
return f"Saved preference: {key} = {value}"
@tool
def get_preference(
key: str,
user_id: Annotated[str, InjectedState("user_id")],
store: Annotated[Any, InjectedStore()],
) -> str:
"""Retrieve a previously saved shopping preference."""
item = store.get(("preferences", user_id), key)
if item is None:
return f"No preference found for '{key}'."
return f"Your {key}: {item.value['value']}"
# ── Agent setup ───────────────────────────────────────────────────────────────
tools = [add_to_cart, view_cart, save_preference, get_preference]
model = ChatAnthropic(model="claude-haiku-5-5").bind_tools(tools)
persistent_store = InMemoryStore()
def agent_node(state: ShopState) -> dict:
return {"messages": [model.invoke(state["messages"])]}
builder = StateGraph(ShopState)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile(store=persistent_store)
# ── Usage ─────────────────────────────────────────────────────────────────────
from langchain_core.messages import HumanMessage
result = graph.invoke({
"messages": [HumanMessage("Add some Sony headphones for $299 to my cart")],
"user_id": "user-42",
"cart": [],
"user_tier": "premium",
})
print(result["messages"][-1].content)
# "Added 'Sony headphones' at $239.20 (20% premium discount applied). Cart now has 1 item(s)."

Recipe 13: Resetting Accumulated State with Overwrite

Section titled “Recipe 13: Resetting Accumulated State with Overwrite”

When a node needs to replace an accumulator channel rather than append to it, use Overwrite to bypass the reducer entirely.

import operator
from typing import Annotated, Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Overwrite
from langgraph.checkpoint.memory import InMemorySaver
class PipelineState(TypedDict):
batch_id: str
events: Annotated[list[str], operator.add] # accumulates across nodes
errors: Annotated[list[str], operator.add]
phase: str
# Normal accumulation — appends to events
def process_batch(state: PipelineState) -> dict:
batch = state["batch_id"]
return {
"events": [f"processed:{batch}"],
"phase": "processed",
}
# Appends error detail
def handle_error(state: PipelineState) -> dict:
return {
"errors": [f"error in batch {state['batch_id']}"],
"events": [f"error:{state['batch_id']}"],
"phase": "errored",
}
# Clears both lists — hard reset before re-processing
def reset_state(state: PipelineState) -> dict:
return {
"events": Overwrite(value=[f"reset:{state['batch_id']}"]),
"errors": Overwrite(value=[]),
"phase": "reset",
}
def route(state: PipelineState) -> Literal["handle_error", "reset_state", "__end__"]:
if state["errors"]:
return "handle_error"
if state["phase"] == "reset":
return "__end__"
return "__end__"
builder = StateGraph(PipelineState)
builder.add_node("process", process_batch)
builder.add_node("handle_error", handle_error)
builder.add_node("reset_state", reset_state)
builder.add_edge(START, "process")
builder.add_conditional_edges("process", route)
builder.add_edge("handle_error", "reset_state")
builder.add_edge("reset_state", END)
graph = builder.compile(checkpointer=InMemorySaver())
# Run with a batch that will have an error, then reset
# In practice you'd trigger the error condition via routing logic
cfg = {"configurable": {"thread_id": "batch-007"}} # required with a checkpointer
result = graph.invoke({
"batch_id": "batch-007",
"events": ["initial"],
"errors": [],
"phase": "pending",
}, cfg)
print(result["events"]) # depends on routing; after reset → ["reset:batch-007"]
print(result["errors"]) # [] — overwritten by reset_state

Only one node may Overwrite a given channel per super-step. If two concurrent nodes both return Overwrite(...) for the same channel, LangGraph raises InvalidUpdateError.


Recipe 14: Checkpoint History Browser with CheckpointTuple

Section titled “Recipe 14: Checkpoint History Browser with CheckpointTuple”

Use CheckpointTuple to build a debugging tool that inspects every state the graph passed through, and supports rewinding to any historical step.

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import StateUpdate
from typing_extensions import TypedDict
class WorkflowState(TypedDict):
input: str
draft: str
score: float
revision: int
def draft_step(state: WorkflowState) -> dict:
return {
"draft": f"Draft #{state['revision'] + 1} for: {state['input']}",
"revision": state["revision"] + 1,
"score": 0.5 + state["revision"] * 0.1,
}
saver = InMemorySaver()
builder = StateGraph(WorkflowState)
builder.add_node("draft", draft_step)
builder.add_edge(START, "draft")
builder.add_edge("draft", END)
graph = builder.compile(checkpointer=saver)
config = {"configurable": {"thread_id": "audit-demo"}}
# Run three times to build up history
for _ in range(3):
graph.invoke({"input": "AI trends", "draft": "", "score": 0.0, "revision": 0}, config)
# ── Browse checkpoint history ─────────────────────────────────────────────────
print("=== Checkpoint History ===")
checkpoints = list(saver.list(config))
for i, cp in enumerate(checkpoints):
meta = cp.metadata
vals = cp.checkpoint.get("channel_values", {})
print(
f"[{i}] source={meta.get('source')!r:8} "
f"step={meta.get('step'):3} "
f"revision={vals.get('revision', '?')} "
f"score={vals.get('score', '?')}"
)
# ── Time-travel: rewind to an earlier step ──────────────────────────────────
# Pick the second-oldest checkpoint (index -1 is newest)
target_cp = checkpoints[-2]
past_state = graph.get_state(target_cp.config)
print(f"\nRewound to revision={past_state.values['revision']}, score={past_state.values['score']}")
# Continue from that historical point (forks the thread)
resumed = graph.invoke(None, target_cp.config)
print(f"After resume: revision={resumed['revision']}, score={resumed['score']}")
# ── Filter by source ─────────────────────────────────────────────────────────
loop_checkpoints = list(saver.list(config, filter={"source": "loop"}))
print(f"\nLoop checkpoints: {len(loop_checkpoints)}")

Recipe 15: Human-in-the-Loop Approval with update_state and StateUpdate

Section titled “Recipe 15: Human-in-the-Loop Approval with update_state and StateUpdate”

Pause the graph at a sensitive step, let a human review and modify state, then resume:

from typing import Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import StateUpdate
class ApprovalState(TypedDict):
request: str
draft_action: str
approved: bool
reviewer_note: str
result: str
def generate_action(state: ApprovalState) -> dict:
"""Generate a proposed action (requires human approval before executing)."""
return {
"draft_action": f"Transfer $10,000 for: {state['request']}",
"approved": False,
}
def execute_action(state: ApprovalState) -> dict:
"""Execute the approved action."""
if not state["approved"]:
return {"result": "Cancelled — not approved."}
return {
"result": f"Executed: {state['draft_action']}. Note: {state['reviewer_note']}"
}
saver = InMemorySaver()
builder = StateGraph(ApprovalState)
builder.add_node("generate", generate_action)
builder.add_node("execute", execute_action)
builder.add_edge(START, "generate")
builder.add_edge("generate", "execute") # interrupted here in practice
builder.add_edge("execute", END)
# Interrupt AFTER generate so the human sees the draft before execute runs
graph = builder.compile(checkpointer=saver, interrupt_after=["generate"])
config = {"configurable": {"thread_id": "approval-thread"}}
# Step 1: Start the graph — it pauses after "generate"
graph.invoke(
{"request": "vendor invoice #1234", "draft_action": "", "approved": False,
"reviewer_note": "", "result": ""},
config,
)
# Step 2: Human reviews draft_action via get_state
state = graph.get_state(config)
print("Draft action:", state.values["draft_action"])
# → "Transfer $10,000 for: vendor invoice #1234"
# Step 3: Human approves (and optionally edits)
graph.update_state(
config,
{
"approved": True,
"reviewer_note": "Verified invoice matches PO-5678",
# Human can also change draft_action here if needed
},
as_node="generate", # treat this as if generate emitted the update
)
# Step 4: Resume — execute now runs
final = graph.invoke(None, config)
print("Result:", final["result"])
# → "Executed: Transfer $10,000 for: vendor invoice #1234. Note: Verified invoice matches PO-5678"
# ── Bulk update: apply multiple edits atomically ─────────────────────────────
# For multi-field updates you want transactional, use bulk_update_state:
graph.bulk_update_state(
config,
[
[StateUpdate({"approved": True}, as_node="generate")],
[StateUpdate({"reviewer_note": "All clear"}, as_node="generate")],
],
)

Recipe 16: ToolRuntime — unified runtime injection

Section titled “Recipe 16: ToolRuntime — unified runtime injection”

ToolRuntime is the single dataclass injected into any tool that declares runtime: ToolRuntime. It replaces the older InjectedState / InjectedStore annotations with one unified parameter, and additionally exposes tool_call_id, config, stream_writer, and the full tools list.

import datetime
from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import AnyMessage
from langchain_core.tools import tool
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.prebuilt.tool_node import ToolRuntime
from langgraph.store.memory import InMemoryStore
from langgraph.checkpoint.memory import InMemorySaver
from langchain_anthropic import ChatAnthropic
class WorkflowState(TypedDict):
messages: Annotated[list[AnyMessage], add_messages]
user_id: str
session_start: str
@tool
def save_research_note(topic: str, content: str, runtime: ToolRuntime) -> str:
"""Save a research note to long-term memory for the current user.
Args:
topic: Short topic label for the note.
content: The note content to persist.
"""
user_id = runtime.state["user_id"] # read from graph state
call_id = runtime.tool_call_id # unique per invocation
# Persist to the store — survives across threads
runtime.store.put(
("research", user_id),
call_id,
{
"topic": topic,
"content": content,
"saved_at": datetime.datetime.utcnow().isoformat(),
},
)
# Stream a custom event visible to any stream consumer
runtime.stream_writer({"note_saved": {"topic": topic, "call_id": call_id}})
return f"Note on '{topic}' saved (id={call_id[:8]})"
@tool
def list_notes(runtime: ToolRuntime) -> str:
"""List all research notes saved for the current user."""
user_id = runtime.state["user_id"]
items = runtime.store.search(("research", user_id))
if not items:
return "No notes saved yet."
lines = [f"- {item.value['topic']}: {item.value['content'][:60]}" for item in items]
return "\n".join(lines)
tools = [save_research_note, list_notes]
model = ChatAnthropic(model="claude-opus-5-5").bind_tools(tools)
store = InMemoryStore()
def call_model(state: WorkflowState) -> dict:
return {"messages": [model.invoke(state["messages"])]}
graph = StateGraph(WorkflowState)
graph.add_node("agent", call_model)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", tools_condition)
graph.add_edge("tools", "agent")
app = graph.compile(checkpointer=InMemorySaver(), store=store)
result = app.invoke(
{
"messages": [{"role": "user", "content": "Save a note: LangGraph uses Pregel-style supersteps"}],
"user_id": "alice",
"session_start": datetime.datetime.utcnow().isoformat(),
},
config={"configurable": {"thread_id": "alice-session-1"}},
)

Recipe 17: ToolNode.wrap_tool_call — interceptor for retries, caching, and auditing

Section titled “Recipe 17: ToolNode.wrap_tool_call — interceptor for retries, caching, and auditing”

wrap_tool_call is a sync interceptor that wraps every tool execution inside a ToolNode. Use it for cross-cutting concerns — rate-limiting, audit logging, result caching — without modifying each tool individually.

import hashlib
import json
import time
from collections import defaultdict
from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import AnyMessage, ToolMessage
from langchain_core.tools import tool
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.prebuilt.tool_node import ToolCallRequest
from langchain_anthropic import ChatAnthropic
# ── Simple in-process cache ──────────────────────────────────────────────────
_result_cache: dict[str, tuple[str, float]] = {}
_call_log: list[dict] = []
_call_counts: dict[str, list[float]] = defaultdict(list)
RATE_LIMIT_PER_MINUTE = 10
CACHE_TTL_SECONDS = 120
def observability_wrapper(request: ToolCallRequest, execute) -> ToolMessage:
"""Layer rate-limiting, caching, and audit logging onto every tool call."""
tool_name = request.tool_call["name"]
args = request.tool_call["args"]
call_id = request.tool_call["id"]
now = time.time()
# ── 1. Rate limiting ─────────────────────────────────────────────────────
window = [t for t in _call_counts[tool_name] if now - t < 60]
_call_counts[tool_name] = window
if len(window) >= RATE_LIMIT_PER_MINUTE:
return ToolMessage(
content=f"Rate limit hit for '{tool_name}'. Retry in {60 - (now - window[0]):.0f}s.",
tool_call_id=call_id,
)
_call_counts[tool_name].append(now)
# ── 2. Cache lookup ──────────────────────────────────────────────────────
cache_key = hashlib.md5(
json.dumps({"tool": tool_name, "args": args}, sort_keys=True).encode()
).hexdigest()
if cache_key in _result_cache:
cached_content, cached_at = _result_cache[cache_key]
if now - cached_at < CACHE_TTL_SECONDS:
_call_log.append({"call_id": call_id, "tool": tool_name, "source": "cache"})
return ToolMessage(content=cached_content, tool_call_id=call_id)
# ── 3. Execute and cache result ──────────────────────────────────────────
result: ToolMessage = execute(request) # the handler takes the (possibly modified) request
_result_cache[cache_key] = (result.content, now)
_call_log.append({
"call_id": call_id,
"tool": tool_name,
"args": args,
"source": "live",
"timestamp": now,
})
return result
# ── Tools ────────────────────────────────────────────────────────────────────
@tool
def get_exchange_rate(from_currency: str, to_currency: str) -> str:
"""Get the exchange rate between two currencies."""
# Replace with a real FX API in production
rates = {"USD_EUR": 0.92, "EUR_USD": 1.09, "GBP_USD": 1.27}
key = f"{from_currency}_{to_currency}"
rate = rates.get(key, "unknown")
return f"1 {from_currency} = {rate} {to_currency}"
@tool
def get_country_info(country: str) -> str:
"""Get basic information about a country."""
info = {
"France": "Capital: Paris, Currency: EUR, Population: 68M",
"UK": "Capital: London, Currency: GBP, Population: 67M",
}
return info.get(country, f"No data for {country}")
class AgentState(TypedDict):
messages: Annotated[list[AnyMessage], add_messages]
tools = [get_exchange_rate, get_country_info]
model = ChatAnthropic(model="claude-opus-5-5").bind_tools(tools)
tool_node = ToolNode(tools, wrap_tool_call=observability_wrapper)
def call_model(state: AgentState) -> dict:
return {"messages": [model.invoke(state["messages"])]}
graph = StateGraph(AgentState)
graph.add_node("agent", call_model)
graph.add_node("tools", tool_node)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", tools_condition)
graph.add_edge("tools", "agent")
app = graph.compile()
result = app.invoke({"messages": [{"role": "user", "content": "USD to EUR rate?"}]})
# Second call uses cache
result2 = app.invoke({"messages": [{"role": "user", "content": "USD to EUR exchange rate again?"}]})
print(f"Audit log entries: {len(_call_log)}")

Recipe 18: Custom channels — BinaryOperatorAggregate, Topic, and EphemeralValue

Section titled “Recipe 18: Custom channels — BinaryOperatorAggregate, Topic, and EphemeralValue”

Custom channels give you precise control over how state fields merge when multiple nodes write to them in the same step.

import operator
from typing import Annotated, Sequence
from typing_extensions import TypedDict
from langgraph.channels.binop import BinaryOperatorAggregate
from langgraph.channels.topic import Topic
from langgraph.channels.ephemeral_value import EphemeralValue
from langgraph.graph import StateGraph, START, END
from langgraph.types import Send
# ── Reducer functions ─────────────────────────────────────────────────────────
def keep_max_confidence(a: float, b: float) -> float:
"""BinaryOperatorAggregate reducer: keep the highest confidence score."""
return max(a, b)
# ── State definition with three custom channel types ─────────────────────────
class EnsembleState(TypedDict):
document: str
# BinaryOperatorAggregate: each parallel classifier writes a score;
# only the maximum survives to the next node.
best_confidence: Annotated[float, keep_max_confidence]
# Topic (step-scoped): ALL classifier labels written this step are collected
# into a list; the list is cleared at the start of the next step.
this_step_labels: Annotated[Sequence[str], Topic(str)]
# EphemeralValue: carries intermediate tokens from tokenize → classify;
# visible only within the same step, never persisted in checkpoints.
token_count: Annotated[int, EphemeralValue(int)]
# Standard list accumulation using operator.add
all_labels: Annotated[list[str], operator.add]
# ── Nodes ────────────────────────────────────────────────────────────────────
def tokenize(state: EnsembleState) -> dict:
"""Count tokens — written to EphemeralValue, only visible this step."""
tokens = state["document"].split()
return {"token_count": len(tokens)}
def classifier_a(state: EnsembleState) -> dict:
"""Fast shallow classifier."""
tokens = state.get("token_count", 0)
confidence = min(0.5 + tokens * 0.01, 0.85)
return {
"best_confidence": confidence,
"this_step_labels": "invoice", # single value → Topic collects it
"all_labels": ["invoice"],
}
def classifier_b(state: EnsembleState) -> dict:
"""Slow deep classifier — usually more accurate."""
return {
"best_confidence": 0.93,
"this_step_labels": "financial_document",
"all_labels": ["financial_document"],
}
def classifier_c(state: EnsembleState) -> dict:
"""Rule-based classifier."""
text = state["document"].lower()
label = "invoice" if "invoice" in text or "amount due" in text else "unknown"
return {
"best_confidence": 0.70 if label != "unknown" else 0.30,
"this_step_labels": label,
"all_labels": [label],
}
def aggregate(state: EnsembleState) -> dict:
# this_step_labels contains ALL labels from the three classifiers this step
labels = list(state["this_step_labels"]) # e.g. ["invoice", "financial_document", "invoice"]
# best_confidence is the max across all three classifiers
print(f"Labels this step: {labels}")
print(f"Best confidence : {state['best_confidence']}")
print(f"token_count (ephemeral, should be 0 or missing here): {state.get('token_count')}")
return {}
def fan_out(state: EnsembleState):
"""Run all three classifiers in parallel via Send."""
return [
Send("classifier_a", state),
Send("classifier_b", state),
Send("classifier_c", state),
]
# ── Graph ─────────────────────────────────────────────────────────────────────
graph = StateGraph(EnsembleState)
graph.add_node("tokenize", tokenize)
graph.add_node("classifier_a", classifier_a)
graph.add_node("classifier_b", classifier_b)
graph.add_node("classifier_c", classifier_c)
graph.add_node("aggregate", aggregate)
graph.add_edge(START, "tokenize")
graph.add_conditional_edges("tokenize", fan_out, ["classifier_a", "classifier_b", "classifier_c"])
graph.add_edge("classifier_a", "aggregate")
graph.add_edge("classifier_b", "aggregate")
graph.add_edge("classifier_c", "aggregate")
graph.add_edge("aggregate", END)
app = graph.compile()
result = app.invoke({
"document": "Invoice #1234 — Amount due: $4,500",
"best_confidence": 0.0,
"this_step_labels": [],
"token_count": 0,
"all_labels": [],
})
print(f"All labels accumulated: {result['all_labels']}")

Recipe 19: Fan-in that waits for named validators

Section titled “Recipe 19: Fan-in that waits for named validators”

Three validators run in parallel and process must run only after all three have passed. The waiting is done by a barrier edge, add_edge(["schema_check", "auth_check", "quota_check"], "process"), which StateGraph implements with a NamedBarrierValue channel. The validation_barrier state key is optional extra checking: declared with NamedBarrierValue, it rejects any token not in REQUIRED_VALIDATORS. On its own, a state key does not decide when nodes run (Channels reference). A validator that raises fails the whole run, which is what a gateway wants here.

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.channels.named_barrier_value import NamedBarrierValue
from langgraph.graph import StateGraph, START, END
from langgraph.types import Send
REQUIRED_VALIDATORS = {"schema_check", "auth_check", "quota_check"}
class APIGatewayState(TypedDict):
request_body: dict
user_id: str
# Validates the tokens the validators write (an unknown token raises InvalidUpdateError)
validation_barrier: Annotated[str, NamedBarrierValue(str, REQUIRED_VALIDATORS)]
response_status: int
response_body: str
def check_schema(state: APIGatewayState) -> dict:
"""Validate request body schema."""
required_fields = {"action", "payload"}
missing = required_fields - set(state["request_body"].keys())
if missing:
raise ValueError(f"Missing fields: {missing}")
return {"validation_barrier": "schema_check"}
def check_auth(state: APIGatewayState) -> dict:
"""Validate that user_id is present and non-empty."""
if not state["user_id"]:
raise PermissionError("Missing user_id")
return {"validation_barrier": "auth_check"}
def check_quota(state: APIGatewayState) -> dict:
"""Check that the user has not exceeded their API quota."""
# In production, query a quota service here
allowed_users = {"alice", "bob", "charlie"}
if state["user_id"] not in allowed_users:
raise PermissionError(f"Quota exceeded for {state['user_id']}")
return {"validation_barrier": "quota_check"}
def process_request(state: APIGatewayState) -> dict:
"""Runs only after schema_check, auth_check, AND quota_check all completed."""
action = state["request_body"].get("action")
return {
"response_status": 200,
"response_body": f"Action '{action}' processed for user {state['user_id']}",
}
def dispatch_validators(state: APIGatewayState):
"""Fan out to all three validators in parallel."""
return [
Send("schema_check", state),
Send("auth_check", state),
Send("quota_check", state),
]
graph = StateGraph(APIGatewayState)
graph.add_node("schema_check", check_schema)
graph.add_node("auth_check", check_auth)
graph.add_node("quota_check", check_quota)
graph.add_node("process", process_request)
graph.add_conditional_edges(
START, dispatch_validators, ["schema_check", "auth_check", "quota_check"]
)
# Barrier edge: "process" runs once, after all three validators have finished,
# even if one of them later grows into several steps.
graph.add_edge(["schema_check", "auth_check", "quota_check"], "process")
graph.add_edge("process", END)
app = graph.compile()
result = app.invoke({
"request_body": {"action": "create_order", "payload": {"item": "widget"}},
"user_id": "alice",
"response_status": 0,
"response_body": "",
})
print(result["response_status"], result["response_body"])
# 200 Action 'create_order' processed for user alice

Recipe 20: Functional API — @entrypoint + @task Workflow

Section titled “Recipe 20: Functional API — @entrypoint + @task Workflow”

Use the Functional API when you want a plain-Python workflow with full LangGraph checkpoint/interrupt support, without declaring a StateGraph:

import asyncio
from typing import Optional
from langgraph.func import entrypoint, task
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver()
@task
async def web_search(query: str) -> list[str]:
"""Simulate searching the web — runs concurrently with other tasks."""
await asyncio.sleep(0.05)
return [f"Result 1 for {query}", f"Result 2 for {query}"]
@task
async def summarise(docs: list[str]) -> str:
"""Summarise retrieved documents."""
await asyncio.sleep(0.02)
return " | ".join(docs)
@entrypoint(checkpointer=checkpointer)
async def research_workflow(question: str, *, previous: Optional[dict] = None) -> dict:
"""
Full research workflow:
1. Fan out to web_search (returns SyncAsyncFuture)
2. Await future and summarise
3. Interrupt for human review
4. Return approved answer
"""
# Check cache from a prior run on the same thread
if previous and previous.get("question") == question:
return previous
# Parallel async fan-out
search_future = web_search(question)
docs = await search_future
summary_future = summarise(docs)
summary = await summary_future
# Pause for human review
approved = interrupt({
"summary": summary,
"prompt": "Is this summary accurate?",
})
result = {
"question": question,
"summary": summary,
"approved": approved,
}
return result
async def run():
config = {"configurable": {"thread_id": "research-1"}}
# First run — pauses at interrupt
async for event in research_workflow.astream("What is LangGraph?", config):
if "__interrupt__" in event:
print("Interrupted — awaiting approval")
print("Summary:", event["__interrupt__"][0].value["summary"])
# Resume with approval
async for event in research_workflow.astream(Command(resume=True), config):
if "research_workflow" in event:
print("Final:", event["research_workflow"])
asyncio.run(run())

Key points:

  • @task functions return a SyncAsyncFuture — call .result() (sync) or await it (async).
  • The entire workflow is checkpointed: replaying after an interrupt re-uses cached task results.
  • previous holds the saved return value from the previous invocation on the same thread_id.
  • entrypoint.final(value=..., save=...) lets you return one thing to the caller and persist something else to the checkpoint.

Recipe 21: Safe Parallel Map-Reduce with Send + Per-Instance Timeout

Section titled “Recipe 21: Safe Parallel Map-Reduce with Send + Per-Instance Timeout”

Send supports a timeout kwarg so you can give individual tasks different time budgets based on their priority or expected cost:

import asyncio
import operator
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Send, TimeoutPolicy
class PipelineState(TypedDict):
jobs: list[dict]
results: Annotated[list[str], operator.add]
failed: Annotated[list[str], operator.add]
class JobState(TypedDict):
job_id: str
priority: str
work_seconds: float
async def execute_job(state: JobState) -> dict:
await asyncio.sleep(state["work_seconds"])
return {"results": [f"done:{state['job_id']}"]}
def dispatch_jobs(state: PipelineState):
sends = []
for job in state["jobs"]:
# High-priority jobs get 30 s; low-priority get 5 s
if job["priority"] == "high":
timeout = TimeoutPolicy(run_timeout=30.0)
else:
timeout = TimeoutPolicy(run_timeout=5.0)
sends.append(Send("execute_job", job, timeout=timeout))
return sends
builder = StateGraph(PipelineState)
builder.add_node("execute_job", execute_job)
builder.add_conditional_edges(START, dispatch_jobs)
builder.add_edge("execute_job", END)
graph = builder.compile()
async def main():
result = await graph.ainvoke({
"jobs": [
{"job_id": "j1", "priority": "high", "work_seconds": 0.05},
{"job_id": "j2", "priority": "low", "work_seconds": 0.02},
{"job_id": "j3", "priority": "high", "work_seconds": 0.1},
],
"results": [],
"failed": [],
})
print(result["results"])
# ['done:j1', 'done:j2', 'done:j3']
asyncio.run(main())

Recipe 22: Command.PARENT — Subgraph Writing to Parent State

Section titled “Recipe 22: Command.PARENT — Subgraph Writing to Parent State”

When a subgraph needs to update the parent graph’s state (not its own), return Command(update=..., graph=Command.PARENT). Omit goto to let the parent’s defined edges handle routing — setting goto=END would terminate the parent immediately and bypass any downstream nodes. Adding goto="some_node" in a Command.PARENT schedules that node in the parent alongside any static edges already defined there:

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command
# --- Subgraph ---
class ReviewState(TypedDict):
draft: str
reviewer: str
def approve_draft(state: ReviewState) -> Command:
cleaned = state["draft"].strip().upper()
# Write "approved_content" directly into the PARENT graph's state.
# No `goto` here — the parent's "review" → "publish" edge takes over.
return Command(
update={"approved_content": cleaned, "reviewer": state["reviewer"]},
graph=Command.PARENT,
)
sub = StateGraph(ReviewState)
sub.add_node("approve", approve_draft)
sub.add_edge(START, "approve")
sub.add_edge("approve", END) # subgraph must have an explicit exit
subgraph = sub.compile()
# --- Parent graph ---
class WorkflowState(TypedDict):
draft: str
approved_content: str
reviewer: str
status: str
def prepare(state: WorkflowState) -> dict:
return {"draft": state["draft"].strip()}
def mark_done(state: WorkflowState) -> dict:
return {"status": "published"}
parent = StateGraph(WorkflowState)
parent.add_node("prepare", prepare)
# Pass the subgraph's *input* keys when invoking as a node
parent.add_node("review", subgraph)
parent.add_node("publish", mark_done)
parent.add_edge(START, "prepare")
parent.add_edge("prepare", "review")
parent.add_edge("review", "publish")
parent.add_edge("publish", END)
workflow = parent.compile()
result = workflow.invoke({
"draft": " hello world ",
"approved_content": "",
"reviewer": "alice",
"status": "draft",
})
print(result)
# {'draft': 'hello world', 'approved_content': 'HELLO WORLD',
# 'reviewer': 'alice', 'status': 'published'}

When to use Command.PARENT:

  • A subgraph computes something that belongs in the parent’s state schema.
  • You want to decouple the subgraph’s internal state from what it exposes upward.
  • Omit goto (or set goto to a specific parent node name) — goto=END terminates the parent immediately, skipping all downstream nodes.
  • Avoid it for deeply nested subgraphs — it only bubbles to the nearest parent; use regular state fields for deeper hierarchies.

Recipe 23: TracePolicy — Controlling a Node’s Trace Payload

Section titled “Recipe 23: TracePolicy — Controlling a Node’s Trace Payload”

Goal: Keep one node’s inputs and outputs out of its LangSmith span (here, a node that handles PII) while every other node is traced normally. For real secrets/PII redaction, see the note at the end of this recipe.

Uses: TracePolicy, omit_payload helper, add_node(trace_policy=...)

from dataclasses import dataclass
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import TracePolicy, omit_payload # omit_payload is in langgraph.types
# --- State ---
class State(TypedDict):
raw_pii: str # e.g., full name + SSN
anonymized: str
result: str
# --- Nodes ---
def anonymize(state: State) -> dict:
"""Replace PII with a placeholder and clear the raw field.
Clearing raw_pii ensures downstream nodes never receive it in state,
so their LangSmith spans won't record the sensitive value either.
"""
text = state["raw_pii"]
# Real implementation would use a NER model or regex; toy version here:
return {"anonymized": "[REDACTED]", "raw_pii": ""} # wipe raw field
def process(state: State) -> dict:
"""Safe to trace — state['raw_pii'] is empty by the time this runs."""
return {"result": f"Processed: {state['anonymized']}"}
# --- Graph ---
builder = StateGraph(State)
# anonymize node: strip both inputs and outputs from LangSmith traces.
# omit_payload is a processor fn that returns {}; pass it for both sides.
builder.add_node(
"anonymize",
anonymize,
trace_policy=TracePolicy(process_inputs=omit_payload, process_outputs=omit_payload),
)
builder.add_node("process", process) # traced normally
builder.add_edge(START, "anonymize")
builder.add_edge("anonymize", "process")
builder.add_edge("process", END)
graph = builder.compile()
result = graph.invoke({"raw_pii": "Alice Smith, SSN 123-45-6789", "anonymized": "", "result": ""})
print(result["result"]) # Processed: [REDACTED]

What omit_payload does: A processor function (from langgraph.types) that returns an empty dict {}, dropping the entire payload. Pass it as process_inputs and/or process_outputs on a TracePolicy to keep the node’s span (run ID, timing, parent/child links) while omitting its data from the trace.

Scope limitations to keep in mind:

  • TracePolicy only hides the annotated node’s own LangSmith span. Without also clearing raw_pii from state (as anonymize does above), every downstream node’s span would still record the raw value in its input state.
  • The root graph run still records the full invocation input (which contains raw_pii) in its LangSmith entry. For complete removal, strip sensitive data before it enters the graph, or use graph-level LangSmith project settings.

You can also supply custom processors instead of omit_payload. Build a fresh graph using the same node functions defined above, replacing omit_payload with your own callable:

from langgraph.types import TracePolicy
from langgraph.graph import StateGraph, START, END
# Match known PII field names (including raw_pii as used in this example).
_PII_KEYS = {"raw_pii", "ssn", "email", "phone", "credit_card"}
def scrub_pii(payload: dict) -> dict:
"""Return a safe version of the payload — called by LangGraph before the node's run is recorded."""
return {k: "[REDACTED]" if k.lower() in _PII_KEYS else v for k, v in payload.items()}
builder2 = StateGraph(State)
builder2.add_node(
"anonymize",
anonymize,
trace_policy=TracePolicy(process_inputs=scrub_pii, process_outputs=scrub_pii),
)
builder2.add_node("process", process)
builder2.add_edge(START, "anonymize")
builder2.add_edge("anonymize", "process")
builder2.add_edge("process", END)
graph2 = builder2.compile()
result2 = graph2.invoke({"raw_pii": "Bob Jones, SSN 987-65-4321", "anonymized": "", "result": ""})
print(result2["result"]) # Processed: [REDACTED]

When to use TracePolicy:

  • High-volume nodes where storing full payloads in LangSmith is expensive (e.g. long message histories).
  • Keeping a single node’s span readable by summarising or omitting bulky inputs/outputs.
  • As a defence-in-depth measure on nodes that touch PII — not as your redaction mechanism.

Not a secrets/PII redaction tool. Per the TracePolicy docstring in 1.2.11, it only transforms the annotated node’s own run and is “not intended to redact secrets”. To redact inputs/outputs across every run (root graph run and child runs included), configure the LangSmith client instead — Client(hide_inputs=..., hide_outputs=..., anonymizer=...) (or the LANGSMITH_HIDE_INPUTS / LANGSMITH_HIDE_OUTPUTS environment variables).


Recipe 24: ToolCallTransformer — Structured Per-Tool Streaming

Section titled “Recipe 24: ToolCallTransformer — Structured Per-Tool Streaming”

Goal: Stream a tool-calling agent and consume each tool’s output incrementally as it arrives, using the structured ToolCallStream API rather than parsing raw event dicts.

Uses: ToolCallTransformer, ToolCallStream, compile(transformers=[...]), stream_events(version="v3")

import asyncio
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition, ToolRuntime
from langgraph.prebuilt import ToolCallTransformer
from langgraph.checkpoint.memory import InMemorySaver
# --- Tools ---
@tool
def fetch_price(ticker: str, runtime: ToolRuntime) -> str:
"""Get the current price for a stock ticker."""
# emit_output_delta pushes incremental chunks onto the "tools" stream channel.
# Each call produces a "tool-output-delta" event that ToolCallStream exposes
# via its __iter__ / __aiter__ so callers can consume partial results in order.
runtime.emit_output_delta(f"Looking up ticker {ticker.upper()}…")
prices = {"AAPL": "182.50", "GOOG": "141.20", "MSFT": "378.90"}
price = prices.get(ticker.upper(), "Unknown ticker")
runtime.emit_output_delta(f"Found: ${price}")
return price
@tool
def summarize_news(ticker: str) -> str:
"""Get a one-line news summary for a ticker (no streaming deltas)."""
return f"No major news for {ticker} today."
# --- Graph ---
tools = [fetch_price, summarize_news]
llm = ChatOpenAI(model="gpt-6-luna").bind_tools(tools)
def call_model(state: MessagesState) -> dict:
return {"messages": [llm.invoke(state["messages"])]}
builder = StateGraph(MessagesState)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
# Register ToolCallTransformer — projects raw protocol events into ToolCallStream handles
graph = builder.compile(
checkpointer=InMemorySaver(),
transformers=[ToolCallTransformer],
)
cfg = {"configurable": {"thread_id": "stocks-1"}}
# --- Sync streaming via the v3 event protocol ---
print("=== Sync stream ===")
# run.tool_calls is a projection on the GraphRunStream returned by
# stream_events(version="v3"). Plain graph.stream(stream_mode="tools") is a
# generator of raw event dicts and cannot be used as a context manager.
with graph.stream_events(
{"messages": [("user", "What is the price and latest news for AAPL?")]},
cfg,
version="v3",
) as run:
for tc_stream in run.tool_calls:
print(f"→ Tool started: {tc_stream.tool_name} (input={tc_stream.input})")
for delta in tc_stream: # drain deltas; output is set once the tool finishes
print(f" delta: {delta!r}")
if tc_stream.error:
print(f" ERROR: {tc_stream.error}")
else:
# output is the ToolMessage produced by the tool call
print(f"[tool] {tc_stream.tool_name} => {tc_stream.output}")
# To also see state-update events, stream separately with "updates" mode:
for update in graph.stream(
{"messages": [("user", "What is the price and latest news for AAPL?")]},
{"configurable": {"thread_id": "stocks-1b"}},
stream_mode="updates",
):
node = list(update.keys())[0]
print(f"[update] node={node}")
# --- Async streaming ---
async def main():
print("\n=== Async stream ===")
# astream_events() is a coroutine — await it to get the AsyncGraphRunStream
run = await graph.astream_events(
{"messages": [("user", "Check MSFT price")]},
{"configurable": {"thread_id": "stocks-2"}},
version="v3",
)
async with run:
async for tc_stream in run.tool_calls:
print(f"→ {tc_stream.tool_name} started (input={tc_stream.input})")
async for delta in tc_stream:
# delta chunks arrive as the tool streams partial output
print(f" chunk: {delta!r}")
if tc_stream.error:
print(f" ERROR: {tc_stream.error}")
else:
print(f" Final output: {tc_stream.output}")
asyncio.run(main())

Key points:

  • run.tool_calls exists only on the GraphRunStream returned by stream_events(..., version="v3") (async: await graph.astream_events(..., version="v3")), and only when ToolCallTransformer is registered — via compile(transformers=[...]) or stream_events(..., transformers=[...]). The v3 protocol is still marked experimental in 1.2.22.
  • Plain graph.stream(..., stream_mode="tools") (alone or in a list such as ["updates", "tools"]) always yields raw event dicts ({"event": "tool-started" | "tool-output-delta" | "tool-finished" | "tool-error", ...}), whether or not a transformer is registered.
  • ToolCallStream __iter__ / __aiter__ (or .output_deltas) iterates delta chunks emitted by ToolRuntime.emit_output_delta(...) inside the tool.
  • ToolCallStream.output is the tool result as the ToolMessage content string (a tool returning 42 gives '42'); it and .completed are set once tool-finished or tool-error fires, so drain the deltas first.

Recipe 25: entrypoint.final — Decoupled Return and Checkpoint Value

Section titled “Recipe 25: entrypoint.final — Decoupled Return and Checkpoint Value”

Goal: Build a conversation workflow where the agent returns a rich result to the caller but feeds only a compact state forward to the next turn via previous.

Uses: entrypoint.final, @entrypoint(checkpointer=...), previous

from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from langgraph.func import entrypoint, task
from langgraph.checkpoint.memory import InMemorySaver
# --- What we persist (compact) ---
@dataclass
class ThreadState:
turn_count: int
last_query: str
last_answer: str
# --- What we return to the caller (richer) ---
@dataclass
class TurnResult:
answer: str
turn_count: int
context_used: list[str]
# --- Tasks ---
@task
def retrieve(query: str) -> list[str]:
"""Toy retrieval — returns relevant context snippets."""
corpus = {
"langgraph": ["LangGraph builds stateful graphs.", "It supports checkpointing."],
"python": ["Python is a high-level language.", "pip installs packages."],
}
for k, docs in corpus.items():
if k in query.lower():
return docs
return ["No specific context found."]
@task
def answer(query: str, context: list[str]) -> str:
"""Generate an answer using retrieved context (toy version)."""
ctx_str = " | ".join(context)
return f"Based on [{ctx_str}]: answer to '{query}'"
# --- Entrypoint ---
@entrypoint(checkpointer=InMemorySaver())
def qa_agent(
query: str,
*,
previous: ThreadState | None = None,
) -> entrypoint.final[TurnResult, ThreadState]:
prev = previous or ThreadState(turn_count=0, last_query="", last_answer="")
context = retrieve(query).result()
ans = answer(query, context).result()
turn_count = prev.turn_count + 1
# What the caller receives — rich object with context included
caller_result = TurnResult(
answer=ans,
turn_count=turn_count,
context_used=context,
)
# What the next call receives as `previous` — compact, no context snippets
saved_state = ThreadState(
turn_count=turn_count,
last_query=query,
last_answer=ans,
)
return entrypoint.final(value=caller_result, save=saved_state)
# --- Usage ---
cfg = {"configurable": {"thread_id": "qa-session-1"}}
r1: TurnResult = qa_agent.invoke("Tell me about LangGraph", cfg)
print(f"Turn {r1.turn_count}: {r1.answer}")
print(f"Context used: {r1.context_used}")
r2: TurnResult = qa_agent.invoke("What about Python?", cfg)
print(f"Turn {r2.turn_count}: {r2.answer}") # turn_count is 2 — loaded from checkpoint
# get_state().values returns the value= output (TurnResult), NOT the save= state (ThreadState).
# ThreadState is only accessible as the `previous` argument on the *next* call.
snap = qa_agent.get_state(cfg)
print(type(snap.values)) # TurnResult — the value= output from the last entrypoint.final

Why entrypoint.final?

  • value= controls what invoke/stream returns to the caller. It is also checkpointed — it is the entrypoint’s output (__end__ channel) and what get_state().values returns.
  • save= controls what is stored in the __previous__ channel and surfaced as previous on the next call.
  • The two can be completely different types. entrypoint.final does not shrink the checkpoint — both values are persisted — so keep large or sensitive data out of value= if checkpoint size matters.
  • Both values go through the checkpointer’s serialiser. Custom classes defined in __main__ (like the dataclasses above) currently log a “Deserializing unregistered type” warning on reload, which a future release will turn into an error. Use plain dicts / TypedDicts, define the classes in an importable module, or allow them explicitly via the serialiser’s allowed_msgpack_modules.

Recipe 26: GraphOutput and Durability — v2 Invoke API

Section titled “Recipe 26: GraphOutput and Durability — v2 Invoke API”

Goal: Use the v2 invoke API to get a typed GraphOutput wrapper that includes both the final state and any interrupts that occurred, while controlling when checkpoints are persisted with Durability modes.

Uses: GraphOutput, Durability, version="v2", interrupt()

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, GraphOutput
from langgraph.checkpoint.memory import InMemorySaver
# --- State ---
class ApprovalState(TypedDict):
document: str
approved: bool
approver: str
# --- Nodes ---
def draft(state: ApprovalState) -> dict:
return {"document": f"Draft: {state['document']}"}
def review(state: ApprovalState) -> dict:
approval = interrupt({
"message": "Please approve or reject this document.",
"document": state["document"],
})
return {"approved": approval["decision"] == "approve", "approver": approval.get("by", "unknown")}
def publish(state: ApprovalState) -> dict:
if state["approved"]:
print(f"Published by {state['approver']}: {state['document']}")
return {}
# --- Graph ---
builder = StateGraph(ApprovalState)
builder.add_node("draft", draft)
builder.add_node("review", review)
builder.add_node("publish", publish)
builder.add_edge(START, "draft")
builder.add_edge("draft", "review")
builder.add_edge("review", "publish")
builder.add_edge("publish", END)
graph = builder.compile(checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "approval-1"}}
# --- v2 invoke: returns GraphOutput ---
# durability="exit": only checkpoint once the graph exits (cheapest — no mid-run persistence)
output: GraphOutput = graph.invoke(
{"document": "Quarterly report", "approved": False, "approver": ""},
cfg,
version="v2",
durability="exit",
)
print(type(output)) # <class 'langgraph.types.GraphOutput'>
print(output.value) # ApprovalState dict (final state up to the interrupt)
print(len(output.interrupts)) # 1 — contains the Interrupt raised by review()
print(output.interrupts[0].value) # {'message': '...', 'document': '...'}
# --- Resume with a Command ---
from langgraph.types import Command
resumed: GraphOutput = graph.invoke(
Command(resume={"decision": "approve", "by": "alice"}),
cfg,
version="v2",
durability="sync", # strongest guarantee: checkpoint before every step
)
print(resumed.value["approved"]) # True
print(resumed.value["approver"]) # alice
print(len(resumed.interrupts)) # 0 — no pending interrupts

Durability modes:

ModeWhen checkpointedCostUse case
"sync"Before each step beginsHighestCritical workflows where every step must survive a crash
"async"Concurrently as the next step runsMediumDefault — good balance of speed and safety
"exit"Only when the graph exitsLowestShort-lived, low-stakes runs; CI test graphs

GraphOutput fields:

FieldTypeDescription
valueOutputTThe final state (or output schema value) after the run.
interruptstuple[Interrupt, ...]All interrupt() calls that fired during the run. Empty when no interrupts occurred.

Use version="v2" to opt into the typed GraphOutput wrapper. The v1 API (default) returns the raw state dict.