LangChain — Components Deep Dive

A study guide to building agents with LangChain 1.x (Python), one component at a time: what it is, the code you will actually type, when to use it (and when not to), the traps, and where the official docs live. How to read this guide. Every component has (1) a mental model, usually an everyday analogy, (2) the code you will write, (3) a when to use / when not to verdict, (4) the traps, and (5) 📖 links to the official docs. The decision tables for “when do I use tools?” (§3) and “when do I use memory?” (§6) are the parts to re-read before a design review. The companion page is LangGraph — Components Deep Dive . Version note: written 17 Oct 2026 from docs.langchain.com. Features marked ⚑ need a minimum version (table in §14), and model names move fast, so run pip show langchain langgraph and pick current model IDs from your provider before copying anything. 0. The map: what LangChain is in 2026 Analogy: a car. LangChain is the cockpit: steering wheel, pedals and dashboard that feel the same in every car (any model provider). LangGraph is the engine and chassis: it keeps the car running, lets you stop and restart a long trip, and gives you low-level control. Deep Agents is a fully equipped rental: GPS, spare tyre and a trunk (planning, subagents, filesystem) already installed. Runtime Framework Harness Example LangGraph (also Temporal, Inngest) LangChain (also Vercel AI SDK, CrewAI, OpenAI Agents SDK, Google ADK, LlamaIndex) Deep Agents SDK (also Claude Agent SDK) Value add Durable execution, streaming, human-in-the-loop, persistence Abstractions and integrations Predefined tools, prompts, subagents, planning, filesystem Use when Low-level control, long-running stateful workflows, mixing deterministic and agentic steps Getting started quickly, standardising how a team builds agents Autonomous agents on complex, non-deterministic, multi-step tasks Packages. langchain (agents, messages, tools, embeddings), langchain-core (base abstractions), one package per provider (install by extra: pip install 'langchain[anthropic]' ), langgraph (runtime, checkpointers, stores), and langchain-classic (legacy chains, retrievers, hub and community re-exports, moved out of the main namespace in v1). What changed in v1 (the things old tutorials get wrong): create_agent is the way to build an agent. The old prompt parameter is now system_prompt ; dynamic prompts go through middleware. Middleware is the defining feature: hooks around the model call and tool call replace most custom graph surgery. Messages expose standard content blocks ( content_blocks ) that look the same across providers. The langchain namespace is deliberately small. If from langchain.chains import ... or from langchain import hub fails, you want pip install langchain-classic . Agent state schemas must be TypedDict (no Pydantic state in create_agent ). Choosing the layer (quick verdict): single model call such as classify, extract or summarise → a bare model (§1). Model plus tools in a loop → create_agent . Need branching, parallel fan-out, custom loops or durable multi-step flows → LangGraph (companion page), and you can still embed a create_agent agent as a node. Long autonomous work with files and subagents → Deep Agents. 📖 Runtimes, frameworks, harnesses · What's new in v1 · Migration guide · Philosophy 1. Models Analogy: an engine you can swap. The model is the reasoning engine. LangChain gives every engine the same plug (invoke, stream, batch, bind_tools, structured output), so you can change provider without rewriting the car. 1.1 Initialise and call from langchain.chat_models import init_chat_model

model = init_chat_model('anthropic:claude-sonnet-5', temperature=0.2, timeout=30, max_tokens=1000, max_retries=6)

model.invoke('Why do parrots talk?') # one AIMessage
for chunk in model.stream('Tell me a story'): # AIMessageChunk objects, sum them to get the full message
 print(chunk.text, end='', flush=True)
model.batch(['q1', 'q2', 'q3'], config={'max_concurrency': 5}) # client-side parallelism Two ways in: init_chat_model('provider:model') , or the provider class ( ChatAnthropic , ChatOpenAI ...). Model names are passed straight to the provider API, so a new model works without a LangChain update. Resilience is built in: max_retries defaults to 6 with exponential backoff and jitter for network errors, 429 and 5xx. 401 and 404 are not retried. For long agent runs on shaky networks raise it to 10-15 and add a checkpointer. batch() is not the provider's batch API. It parallelises calls client-side; provider batch endpoints are a separate product. Configurable models: init_chat_model(temperature=0) with no model name lets you pick the model per call via config={'configurable': {'model': '...'}} . Use config_prefix when a chain has several models. 1.2 Tool calling and structured output on a bare model model_with_tools = model.bind_tools([get_weather]) # tool_choice='any' forces a call
ai = model_with_tools.invoke('Weather in Boston and Tokyo?') # ai.tool_calls may hold several parallel calls

from pydantic import BaseModel, Field
class Movie(BaseModel):
 title: str = Field(description='Title')
 year: int
