Middleware Overview

Purpose and Scope

Middleware is the extension layer for LangChain agents: it lets application developers influence what happens around model calls, tool calls, state updates, safety checks, and lifecycle boundaries without rewriting the whole agent loop. The package entrypoint describes middleware as plugins used with Agents and gathers the public middleware classes, hook decorators, request and response types, and runtime integration points under one import surface. In practice, this makes middleware the place to add cross-cutting behavior such as retry policy, context reduction, PII controls, shell execution policy, file search tools, and human review workflows.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py

The official docs frame middleware as a way to more tightly control what happens inside an agent: tracking behavior, transforming prompts or tool selection, adding retries and fallbacks, applying guardrails, and terminating early when needed. The Python package mirrors that role by exporting hook names like before_agent, before_model, after_model, after_agent, wrap_model_call, wrap_tool_call, and dynamic_prompt. Those names are important because they describe the points where middleware can observe or modify execution while preserving the standard agent abstraction.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py

Relevant Source Files

• libs/langchain_v1/langchain/agents/middleware/__init__.py is the public middleware entrypoint. It imports and re-exports middleware classes, hook helpers, agent state types, model request and response contracts, tool call request contracts, and Runtime from LangGraph.
• libs/langchain_v1/langchain/agents/middleware/_execution.py defines execution policy primitives for persistent shell middleware, including the abstract base policy and host, sandbox, and Docker-oriented policy exports surfaced by the package entrypoint.
• libs/langchain_v1/langchain/agents/middleware/_redaction.py contains shared PII detection and redaction utilities, including detector signatures, match records, supported redaction strategies, and the blocking exception used by PII middleware.
• libs/langchain_v1/langchain/agents/middleware/_retry.py contains shared retry policy helpers used by model and tool retry middleware, including retry predicates, failure handling modes, parameter validation, and exponential backoff delay calculation.
• libs/langchain_v1/langchain/agents/middleware/context_editing.py implements model-agnostic context editing that clears older tool outputs once a token threshold is exceeded.
• libs/langchain_v1/langchain/agents/middleware/file_search.py implements filesystem-backed Glob and Grep tools as middleware-provided capabilities for agents that need file search.

Public Middleware Surface

The middleware package intentionally exposes both ready-made middleware and low-level authoring hooks. The ready-made classes include ContextEditingMiddleware, FilesystemFileSearchMiddleware, HumanInTheLoopMiddleware, ModelCallLimitMiddleware, ModelFallbackMiddleware, ModelRetryMiddleware, PIIMiddleware, ProviderToolSearchMiddleware, ShellToolMiddleware, SummarizationMiddleware, TodoListMiddleware, ToolCallLimitMiddleware, ToolRetryMiddleware, LLMToolEmulator, and LLMToolSelectorMiddleware. This is more than a catalog: it tells readers that middleware can add capabilities, enforce limits, transform state, emulate or select tools, retry calls, summarize conversation history, and gate risky actions.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py

The same entrypoint also exports the contracts middleware authors use to participate in the agent runtime. AgentMiddleware, AgentState, InputAgentState, and OutputAgentState describe stateful participation. ModelRequest, ModelResponse, ExtendedModelResponse, and ModelCallResult describe model-call boundaries. ToolCallRequest represents tool-call interception. The hook functions and decorators exported from the package provide the vocabulary for lifecycle behavior: run before or after the agent, run before or after model calls, wrap model calls, wrap tool calls, configure hooks, or supply a dynamic prompt.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py

System-to-Code Mapping

Concern	Source-backed implementation signal	What it means for developers
Public imports	libs/langchain_v1/langchain/agents/middleware/__init__.py	Import middleware and hook primitives from langchain.agents.middleware rather than reaching into implementation modules.
Runtime safety	libs/langchain_v1/langchain/agents/middleware/_redaction.py	Use PII detection, masking, hashing, redaction, or blocking behavior when sensitive text may pass through prompts, tools, or outputs.
Resilience	libs/langchain_v1/langchain/agents/middleware/_retry.py	Apply consistent retry validation, retry predicates, exponential backoff, jitter, and failure handling across model and tool middleware.
Context management	libs/langchain_v1/langchain/agents/middleware/context_editing.py	Reduce oversized conversation state by clearing older tool outputs while keeping recent results and selected tools intact.
Local capability injection	libs/langchain_v1/langchain/agents/middleware/file_search.py	Add agent-accessible filesystem search tools without requiring each agent definition to manually implement Glob and Grep.
Shell execution policy	libs/langchain_v1/langchain/agents/middleware/_execution.py	Choose a host, sandbox, or Docker-oriented execution policy with explicit timeout and output constraints.

Middleware is best understood as a set of contracts plus implementations. The contract layer gives all middleware the same shape: it can receive state, context, requests, responses, and runtime information at predictable boundaries. The implementation layer then applies a particular policy. For example, retry middleware needs to know whether an exception is retryable and how long to wait; context editing needs to inspect message history and token counts; file search needs to validate paths and patterns before exposing search results back to the agent.

