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–6import jsonimport operatorfrom typing import Annotated
from typing_extensions import TypedDictfrom langchain.chat_models import init_chat_modelfrom langgraph.checkpoint.memory import InMemorySaverfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messages
model = init_chat_model("anthropic:claude-sonnet-5-5")Recipe 1: RAG System with Quality Control
Section titled “Recipe 1: RAG System with Quality Control”Retrieval-Augmented Generation with automatic re-retrieval and refinement:
from langgraph.graph import StateGraph, START, ENDfrom langgraph.types import Sendfrom typing_extensions import TypedDictfrom typing import Annotatedfrom langgraph.graph.message import add_messagesimport 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 graphrag_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())
# Usageresult = 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 graphsupport_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())
# Usageresult = 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 osfrom pydantic import BaseModelfrom 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_sourcereceives only itsSearchTaskpayload, not the whole state. That keeps the parallel tasks independent; everything they need is in theSend.- A failing search fails the run, because an
error_handlerdoes not catch failures in parallel tasks. Wrap the call intry/exceptinsidesearch_sourceand return an error entry if partial results are acceptable. - To cap concurrent API calls, pass
{"max_concurrency": 3}in the config.
Recipe 4: Agentic Loop with Tool Calling
Section titled “Recipe 4: Agentic Loop with Tool Calling”Autonomous agent that reasons and acts:
import uuidfrom langgraph.prebuilt import ToolNode, tools_conditionfrom langchain_core.tools import tool
# Define specialized tools@tooldef 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."
@tooldef check_inventory(product_id: str) -> dict: """Check product inventory.""" return { "product_id": product_id, "in_stock": True, "quantity": 50 }
@tooldef 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 }
@tooldef 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 themmodel_with_tools = model.bind_tools(tools)
# Build custom agent for more controlclass 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 graphagent_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 routingagent_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())
# Usageconfig = {"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)Recipe 5: Document Processing Pipeline
Section titled “Recipe 5: Document Processing Pipeline”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 pipelinedoc_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()
# Usageresult = 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 asyncioimport uuidfrom datetime import datetime, timezone
from langgraph.runtime import Runtimefrom 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.22import operatorfrom typing import Annotatedfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import Send, RetryPolicy, CachePolicyfrom langgraph.store.memory import InMemoryStorefrom langgraph.cache.memory import InMemoryCachefrom langgraph.checkpoint.memory import InMemorySaverfrom 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-outbuilder.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 cacheRecipe 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 Anyfrom typing_extensions import NotRequired
from langchain.agents import create_agent, AgentStatefrom langchain.agents.middleware import after_model, dynamic_prompt, ModelRequestfrom langchain.messages import ToolMessagefrom langchain.tools import tool, ToolRuntimefrom langgraph.checkpoint.memory import InMemorySaverfrom langgraph.runtime import Runtimefrom langgraph.types import Command
class ShoppingState(AgentState): user_id: NotRequired[str] cart: NotRequired[list[dict]] total: NotRequired[float] tokens_used: NotRequired[int]
@tooldef 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)], })
@tooldef 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}"
@tooldef 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_promptdef 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 hasmessages. (The oldercreate_react_agentneeded aremaining_stepskey in a custom schema;create_agentdoes not.) - A tool that returns a
Commandmust include aToolMessagefor its own call inupdate["messages"]; otherwise the model sees a tool call with no result. @dynamic_promptrebuilds 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.22import operatorfrom typing import Annotated, Literalfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import Command, Send, RetryPolicyfrom 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 failedRecipe 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 InMemoryStorefrom langgraph.graph.message import MessagesState, add_messagesfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.runtime import Runtimefrom langchain_core.messages import HumanMessage, AIMessage, SystemMessagefrom typing import Annotatedfrom typing_extensions import TypedDictfrom 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@dataclassclass 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:
InMemoryStoreaccepts anindexdict to enable semantic (vector) search viastore.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=UserContextonStateGraphdeclares the type ofruntime.context; pass the value withinvoke(..., 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 operatorfrom typing import Annotatedfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import Sendfrom langgraph.prebuilt.tool_node import ToolRuntimefrom langgraph.store.base import BaseStorefrom 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 ───────────────────────────
@tooldef 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 parallelbuilder.add_conditional_edges(START, fan_out, ["analyze_doc"])
# All analyze_doc branches converge herebuilder.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.ToolRuntimeis injected byToolNodewhen a@tooldeclares 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, Annotatedfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, END, MessagesStatefrom langgraph.prebuilt import ToolNode, InjectedState, InjectedStore, tools_conditionfrom langgraph.store.memory import InMemoryStorefrom langchain_core.tools import toolfrom langchain_anthropic import ChatAnthropic
# Extend MessagesState with domain-specific fieldsclass ShopState(MessagesState): user_id: str cart: list[dict] # [{"id": str, "name": str, "price": float}] user_tier: str # "standard" | "premium"
# ── Tools ────────────────────────────────────────────────────────────────────
@tooldef 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)." )
@tooldef 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)
@tooldef 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}"
@tooldef 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 operatorfrom typing import Annotated, Literalfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import Overwritefrom 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 eventsdef process_batch(state: PipelineState) -> dict: batch = state["batch_id"] return { "events": [f"processed:{batch}"], "phase": "processed", }
# Appends error detaildef 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-processingdef 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 logiccfg = {"configurable": {"thread_id": "batch-007"}} # required with a checkpointerresult = 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_stateKey rule for Overwrite
Section titled “Key rule for Overwrite”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 InMemorySaverfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import StateUpdatefrom 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 historyfor _ 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 Literalfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.checkpoint.memory import InMemorySaverfrom 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 practicebuilder.add_edge("execute", END)
# Interrupt AFTER generate so the human sees the draft before execute runsgraph = 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_statestate = 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 runsfinal = 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 datetimefrom typing import Annotatedfrom typing_extensions import TypedDictfrom langchain_core.messages import AnyMessagefrom langchain_core.tools import toolfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messagesfrom langgraph.prebuilt import ToolNode, tools_conditionfrom langgraph.prebuilt.tool_node import ToolRuntimefrom langgraph.store.memory import InMemoryStorefrom langgraph.checkpoint.memory import InMemorySaverfrom langchain_anthropic import ChatAnthropic
class WorkflowState(TypedDict): messages: Annotated[list[AnyMessage], add_messages] user_id: str session_start: str
@tooldef 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]})"
@tooldef 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 hashlibimport jsonimport timefrom collections import defaultdictfrom typing import Annotatedfrom typing_extensions import TypedDictfrom langchain_core.messages import AnyMessage, ToolMessagefrom langchain_core.tools import toolfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messagesfrom langgraph.prebuilt import ToolNode, tools_conditionfrom langgraph.prebuilt.tool_node import ToolCallRequestfrom 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 = 10CACHE_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 ────────────────────────────────────────────────────────────────────
@tooldef 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}"
@tooldef 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 cacheresult2 = 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 operatorfrom typing import Annotated, Sequencefrom typing_extensions import TypedDictfrom langgraph.channels.binop import BinaryOperatorAggregatefrom langgraph.channels.topic import Topicfrom langgraph.channels.ephemeral_value import EphemeralValuefrom langgraph.graph import StateGraph, START, ENDfrom 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 Annotatedfrom typing_extensions import TypedDictfrom langgraph.channels.named_barrier_value import NamedBarrierValuefrom langgraph.graph import StateGraph, START, ENDfrom 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 aliceRecipe 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 asynciofrom typing import Optionalfrom langgraph.func import entrypoint, taskfrom langgraph.types import interrupt, Commandfrom langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver()
@taskasync 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}"]
@taskasync 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:
@taskfunctions return aSyncAsyncFuture— call.result()(sync) orawaitit (async).- The entire workflow is checkpointed: replaying after an interrupt re-uses cached task results.
previousholds the saved return value from the previous invocation on the samethread_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 asyncioimport operatorfrom typing import Annotated, TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom 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 TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom 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 exitsubgraph = 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 nodeparent.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 setgototo a specific parent node name) —goto=ENDterminates 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 dataclassfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom 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 normallybuilder.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:
TracePolicyonly hides the annotated node’s own LangSmith span. Without also clearingraw_piifrom state (asanonymizedoes 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 TracePolicyfrom 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
TracePolicydocstring 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 theLANGSMITH_HIDE_INPUTS/LANGSMITH_HIDE_OUTPUTSenvironment 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 asynciofrom langchain_core.tools import toolfrom langchain_openai import ChatOpenAIfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import MessagesStatefrom langgraph.prebuilt import ToolNode, tools_condition, ToolRuntimefrom langgraph.prebuilt import ToolCallTransformerfrom langgraph.checkpoint.memory import InMemorySaver
# --- Tools ---
@tooldef 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
@tooldef 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 handlesgraph = 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_callsexists only on theGraphRunStreamreturned bystream_events(..., version="v3")(async:await graph.astream_events(..., version="v3")), and only whenToolCallTransformeris registered — viacompile(transformers=[...])orstream_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 byToolRuntime.emit_output_delta(...)inside the tool.ToolCallStream.outputis the tool result as theToolMessagecontent string (a tool returning42gives'42'); it and.completedare set oncetool-finishedortool-errorfires, 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 annotationsfrom dataclasses import dataclassfrom typing import Anyfrom langgraph.func import entrypoint, taskfrom langgraph.checkpoint.memory import InMemorySaver
# --- What we persist (compact) ---
@dataclassclass ThreadState: turn_count: int last_query: str last_answer: str
# --- What we return to the caller (richer) ---
@dataclassclass TurnResult: answer: str turn_count: int context_used: list[str]
# --- Tasks ---
@taskdef 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."]
@taskdef 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.finalWhy entrypoint.final?
value=controls whatinvoke/streamreturns to the caller. It is also checkpointed — it is the entrypoint’s output (__end__channel) and whatget_state().valuesreturns.save=controls what is stored in the__previous__channel and surfaced aspreviouson the next call.- The two can be completely different types.
entrypoint.finaldoes not shrink the checkpoint — both values are persisted — so keep large or sensitive data out ofvalue=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’sallowed_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 TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.types import interrupt, GraphOutputfrom 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"]) # Trueprint(resumed.value["approver"]) # aliceprint(len(resumed.interrupts)) # 0 — no pending interruptsDurability modes:
| Mode | When checkpointed | Cost | Use case |
|---|---|---|---|
"sync" | Before each step begins | Highest | Critical workflows where every step must survive a crash |
"async" | Concurrently as the next step runs | Medium | Default — good balance of speed and safety |
"exit" | Only when the graph exits | Lowest | Short-lived, low-stakes runs; CI test graphs |
GraphOutput fields:
| Field | Type | Description |
|---|---|---|
value | OutputT | The final state (or output schema value) after the run. |
interrupts | tuple[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.