model.with_structured_output(Movie).invoke('Details on Inception') # Movie(...) With a bare model you run the tool and send a ToolMessage back. An agent (§4) does that loop for you. with_structured_output accepts Pydantic, TypedDict or JSON Schema; method is json_schema (provider-native), function_calling (forces a tool call) or json_mode (valid JSON, schema only in the prompt). include_raw=True returns the raw message too, which is how you get token counts. 1.3 Other model features worth knowing Feature What to know Reasoning Read content_blocks of type reasoning . ⚑ A standard reasoning_effort parameter exists for several providers; check model.profile['reasoning_effort_levels'] . Model profile ⚑ model.profile lists capabilities ( max_input_tokens , tool_calling , structured_output , modalities). Summarisation middleware and structured-output auto-selection read it. It is beta and can be overridden with profile= . Multimodal Pass {'type': 'image', 'url': ...} or base64 plus mime_type as content blocks; not every model supports every type. Prompt caching Three levels: implicit (OpenAI, Gemini), explicit provider controls ( cache_control blocks for Anthropic, cachePoint for Bedrock), and middleware that caches stable system prompt and tool content. Usually only engages above a minimum token count. Server-side tools Web search and code interpreters run at the provider. The response carries server_tool_call and server_tool_result blocks in one turn, with no ToolMessage for you to return. Rate limiting rate_limiter=InMemoryRateLimiter(requests_per_second=...) limits request count only, not request size. Exceptions Standard types ( ModelRateLimitError , ModelTimeoutError , ContextOverflowError ...) each carry is_retryable , which retry middleware respects. Token usage msg.usage_metadata , or aggregate across models with get_usage_metadata_callback() . When to use a bare model: one-shot generation, classification, extraction, routing decisions inside your own code, or evaluator calls. When not to: as soon as the model must choose tools and loop, use an agent. Traps. (1) model.invoke returning a string means you built a legacy text-completion LLM, not a chat model. (2) A pre-bound model ( bind_tools already called) cannot be used where create_agent needs structured output. (3) parallel_tool_calls=False exists on some providers if your tools are not safe to run concurrently. 📖 Models · Providers and models · Chat model integrations 2. Messages Analogy: a transcript with stage directions. Each line has a speaker (role), the words (content) and margin notes (metadata such as IDs and token counts). The whole conversation is just a list of these lines. Type Role Notes SystemMessage Instructions that prime behaviour Always a SystemMessage inside ModelRequest.system_message , even when you passed a string. HumanMessage User input, text or multimodal A plain string is shorthand for one HumanMessage. AIMessage Model output .text , .content , .content_blocks , .tool_calls , .usage_metadata , .response_metadata , .id . ToolMessage Result of one tool call tool_call_id must match the AIMessage's call ID. artifact carries data for your app that is not sent to the model. Standard content blocks ( msg.content_blocks ): text (with annotations/citations), reasoning , image , audio , video , file , text-plain , tool_call , tool_call_chunk , invalid_tool_call , server_tool_call , server_tool_result and the escape hatch non_standard . content stays loosely typed (string, provider-native blocks or standard blocks); content_blocks lazily parses it into the standard form. Set output_version='v1' (or LC_OUTPUT_VERSION=v1 ) if another system must read the standard blocks from stored content. Rules that bite. Every tool call in history needs a matching ToolMessage, and most providers want history to start with a user message. Streaming chunks ( AIMessageChunk ) add up with + . Serialisation uses dumpd and load , but never call load() on untrusted data : it instantiates Python objects and can trigger side effects. 📖 Messages 3. Tools Analogy: hands for a brain. The model can only think and talk. A tool lets it reach out: read a database, call an API, write a file. The model decides whether and with what arguments to reach; your code does the reaching. 3.1 Define a tool from langchain.tools import tool

@tool
def search_orders(user_id: str, status: str, limit: int = 10) -> str:
 '''Search a user's orders by status. Use when the user asks about order history.

 Args:
 user_id: Unique user ID
 status: pending, shipped or delivered
 limit: Max results
 '''
 ... Type hints are required (they become the input schema). The docstring is the description the model reads, so write it as a prompt: when to use it, what the arguments mean. Prefer snake_case names; spaces and special characters get rejected by some providers. Override with @tool('web_search') or description=... . Richer inputs: @tool(args_schema=PydanticModel) or a JSON schema. Reserved argument names: config and runtime . Do not use them for your own parameters. 3.2 ToolRuntime: state, context, store, streaming Add runtime: ToolRuntime to the signature. It is injected at call time and hidden from the model's schema . Field What it is Use for runtime.state Short-term memory for this thread (messages, custom fields) Read history, counters, auth flags runtime.context Immutable per-run config passed at invoke time User ID, tenant, API keys, permissions runtime.store Long-term memory, persists across threads Preferences, learned facts runtime.stream_writer Emit custom progress events 'Fetched 10/100 records' runtime.tool_call_id ID of this call Building a matching ToolMessage runtime.execution_info ⚑ thread_id, run_id, attempt number Logging, retry-aware behaviour runtime.server_info ⚑ Assistant/graph ID, authenticated user on LangGraph Server (else None) Per-user scoping on the platform from langchain.tools import tool, ToolRuntime
