Middleware: hooks and their order
A middleware has six hooks, the four node hooks become graph nodes, and before_* hooks run in list order while after_* hooks run in reverse.
You add a logging middleware and a redaction middleware to an agent. The log shows the redacted text on the way in and the raw text on the way out. The order of the middleware list did that, and it works in two directions.
When you finish this section, you can write a middleware and say where each of its hooks runs. You can also predict the order of hooks from several middlewares. You can also say what a change of order breaks.
The six hooks
Middleware: an object of a subclass of AgentMiddleware that create_agent runs at fixed points of the agent loop.
Node hook: a hook that create_agent turns into a graph node. It takes the state and the runtime, and returns a state update or None.
Wrap hook: a hook that takes a request and a handler, and calls the handler to run the model or the tool. It can change the request, call the handler again, or return without a call.
| Hook | Kind | When it runs | It returns |
|---|---|---|---|
before_agent | node | once, at the start of each run | a state update or None |
before_model | node | before each model call | a state update or None |
wrap_model_call | wrap | around each model call, inside the model node | a ModelResponse, an AIMessage, or an ExtendedModelResponse |
after_model | node | after each model call | a state update or None |
wrap_tool_call | wrap | around each tool call, inside the tools node | a ToolMessage or a Command |
after_agent | node | once, at the end of each run | a state update or None |
Each hook has an async twin with an a in front, such as abefore_model. A middleware with only a sync wrap_model_call raises NotImplementedError when the agent runs under ainvoke. A middleware can also declare tools and a state_schema, and create_agent adds both to the agent.
The kit middleware Traced writes one line for each hook it runs. Its model wrapper shows the shape of every wrap hook:
def wrap_model_call(self, request, handler):
self.log.append(f"{self.label}.wrap_model_call enter")
response = handler(request)
self.log.append(f"{self.label}.wrap_model_call exit")
return responseFor a hook or two, the decorators before_model, after_model, before_agent, after_agent, wrap_model_call, wrap_tool_call, and dynamic_prompt turn one function into a middleware.
Hooks become nodes
The kit builds an agent with middleware=[A, B, C], three Traced instances. Each node hook is a node named <middleware name>.<hook>. The edges chain them in the list order on the way in:
"A.before_agent -> B.before_agent",
"A.before_model -> B.before_model",
…
"B.before_agent -> C.before_agent",
"B.before_model -> C.before_model",
…
"C.before_agent -> A.before_model",
"C.before_model -> model",
…
"__start__ -> A.before_agent",On the way out, the edge from model goes to the last middleware first:
"A.after_model -> A.before_model",
"A.after_model -> C.after_agent",
"A.after_model -> tools",
…
"B.after_model -> A.after_model",
…
"C.after_model -> B.after_model",
…
"model -> C.after_model",A.after_model is the last node hook after the model. Its three edges go to tools, to the end through C.after_agent, or back to A.before_model for a jump. After tools, the loop goes back to A.before_model, so before_agent hooks run once for each run.
Figure 4.8 draws the same graph from its Mermaid text. The before hooks run down to model, and the after hooks run down to the end in reverse order.
The order of one tool round trip
The kit ran one question with one tool call and recorded every hook:
"A.before_agent",
"B.before_agent",
"C.before_agent",
"A.before_model",
"B.before_model",
"C.before_model",
"A.wrap_model_call enter",
"B.wrap_model_call enter",
"C.wrap_model_call enter",
" model called",
"C.wrap_model_call exit",
"B.wrap_model_call exit",
"A.wrap_model_call exit",
"C.after_model",
"B.after_model",
"A.after_model",
"A.wrap_tool_call enter add",
"B.wrap_tool_call enter add",
"C.wrap_tool_call enter add",
"C.wrap_tool_call exit",
"B.wrap_tool_call exit",
"A.wrap_tool_call exit",
…
"C.after_agent",
"B.after_agent",
"A.after_agent"Three rules give this order, and figure 4.9 draws them:
before_agentandbefore_modelhooks run in list order, A then B then C.after_modelandafter_agenthooks run in reverse list order, C then B then A.- Wrap hooks nest. The first middleware in the list is the outermost layer, so A enters first and exits last.
The custom middleware page states the same three rules. Our capture agrees with it at the pin.
What the order changes
Put a middleware first when it must see the raw request and the final response. A wrap hook in front sees everything the later ones do. A node hook in front runs first before the model and last after it.
The reverse order of after_model has a cost. A middleware that sets jump_to from after_model runs before the after_model hooks of every middleware in front of it. If one of those is HumanInTheLoopMiddleware, the jump can skip the review. The other order failed too in batched mode: a rejected call still ran. Section 6.5 shows both cases, as issue langchain#40492 reports, and per-call mode was safe in both orders. The human in the loop page says to list HumanInTheLoopMiddleware before retry and error middleware.
jump_to: a key that a node hook returns to move the run to model, tools, or end. A hook can use it only when it declares the targets with hook_config(can_jump_to=...) or the can_jump_to option of a decorator.
Names must be unique
create_agent names a middleware by its name property, which is the class name by default. Two instances of one class have the same name, and the agent refuses them:
create_agent(middleware=[A, A]):
raised builtins.AssertionError: Please remove duplicate middleware instances.To use two instances of one class, give each its own name. The kit Traced middleware returns its label as the name:
@property
def name(self):
return self.labelSection 8.3 gives the measured cost of each hook.
LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11