4.5

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.

HookKindWhen it runsIt returns
before_agentnodeonce, at the start of each runa state update or None
before_modelnodebefore each model calla state update or None
wrap_model_callwraparound each model call, inside the model nodea ModelResponse, an AIMessage, or an ExtendedModelResponse
after_modelnodeafter each model calla state update or None
wrap_tool_callwraparound each tool call, inside the tools nodea ToolMessage or a Command
after_agentnodeonce, at the end of each runa 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:

pythona wrap_model_call hookFull log
    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 response
One method of the Traced middleware. The other hooks append one line each.

For 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:

jsonthe edges into the model nodeFull log
  "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",
Cut to the edges from __start__ to model.

On the way out, the edge from model goes to the last middleware first:

jsonthe edges out of the model nodeFull log
  "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",
Cut to the after_model edges.

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.

Fig. 4.8the graph of middleware A, B, and Cstructure
The graph of middleware A, B, and C The compiled graph of create_agent with tools=[add] and middleware=[A, B, C], drawn from its draw_mermaid output. It has 16 nodes, 12 of them hook nodes, and 17 edges, 4 of them conditional. The before hooks run A, B, C from the top. The after_model hooks run C, B, A under model. A.after_model has three conditional edges: to tools, to C.after_agent, and back to A.before_model. tools goes back to A.before_model. GET_GRAPH() OF THE AGENT 16 nodes, 12 of them hooks __start__ model tools __tools = add A.before_agent A.before_model A.after_model A.after_agent B.before_agent B.before_model B.after_model B.after_agent C.before_agent C.before_model C.after_model C.after_agent __end__ plain edge conditional edge, chosen at run time
The before hooks chain in list order into model, the after_model hooks chain in reverse, and A.after_model chooses between tools, the end, and A.before_model. Read from __start__ at the top. Blue boxes are hook nodes. The dashed amber lanes at the sides go back up to A.before_model.

The order of one tool round trip

The kit ran one question with one tool call and recorded every hook:

jsonthe hook order for one tool round tripFull log
  "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"
Cut to the first model call and the tool call. The second model call repeats the model part, and the three after_agent hooks end the run.

Three rules give this order, and figure 4.9 draws them:

  1. before_agent and before_model hooks run in list order, A then B then C.
  2. after_model and after_agent hooks run in reverse list order, C then B then A.
  3. Wrap hooks nest. The first middleware in the list is the outermost layer, so A enters first and exits last.
Fig. 4.9the order of hooks from three middlewaresflow
The order of hooks from three middlewares A trace of the 38 hook calls that middleware=[A, B, C] logged in one tool round trip, read from left to right. Three lanes, A, B and C, and a fourth lane for the model and the tool. Each dot is one node hook. Each bar is one wrap hook, from its enter to its exit. 9 numbered phases run along the top: before_agent A B C, before_model A B C, wrap_model_call entered A B C with the model inside and left C B A, after_model C B A, wrap_tool_call entered A B C around the add tool and left C B A, the same model pass again, and after_agent C B A. The bars of A are the longest, so A is the outer layer. Under the trace, the graph edges read from the compiled agent: C.before_model to model to C.after_model to B.after_model to A.after_model. 38 HOOK CALLS IN THE ORDER THEY RAN 1 2 3 4 5 6 7 8 9 A B C model, tool PHASES 1 before_agent: A B C 2 before_model: A B C 3 wrap_model_call: A B C 4 after_model: C B A 5 wrap_tool_call: A B C 6 before_model: A B C 7 wrap_model_call: A B C 8 after_model: C B A 9 after_agent: C B A before_ node hook after_ node hook wrap_model_call wrap_tool_call GRAPH EDGES AROUND THE MODEL NODE C.before_model model C.after_model B.after_model A.after_model Each after_model hook is its own node, and the edges run in the reverse of the list order.
Node hooks run A, B, C before the model and C, B, A after it, and wrap hooks nest with A as the outer layer. Read the trace from left to right. Each dot is one node hook in lane A, B, or C, and each bar is one wrap hook from enter to exit. The numbered phases are keyed under the trace, and the bottom row is the edges around the model node.

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:

outputtwo middleware with the same nameFull log
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:

pythona name propertyFull log
    @property
    def name(self):
        return self.label

Section 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