from langchain.messages import ToolMessage
from langgraph.types import Command

@tool
def set_user_name(new_name: str, runtime: ToolRuntime) -> Command:
 '''Save the user's name.'''
 return Command(update={
 'user_name': new_name,
 'messages': [ToolMessage(content='Name saved.', tool_call_id=runtime.tool_call_id)],
 }) 3.3 What a tool may return Return Effect Pick it when str Becomes a ToolMessage the model reads Result is naturally text dict /object Serialised and returned; the model reads fields Downstream reasoning needs explicit fields Content-block list Multimodal ToolMessage (text plus image...) Screenshots, charts; model must support the modality Command(update=..., goto=...) Writes to state and can route The tool must change state. Include a ToolMessage with the matching tool_call_id or ToolNode raises ValueError . @tool(return_direct=True) Skips the final model call and returns the tool output Output is already the complete answer Parallel gotchas. Models may call several tools in one step. If two tools write the same state key, define a reducer for it. return_direct only short-circuits the loop when every tool call in that step has it set; a mixed batch goes back to the model. 3.4 Errors, dynamic tools, headless tools, MCP Errors: use ToolErrorMiddleware ⚑ or a @wrap_tool_call that catches the exception and returns a ToolMessage so the model can self-correct. Return the exception type rather than the raw message when details could be sensitive. Put retry inner (later in the list) so exceptions reach the error handler after retries are exhausted. Dynamic tool selection: if all tools are known up front, register them all and filter per call with @wrap_model_call and request.override(tools=...) (by auth state, role, feature flag). If tools are discovered at runtime (MCP, registry), you need two hooks: wrap_model_call to add them and wrap_tool_call to execute them, otherwise the agent cannot run the tool it just advertised. Headless tools: schema-only tools whose implementation lives in the client (browser geolocation, clipboard). The run interrupts with a tool payload and resumes when the client returns a result. MCP ⚑ (beta): from langchain.mcp import MCPAdapter ; async with MCPAdapter(url) as a: tools = await a.list_tools() , then pass to create_agent . Requires langchain[mcp]>=1.4.0 ; the standalone langchain-mcp-adapters package has a migration guide. 3.5 WHEN to use tools (decision table) Situation Use Why Needs fresh or private data (DB, API, files, web) Tool The model cannot know it Needs exact arithmetic, code execution, or a guaranteed-correct lookup Tool Models are unreliable calculators Has a side effect (send, write, delete, pay) Tool plus human approval (§9) Gate the dangerous ones Step is always executed, in a fixed order, with no judgement needed Plain code or a graph node , not a tool Do not pay tokens and latency to have a model 'decide' the obvious You only need the final answer in a fixed shape Structured output (§8) Cheaper and safer than a tool that just returns data Static knowledge that fits in the prompt Prompt or skill No call needed Big knowledge base Retrieval tool (§12) Fetch only relevant chunks More than roughly 10 tools and the model picks wrong Filter dynamically, LLMToolSelector, skills or subagents Too many tools overload context and raise errors Tool output is huge Context editing or filesystem middleware Stops results filling the window Traps. Vague docstrings cause wrong calls. A tool that returns a 50k-token blob poisons every later turn. A tool that mutates state without returning a ToolMessage breaks message history. Tools run again if a node is retried or resumed, so make side effects idempotent . 📖 Tools · MCP · Headless tools · Prebuilt tools 4. Agents (create_agent) Analogy: a new hire with a toolbox and a handbook. Agent = model + harness. The model does the thinking; the harness (prompt, tools, middleware) decides what it sees and may do. The loop is: think, pick a tool, see the result, think again, until it answers. from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from langchain_core.utils.uuid import uuid7

