R.2

Middleware hooks and classes

AgentMiddleware has six hooks with a sync and an async form each, and langchain 1.5.0 builds 19 middleware classes on them.

Every middleware is a subclass of AgentMiddleware in langchain.agents.middleware. The module exports 50 names. A path in this page is relative to libs/langchain_v1/langchain/agents/middleware/ at langchain==1.5.0, unless it names another package. Section 4.5 gives the order of the hooks, and section 4.6 tells you when to use each class.

The six hooks

AgentMiddleware starts at line 387 of types.py.

HookAsync formKindArgumentsReturnsLine
before_agentabefore_agentnodestate, runtimea state update or None433, 444
before_modelabefore_modelnodestate, runtimea state update or None457, 468
wrap_model_callawrap_model_callwraprequest, handlera ModelResponse, an AIMessage, or an ExtendedModelResponse505, 600
after_modelaafter_modelnodestate, runtimea state update or None481, 492
wrap_tool_callawrap_tool_callwraprequest, handlera ToolMessage or a Command676, 758
after_agentaafter_agentnodestate, runtimea state update or None652, 663

A middleware with only the sync form of a wrap hook raises NotImplementedError under ainvoke. The message lists three ways to fix it, and the reverse case raises too.

Order and names

Rule
A node hook becomes the graph node <name>.<hook>, such as HumanInTheLoopMiddleware.after_model.
The default name is the class name. Two middlewares with one name raise AssertionError.
before_agent and before_model run in list order.
after_model runs in reverse list order, because the model node leads to the last one.
after_agent also runs in reverse list order, once at the end of the run.
The first middleware in the list is the outer layer of each wrap hook.
A node hook can return jump_to only to targets that it declares with hook_config(can_jump_to=...).

Capture 09-middleware-order.txt records the order for one tool round trip with three middlewares.

Decorators

Each decorator turns one function into a middleware class with one hook.

DecoratorHookLine
before_agentbefore_agent1320
before_modelbefore_model954
after_modelafter_model1143
after_agentafter_agent1532
wrap_model_callwrap_model_call1866
wrap_tool_callwrap_tool_call2039
dynamic_promptwrap_model_call, and it sets the system message1706
hook_confignone. It declares can_jump_to on a hook method881

The node hook decorators take the keywords state_schema, tools, can_jump_to, and name. The two wrap decorators take no can_jump_to.

Request and response types

TypeFieldsLine
ModelRequestmodel, messages without the system message, system_message, tool_choice, tools, response_format, state, runtime, model_settings. Change it with override(**kw)types.py:90
ModelResponseresult, a list of messages, and structured_responsetypes.py:275
ExtendedModelResponsemodel_response and an optional commandtypes.py:293
ToolCallRequesttool_call, tool, state, runtime. Change it with override(**kw)langgraph.prebuilt tool_node.py:141

The 19 classes

Each row gives the hooks, the constructor defaults that change behaviour, and the file and line of the class and of its __init__. A parameter without a default is required.

ClassHooksConstructor defaultsFile and line
SummarizationMiddlewarebefore_modelmodel required, trigger=None, keep=("messages", 20), trim_tokens_to_summarize=4000summarization.py:263, :282
ContextEditingMiddlewarewrap_model_calledits=None, token_count_method="approximate"context_editing.py:187, :201
HumanInTheLoopMiddlewareafter_model, wrap_tool_callinterrupt_on required, description_prefix="Tool execution requires approval", interrupt_mode="batched"human_in_the_loop.py:398, :491
ModelCallLimitMiddlewarebefore_model, after_modelthread_limit=None, run_limit=None, exit_behavior="end"model_call_limit.py:94, :126
ToolCallLimitMiddlewareafter_modeltool_name=None, thread_limit=None, run_limit=None, exit_behavior="continue"tool_call_limit.py:141, :202
ToolRetryMiddlewarewrap_tool_callmax_retries=2, tools=None, on_failure="continue", backoff_factor=2.0, initial_delay=1.0, max_delay=60.0, jitter=Truetool_retry.py:32, :133
ModelRetryMiddlewarewrap_model_callmax_retries=2, on_failure="continue", backoff_factor=2.0, initial_delay=1.0, max_delay=60.0, jitter=Truemodel_retry.py:33, :116
ModelFallbackMiddlewarewrap_model_callfirst_model, then any number of other modelsmodel_fallback.py:342, :368
ModelRefusalMiddlewarewrap_model_callno parametersmodel_refusal.py:39
ToolErrorMiddlewarewrap_tool_callon_error=None, aon_error=None, tools=None. With neither handler it raises ValueErrortool_error.py:37, :84
PIIMiddlewarebefore_model, after_modelpii_type required, strategy="redact", apply_to_input=True, apply_to_output=False, apply_to_tool_results=Falsepii.py:513, :577
ModelRouterMiddlewarebefore_agent, wrap_model_callchoices, instructions, and classifier required. Beta, marked with @beta, new in 1.5.0, by the release notesmodel_router.py:72, :121
AutoModeMiddlewarewrap_tool_calltools and classifier required, criteria=None. Beta in its docstring only, with no @beta mark and no warning, new in 1.5.0, by the release notesauto_mode.py:64, :117
TodoListMiddlewarewrap_model_call, after_modela default system prompt and tool descriptiontodo.py:174, :203
LLMToolSelectorMiddlewarewrap_model_callmodel=None, max_tools=None, always_include=None, max_retries=1tool_selection.py:121, :150
LLMToolEmulatorwrap_tool_calltools=None, model=Nonetool_emulator.py:27, :71
ProviderToolSearchMiddlewarewrap_model_callsearchable_tools=Noneprovider_tool_search.py:57, :93
ShellToolMiddlewarebefore_agent, after_agentworkspace_root=None, execution_policy=None, which becomes HostExecutionPolicy(), tool_name="shell"shell_tool.py:518, :537
FilesystemFileSearchMiddlewarenone. It adds tools onlyroot_path required, use_ripgrep=True, max_file_size_mb=10file_search.py:108, :133

A max_retries of 2 means 3 attempts in all. retry_on defaults to default_retry_on in both retry classes, as section 4.7 explains. With the default trigger=None, SummarizationMiddleware never summarizes.

Types of human review

NameValues or fieldsLine in human_in_the_loop.py
DecisionTypeapprove, edit, reject, respond87
InterruptModebatched, per_call170
HITLRequestaction_requests, review_configs107
HITLResponsedecisions289
InterruptOnConfigallowed_decisions, description, args_schema, when306

True in interrupt_on allows all four decisions. Section 6.5 runs both modes.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11