Sources: libs/langchain_v1/langchain/agents/middleware/_retry.py, libs/langchain_v1/langchain/agents/middleware/context_editing.py, libs/langchain_v1/langchain/agents/middleware/file_search.py

Execution Flow and Lifecycle Hooks

A typical agent loop alternates between model reasoning and tool execution until the model returns without further tool calls. Middleware fits around that loop rather than replacing it. A before_model hook can prepare or constrain the request before the chat model sees it. A wrap_model_call hook can decide how the model call is executed, including fallback or retry behavior. A wrap_tool_call hook can inspect or intervene before an external tool runs. After-call hooks can record results, modify state, or enforce output rules before execution continues.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py

The representative modules show how those hook opportunities become concrete agent behavior. Context editing operates on message lists and uses approximate token counting to decide when to replace old ToolMessage content with a placeholder. File search middleware exposes Glob and Grep style tools rooted at a configured directory, with path containment checks and include-pattern validation to keep searches inside the intended filesystem boundary. Retry helpers centralize how middleware validates retry settings and calculates delay, so model and tool retry implementations can share predictable semantics.

Sources: libs/langchain_v1/langchain/agents/middleware/context_editing.py, libs/langchain_v1/langchain/agents/middleware/file_search.py, libs/langchain_v1/langchain/agents/middleware/_retry.py

Implementation Details

Context editing is a good example of middleware that changes agent state rather than adding a new external capability. ClearToolUsesEdit has a trigger token threshold, a clear_at_least target, a keep count for the most recent tool results, an option to clear originating tool call inputs, an exclude_tools list, and a placeholder string. When the token count is above the trigger, it finds older ToolMessage entries, skips excluded or already-cleared items, and replaces their content and artifact metadata while marking the response metadata with the context editing strategy.

Sources: libs/langchain_v1/langchain/agents/middleware/context_editing.py

Safety-focused middleware is represented by the shared redaction module. It defines RedactionStrategy as block, redact, mask, or hash; PIIMatch records the type, value, and text offsets for each match; Detector is a callable from string content to matches; and PIIDetectionError carries the PII type plus detected matches when blocking is configured. Built-in detectors include email addresses, credit card numbers with Luhn validation, IP addresses, MAC addresses, and URLs. These utilities give PII middleware structured findings instead of relying on untyped string replacement.

Sources: libs/langchain_v1/langchain/agents/middleware/_redaction.py

Execution policy support shows that middleware can also govern side effects. BaseExecutionPolicy defines common timeout and output limit fields and requires a spawn method for launching a persistent shell process. HostExecutionPolicy runs commands directly on the host and documents that it offers no filesystem or network sandboxing, although it can apply CPU and memory limits on supported platforms. The package entrypoint also exports CodexSandboxExecutionPolicy, DockerExecutionPolicy, HostExecutionPolicy, RedactionRule, and ShellToolMiddleware, making execution isolation a configurable policy decision.

Sources: libs/langchain_v1/langchain/agents/middleware/_execution.py, libs/langchain_v1/langchain/agents/middleware/init.py

Compact Reference

Name	Kind	Source-backed role
AgentMiddleware	Base contract	Author middleware that participates in agent state, context, model, and tool lifecycles.
before_agent, after_agent	Hook exports	Run logic at agent lifecycle boundaries.
before_model, after_model	Hook exports	Run logic around model request and response handling.
wrap_model_call, wrap_tool_call	Hook exports	Intercept model or tool execution and optionally add retry, fallback, safety, or instrumentation behavior.
dynamic_prompt	Hook export	Provide prompt behavior dynamically through middleware.
ModelRetryMiddleware, ToolRetryMiddleware	Middleware exports	Use shared retry semantics for failures around model or tool execution.
ContextEditingMiddleware, ClearToolUsesEdit	Middleware and edit strategy	Reduce context size by clearing older tool results when token thresholds are exceeded.
FilesystemFileSearchMiddleware	Middleware export	Add filesystem Glob and Grep search tools rooted at a configured path.
PIIMiddleware, PIIDetectionError	Middleware and exception export	Detect, redact, mask, hash, or block sensitive content.
ShellToolMiddleware plus execution policies	Middleware and policy exports	Run shell-backed tools under host, sandbox, or Docker-oriented policies.

When choosing middleware, start from the agent behavior you need to control. Use retry and fallback middleware for flaky model or tool dependencies. Use PII and guardrail-oriented middleware when prompts or tool results may contain sensitive data. Use context editing or summarization when long conversations threaten model context limits. Use file search or shell middleware when the agent needs local operational capabilities, and pair them with tight roots, timeouts, output caps, and execution policy choices. Read the customization page next if you need to implement a new hook rather than configure one of the exported middleware classes.

Sources: libs/langchain_v1/langchain/agents/middleware/init.py, libs/langchain_v1/langchain/agents/middleware/_execution.py, libs/langchain_v1/langchain/agents/middleware/_redaction.py, libs/langchain_v1/langchain/agents/middleware/_retry.py, libs/langchain_v1/langchain/agents/middleware/context_editing.py, libs/langchain_v1/langchain/agents/middleware/file_search.py