agent = create_agent(
 model='anthropic:claude-sonnet-5',
 tools=[search_orders],
 system_prompt='You are a concise support agent.',
 checkpointer=InMemorySaver(), # dev only
 name='support_agent',
)
cfg = {'configurable': {'thread_id': str(uuid7())}}
r1 = agent.invoke({'messages': [{'role': 'user', 'content': 'Where is order 42?'}]}, config=cfg)
r2 = agent.invoke({'messages': [{'role': 'user', 'content': 'And the one before?'}]}, config=cfg) # same thread, remembers Parameter Purpose model 'provider:model' string or model instance (not pre-bound if you use structured output) tools Callables, @tool objects or provider tool dicts system_prompt String or SystemMessage (use a SystemMessage for cache control) middleware The customisation primitive (§5) response_format Schema for the final structured answer (§8) state_schema Extra state fields (TypedDict only). Prefer defining them on the middleware that uses them context_schema Shape of per-run immutable context ( runtime.context ) checkpointer Thread persistence (short-term memory, HITL, time travel) store Cross-thread long-term memory name Identifier; vital when the agent is a subgraph, and surfaces as lc_agent_name in stream metadata thread_id versus context. thread_id scopes the conversation (history and checkpoints). context= carries per-run data (user ID, keys). In production pass both on every call. Result shape. result['messages'] is the full history; result['structured_response'] exists when response_format is set. With version='v2' , invoke returns an object with .value and .interrupts (⚑ LangGraph 1.1+). Limits. recursion_limit is a top-level key of config (not inside configurable ); LangGraph 1.0.6+ defaults it to 1000 steps and raises GraphRecursionError beyond it. Add ModelCallLimitMiddleware so a looping agent cannot burn money. When create_agent is enough: a model with tools, memory, guardrails and approvals. When to drop to LangGraph: explicit branching and fan-out you must control, deterministic steps interleaved with agentic ones, or custom loops. 📖 Agents · Quickstart · Runtime 5. Middleware Analogy: airport security checkpoints along the agent's route. Before boarding (before_agent), before each flight (before_model), wrapped around the flight itself (wrap_model_call), after landing (after_model), around each baggage handoff (wrap_tool_call), and at the exit (after_agent). Each checkpoint can inspect, change or turn the passenger around. Style Hook Runs Node before_agent / after_agent Once per invocation Node before_model / after_model Around each model response Wrap wrap_model_call Around each model call (you choose how often to call handler : 0 = short-circuit, 1 = normal, N = retry) Wrap wrap_tool_call Around each tool call Convenience @dynamic_prompt Build the system prompt per call Order. before_* run first to last; after_* run last to first; wrap_* nest like function calls (first middleware is outermost). Put critical guards first. from langchain.agents.middleware import before_model, wrap_model_call, dynamic_prompt, AgentState, ModelRequest, ModelResponse
from langgraph.runtime import Runtime
from langchain.messages import AIMessage

@before_model(can_jump_to=['end'])
def stop_long_chats(state: AgentState, runtime: Runtime):
 if len(state['messages']) >= 50:
 return {'messages': [AIMessage('Conversation limit reached.')], 'jump_to': 'end'}

@dynamic_prompt
def role_prompt(request: ModelRequest) -> str:
 return f'You are a helpful assistant for a {request.runtime.context.user_role}.'

@wrap_model_call
def route_model(request: ModelRequest, handler) -> ModelResponse:
 model = big_model if len(request.messages) > 10 else small_model
 return handler(request.override(model=model)) Jumps: return {'jump_to': 'end' | 'tools' | 'model'} , and declare the target with can_jump_to or @hook_config . State updates: node hooks return a dict applied through the graph's reducers. Wrap hooks return ExtendedModelResponse(model_response=..., command=Command(update=...)) for model calls, or a Command for tool calls. With several layers, commands compose: messages are additive, and for non-reducer keys the outermost value wins. If an outer layer retries, commands from earlier attempts are dropped. Middleware-scoped state: subclass AgentMiddleware , set state_schema = MyState (extra fields live and die with that middleware), and optionally ship tools (for example write_todos ) and stream transformers ⚑. Class versus decorator: decorators for one hook; classes for several hooks, configuration, or when you need both sync and async ( abefore_model ...). Middleware is not a separate runtime. The hooks run inside the compiled LangGraph, so you can embed the whole agent as a node in a larger StateGraph and its HITL, summarisation and retries come with it. 5.1 Built-in middleware catalogue Middleware Use it for Key options ToolErrorMiddleware ⚑ Turn tool exceptions into error ToolMessages the model can recover from on_error (return None to propagate), tools ToolRetryMiddleware Retry flaky tools with backoff max_retries=2 , backoff_factor=2.0 , retry_on , on_failure='continue'|'error' ModelRetryMiddleware Retry model calls Same options; ⚑ default respects is_retryable ModelFallbackMiddleware Fail over to other models/providers Ordered list of fallback models SummarizationMiddleware Compress old history persistently trigger (tokens/messages/fraction, AND within a dict, OR across a list), keep ContextEditingMiddleware Clear old tool outputs when context grows ClearToolUsesEdit(trigger, keep=3, exclude_tools) HumanInTheLoopMiddleware Approve, edit, reject tool calls interrupt_on , interrupt_mode , when ⚑ ModelCallLimitMiddleware Cap model calls (cost, loops) thread_limit (needs checkpointer), run_limit , exit_behavior ToolCallLimitMiddleware Cap total or per-tool calls tool_name , thread_limit , run_limit , exit_behavior PIIMiddleware Detect/handle PII strategy block|redact|mask|hash , custom detector , apply_to_input/output/tool_results TodoListMiddleware Planning via a write_todos tool Custom prompt/description LLMToolSelectorMiddleware Pre-select relevant tools when you have 10+ model , max_tools , always_include ProviderToolSearchMiddleware Defer tools behind provider-side tool search searchable_tools ; Anthropic and recent OpenAI models only ShellToolMiddleware Persistent shell session Execution policy: host, Docker or sandbox. Not compatible with interrupts yet FilesystemFileSearchMiddleware Glob and grep tools over a directory root_path , use_ripgrep FilesystemMiddleware , SubAgentMiddleware , MemoryMiddleware , SkillsMiddleware (deepagents) Files as context, delegation, memory files, on-demand skills Backends: StateBackend , StoreBackend , CompositeBackend RubricMiddleware (beta) Self-grade against a rubric and iterate max_iterations LLMToolEmulator Fake tool results for tests tools , model Provider-specific Anthropic prompt caching, bash, text editor, memory; Bedrock prompt caching; OpenAI moderation See integrations A sensible production stack (outer to inner): call limits → HITL → PII → summarisation or context editing → model retry/fallback → tool error → tool retry. The one ordering rule worth memorising: HITL must wrap retry and error middleware in per-call mode, or a retried call asks the reviewer again. Traps. Keep middleware single-purpose. Hooks that run before a HITL pause run again on resume, so they must be side-effect free. thread_limit on any limiter silently does nothing without a checkpointer. Summarisation compresses text only; images are not shrunk. 📖 Overview · Prebuilt · Custom 6. Memory: when to use which Analogy: a notepad on your desk versus a filing cabinet in the archive. The notepad (short-term memory) holds this conversation and is thrown away or archived with it. The cabinet (long-term memory) holds things worth knowing in any future conversation. The desk is small, so you also need a rule for when to summarise the notepad. 6.1 Decision table You need… Use Mechanism The agent to remember earlier turns of this conversation Short-term memory checkpointer plus a stable thread_id Pause and resume later (approvals, crashes) Short-term memory Same checkpointer; required for HITL The conversation is getting too long for the context window Trim, delete or summarise @before_model trim, RemoveMessage , or SummarizationMiddleware Remember a user across sessions (preferences, profile, learned facts) Long-term memory store with namespace and key; read/write from tools or middleware Find memories by meaning, not exact key Store with semantic index InMemoryStore(index={'embed':..., 'dims':...}) then store.search(query=...) Per-request settings (user ID, tenant, keys) Not memory: runtime context context_schema plus context= on invoke Large intermediate artefacts (search dumps, files) Filesystem , not messages FilesystemMiddleware ; route /memories/ to a StoreBackend to persist Static reference knowledge Not memory: prompt, skills or retrieval §12 6.2 Short-term memory (thread scope) from langgraph.checkpoint.postgres import PostgresSaver # pip install langgraph-checkpoint-postgres 'psycopg[binary]'
with PostgresSaver.from_conn_string(DB_URI) as cp:
 cp.setup() # creates tables
 agent = create_agent('openai:gpt-5.5', tools=[...], checkpointer=cp)
 agent.invoke({'messages': 'Hi, I am Bob'}, {'configurable': {'thread_id': 'cust-17'}}) State is read at the start of each step and written when a step completes. Custom fields: subclass AgentState (TypedDict) and pass it through state_schema or, better, a middleware's state_schema . InMemorySaver is for development; use Postgres, SQLite, Mongo or Cosmos-backed savers in production. # Trim (transient is possible via wrap_model_call; this one rewrites state)
from langchain.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
@before_model
def trim(state: AgentState, runtime: Runtime):
 m = state['messages']
 if len(m) <= 3: return None
 return {'messages': [RemoveMessage(id=REMOVE_ALL_MESSAGES), m[0], *m[-3:]]}

# Summarise (persistent)
SummarizationMiddleware(model='openai:gpt-5.4-mini', trigger=('tokens', 4000), keep=('messages', 20)) Choosing a strategy. Trim is cheap and lossy: fine for chit-chat. Delete is surgical: remove specific messages. Summarise costs an extra model call but keeps meaning: use for long support or research threads. Context editing clears old tool outputs only: use when tool results are what bloat the window. Always keep history valid : a tool-call AIMessage must be followed by its ToolMessage, and some providers want a user message first. RemoveMessage only works on a key with the add_messages reducer (the default messages key has it). 6.3 Long-term memory (cross-thread) from langgraph.store.memory import InMemoryStore # PostgresStore in production
store = InMemoryStore(index={'embed': embeddings, 'dims': 1536, 'fields': ['$']})
store.put(('user_123', 'memories'), 'm1', {'text': 'Prefers short, direct answers'})
hits = store.search(('user_123', 'memories'), query='communication style', limit=3)

@tool
def save_memory(text: str, runtime: ToolRuntime[Context]) -> str:
 '''Save a durable fact about the user.'''
 runtime.store.put((runtime.context.user_id, 'memories'), str(uuid7()), {'text': text})
 return 'saved'

agent = create_agent(model, tools=[save_memory], store=store, context_schema=Context) Model: JSON documents under a namespace tuple (like a folder, usually including user or org ID) and a key (like a file name). Cross-namespace search is by prefix and content filter. Nothing is injected automatically. You must read memories (a tool the model can call, or a @dynamic_prompt / wrap_model_call that injects them) and write them (a tool, or a background step after the turn). Decide deliberately between 'model decides what to remember' (tool, flexible, sometimes forgets) and 'we extract after every turn' (middleware, consistent, costs a call). Use user-scoped namespaces so one user can never read another's memories. Namespace prefix matching returns sub-namespaces too. On the managed platform the store is provisioned for you; semantic search needs index settings in langgraph.json . Traps. (1) Reusing a thread_id across users leaks history. (2) A fresh thread_id means a blank notepad, not a lost cabinet: long-term memory survives because it is in the store. (3) InMemoryStore and InMemorySaver vanish on restart. (4) Summarisation permanently replaces messages; if you need the originals for audit, write them elsewhere first. 📖 Short-term memory · Long-term memory · Memory concepts · Checkpointer integrations · Store integrations 7. Context engineering Analogy: packing the briefing folder for a consultant. The consultant is capable, but if the folder holds the wrong pages, the advice will be wrong. Most agent failures are the wrong folder, not a weak consultant. Agents usually fail because the right context was not passed to the model, not because the model is too weak. LangChain splits what you control into three kinds: Context type You control Lifetime Model context System prompt, messages, tools, model, response format for one call Transient (does not change saved state) Tool context What tools read and write (state, store, runtime context) Persistent Life-cycle context What happens between steps: summarise, guardrails, logging Persistent Data source Also called Scope Examples Runtime context Static config One run User ID, role, API keys, environment State Short-term memory One conversation Messages, uploaded files, auth status Store Long-term memory Across conversations Preferences, extracted insights Transient versus persistent. wrap_model_call with request.override(...) changes only what this call sees. To change saved history, return a Command from the wrap hook or use before_model , after_model or a tool. Recency matters. Models pay more attention to the last messages, so injected context (compliance rules, style guide) is appended after history rather than before it. Typical moves: dynamic system prompt by role or environment; inject uploaded-file summaries; filter tools by authentication state; route to a bigger model for long threads; switch response_format by stage. Start simple: static prompt and tools first, add one dynamic behaviour at a time, and watch token use and latency. 📖 Context engineering in agents · Context overview 8. Structured output Analogy: a form instead of an essay. You hand the model a form with typed boxes. You get back something your code can use without parsing prose. from pydantic import BaseModel, Field
from langchain.agents.structured_output import ToolStrategy, ProviderStrategy

class Ticket(BaseModel):
 category: str = Field(description='billing, technical, account or product')
 priority: str
 summary: str

agent = create_agent(model='openai:gpt-5.5', tools=[], response_format=Ticket) # auto strategy
r = agent.invoke({'messages': [{'role': 'user', 'content': 'My card was charged twice!'}]})
r['structured_response'] # Ticket(...) Option Behaviour Pick it when Pass a schema type Auto: provider-native if the model supports it, else tool-calling Default ProviderStrategy(schema, strict=...) ⚑ Provider enforces the schema; most reliable Provider supports it; need strict adherence ToolStrategy(schema, handle_errors=...) Schema becomes a tool; model must call it; validation errors are fed back for retry Provider lacks native support; union types Schema types: Pydantic (returns validated instance), dataclass or TypedDict (return a dict), JSON Schema (needs top-level title and description , and must be wrapped in an explicit strategy), and Union[...] with ToolStrategy so the model picks one shape. handle_errors : True (default, retry with a template message), a string (always that message), an exception type or tuple (only those), a callable returning a message, or False (raise). If the model returns two structured outputs at once, the agent feeds back an error and asks for one. tool_message_content customises the confirmation line that lands in history. If you pass tools and a schema, the model must support using both together. Structured output versus a tool: use response_format for the final answer's shape ; use a tool when something must happen mid-run. Outside agents, use model.with_structured_output (§1). 📖 Structured output 9. Human-in-the-loop and guardrails Analogy: a second signature on the cheque. The agent may prepare the transfer, but for large amounts a human signs before it goes out. The agent waits, with its place saved, as long as it takes. from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.types import Command

agent = create_agent('openai:gpt-5.5', tools=[write_file, execute_sql, read_data],
 middleware=[HumanInTheLoopMiddleware(interrupt_on={
 'write_file': True, # all decisions allowed
 'execute_sql': {'allowed_decisions': ['approve', 'reject']},
 'read_data': False, # auto-approve
 })],
 checkpointer=InMemorySaver()) # REQUIRED
cfg = {'configurable': {'thread_id': 't1'}}
r = agent.invoke({'messages': [...]}, config=cfg, version='v2')
r.interrupts # what needs review
agent.invoke(Command(resume={'decisions': [{'type': 'approve'}]}), config=cfg, version='v2') # same thread_id Decision Effect Note approve Run as proposed edit Run with changed args ( edited_action ) Edit conservatively; big edits make the model re-plan and may repeat the call reject Skip and send feedback message Use this to deny. Say whether the agent may retry respond Your reply becomes the tool result For 'ask user' tools only. The model sees a success , so never use it to deny Batched mode (default): one interrupt per model turn listing all gated calls; resume with an ordered decisions list. interrupt_mode='per_call' ⚑: one interrupt per call, each with a response_schema , resumed with a dict keyed by interrupt ID. The docs recommend per-call for new agents and plan to make it the default next major version. Conditional gating ⚑: 'when': predicate(request) pauses only risky calls (for example SQL that is not a SELECT). The predicate re-runs on resume and must give the same answer, or the reviewer's decision is ignored. In per-call mode an invalid answer is rejected before saving, so send a corrected answer to the same interrupt ID. If several answers are sent together and one is invalid, others may have run, so validate first or answer one at a time. Stream while pausing: stream = agent.stream_events(..., version='v3') , check stream.interrupted and stream.interrupts . Guardrails are policies enforced deterministically regardless of what the model does: PIIMiddleware (redact/mask/hash/block, with custom detectors), call limits, and your own after_agent checks (including model-based safety checks using jump_to='end' ). A system prompt asking the model to behave is not a guardrail. 📖 Human-in-the-loop · HITL concepts · Guardrails 10. Streaming Analogy: a live sports ticker instead of the final score. You can show progress (each step), words as they are typed (tokens), or your own custom events ( 'Fetched 10/100 records' ). Mode Yields updates State update after each agent step (model, tools, model) messages (token, metadata) from any node that calls an LLM (metadata has langgraph_node , lc_agent_name ) custom Anything written with runtime.stream_writer or get_stream_writer() values Full state after each step # Classic modes: v2 format = one dict per chunk with type, ns, data
for chunk in agent.stream(inp, stream_mode=['updates', 'messages', 'custom'], version='v2'):
 if chunk['type'] == 'messages':
 token, meta = chunk['data']

# Event streaming (recommended for new apps, langchain 1.3+): one typed iterator per projection
stream = agent.stream_events(inp, config=cfg, version='v3')
for kind, item in stream.interleave('messages', 'tool_calls'):
 if kind == 'messages':
 for t in item.text: print(t, end='')
final = stream.output Reasoning tokens: iterate message.reasoning in event streaming, or filter content_blocks for reasoning . Subagents and nested graphs: pass subgraphs=True on classic streaming, or read stream.subgraphs in event streaming. Name every agent so you can tell who is talking. Tool streaming: tool calls arrive as tool_call_chunk blocks (partial JSON); complete calls come from updates or by summing chunks until chunk_position == 'last' . Turn it off for a model with streaming=False (or disable_streaming=True ) when you do not want its tokens reaching the client. If a custom tool uses get_stream_writer , it can no longer run outside a LangGraph context. 📖 Streaming · Event streaming · Frontend 11. Multi-agent patterns Analogy: a hospital. A generalist (single agent) can handle most cases. When the case needs a specialist's long reference books, you either call the specialist in ( subagent ), transfer the patient ( handoff ), look up a protocol ( skill ), or triage at the door ( router ). First question: do you need multi-agent at all? A single agent with the right tools and prompt often suffices. Reach for multi-agent when (a) context management: specialised knowledge would overflow one prompt, (b) distributed development: separate teams own capabilities, or (c) parallelisation. Also when one agent has too many tools and picks poorly. Pattern How it works Strengths Subagents Main agent calls subagents as tools; all routing goes through it Isolation, parallel calls, large-context domains; stateless by default Handoffs Tool calls change a state variable; the active agent or its prompt/tools switch Direct user conversation with the specialist; stateful Skills One agent loads specialised prompts on demand Simple, directly conversational; context accumulates Router A step classifies input and sends it to one or more agents, then synthesises Parallel fan-out across knowledge sources; stateless Custom workflow LangGraph graph mixing deterministic and agentic nodes Full control; embed any other pattern as a node Measured trade-offs from the docs: one-shot 'buy coffee' costs 4 model calls with subagents but 3 with handoffs, skills or router. A repeat request costs 8 total with subagents (stateless) versus 5 with handoffs or skills (stateful). Multi-domain comparison (three languages, about 2K tokens of docs each): subagents and router about 9K tokens, skills about 15K (context accumulates), handoffs 14K+ and sequential. Rule of thumb: parallel and big-context → subagents or router; repeat and conversational → handoffs or skills. @tool
def ask_fruit_expert(question: str) -> str:
 '''Ask the fruit expert. Use for ALL fruit questions.'''
 r = fruit_agent.invoke({'messages': [{'role': 'user', 'content': question}]})
 return r['messages'][-1].content
supervisor = create_agent(model, tools=[ask_fruit_expert, ask_veggie_expert], checkpointer=cp) Traps. A per-thread stateful subagent ( checkpointer=True ) breaks when the model calls it twice in parallel (checkpoint conflict): add ToolCallLimitMiddleware(tool_name=..., run_limit=1) . The langgraph-supervisor package has a migration guide to this tool-wrapped pattern. Deep Agents ships subagents, skills, planning and filesystem if you would rather not assemble this yourself. 📖 Multi-agent · Subagents · Handoffs · Skills · Router · Custom workflow 12. Retrieval (RAG) Analogy: an open-book exam. Instead of memorising the library, the model gets a librarian (the retriever) who fetches the right pages when asked. Scope note: I did not re-read the RAG tutorials for this page; this section is the stable shape plus pointers. Verify names against the tutorials. The pipeline is: load documents → split into chunks → embed ( init_embeddings ) → store in a vector store → retrieve. Two ways to use it: agentic RAG (expose a retrieval tool ; the model decides when to search and can search several times) and two-step RAG (always retrieve first, then answer; predictable and cheap). Return the passage as the ToolMessage content and put document IDs or page numbers in artifact so your UI can cite without bloating the prompt. Use RAG when knowledge is large, changes often, or must be cited. Do not use it for facts that fit in the prompt, or as a substitute for structured data you can query exactly (use a SQL tool). Memory versus RAG: memory is about this user and these conversations ; RAG is about shared documents . 📖 Build a semantic search engine · Agentic RAG with LangGraph · SQL agent · Vector stores 13. Production: reliability, cost, security, testing Reliability stack: model max_retries plus ModelRetryMiddleware , ModelFallbackMiddleware for provider outages, tool retry and error middleware, a durable checkpointer, and call limits as circuit breakers. Cost: prompt caching, summarisation or context editing, a cheap model for routing and summaries (a wrap_model_call router), tool filtering, and ModelCallLimitMiddleware . Security: treat tool output as untrusted input (prompt injection can arrive inside a web page or document); gate side effects with HITL; run shell tools under Docker or a sandbox policy, never the host policy on untrusted input; redaction rules do not stop exfiltration on the host; use PII middleware; sanitise error text returned to the model; never load() untrusted serialised messages; scope store namespaces per user. Observability: set up LangSmith tracing from day one; it records every turn, tool call and middleware span. Use a trace_policy ⚑ to omit large payloads. Testing: unit-test logic with fake chat models and in-memory persistence (no API calls); integration-test with real models (manage keys, flakiness, cost); evaluate trajectories with deterministic matching or LLM-as-judge; LLMToolEmulator fakes tools when real ones are expensive. Deployment: LangSmith deployment provisions checkpointer and store for you; locally pass them explicitly. 📖 Testing · Observability · Deployment · LangSmith Studio 14. Version gates and the trap list ⚑ Feature Minimum Model profiles, fraction triggers in summarisation langchain 1.1 ProviderStrategy(strict=...) langchain 1.2 Middleware stream transformers; PII output redaction in streams; event streaming langchain 1.3.x (1.3.2 for transformers/PII) HITL when predicate 1.3.3 ToolErrorMiddleware 1.3.14 Middleware trace_policy 1.3.15 Retry middleware respects is_retryable by default 1.3.16 langchain.mcp (beta) langchain[mcp] 1.4.0 HITL interrupt_mode='per_call' 1.4.6 reasoning_effort standard parameter langchain-core 1.5.2 plus provider package versions runtime.execution_info , server_info ; v2 stream format langgraph 1.1.x Trap checklist (read before every review): No checkpointer, yet expecting memory or HITL. Or a reused thread_id across users. InMemory* in production. Tool with a vague docstring, or no ToolMessage after returning a Command. Too many tools; huge tool outputs; no call limits. Retry placed outside HITL; side effects before an interrupt. Structured output with a pre-bound model, or a raw JSON Schema not wrapped in a strategy. Old tutorial imports ( prompt= , langchain.chains , Pydantic agent state) on a v1 install. Trusting the system prompt as a security control. 15. Exercises Build an agent with one @tool that reads runtime.context.user_id , a checkpointer , and a thread_id . Prove it remembers turn 1 on turn 2, then change only the thread_id and show it forgets. Add SummarizationMiddleware with a tiny trigger ( ('messages', 6) ), run 10 turns, and print the history to see the summary message replace the old ones. Add a save_memory tool plus an InMemoryStore . In thread A tell the agent a preference; in thread B (new thread_id , same user_id ) show it can recall it via a search tool. Gate execute_sql with HITL so only non-SELECT queries pause (a when predicate). Approve one, reject one with a message, and observe how the model reacts to the rejection. Write a wrap_model_call router that uses a cheap model for the first 6 messages and a stronger one after. Verify with usage_metadata or LangSmith. Solution notes Same thread_id reloads state from the checkpointer; a new one starts empty. context is separate and must be passed on every call. Summarisation is persistent: the checkpointed state now holds a summary message plus the last keep messages. Trim, by contrast, only changes what is sent if done in wrap_model_call . The store key space is (user_id, 'memories') , independent of thread. The agent will not use the memory unless a tool or prompt injection reads it. when returns True to pause. On resume it is evaluated again and must match. A reject message should tell the agent whether to retry. request.override(model=...) changes only this call; models should be created once outside the hook. Sources: docs.langchain.com (Python): LangChain overview , products , agents , models , messages , tools , short-term memory , long-term memory , middleware , structured output , HITL , streaming , multi-agent , context engineering . RAG section: scope note above.