Tool middleware#

Tool middleware lets you wrap one function tool with async hooks that run immediately around its execution—the same idea as an agent's on_tool_execution() Middleware, but attached at tool definition time with plain callables (no BaseMiddleware subclass).

Use this pattern when behavior is specific to a single tool. For policies that apply to every tool on an agent, register BaseMiddleware with on_tool_execution() instead.

Why use it#

Tool-scoped hooks are optional. They help when:

• Colocation — Validation, redaction, or metrics for one tool live next to that implementation instead of in shared agent middleware.
• Clear contracts — Libraries can ship a tool with hooks that always run (normalize arguments, scrub secrets) without requiring consumers to register matching agent middleware.
• Simpler agents — You avoid a large on_tool_execution full of if event.name == ... when only a few tools need special handling.

Use agent middleware=[...] when the policy is global or shared across most tools. Use middleware=[...] on @tool, @agent.tool, or @toolkit.tool when the behavior belongs to that tool only.

Typical cases#

API#

The public type alias is ToolMiddleware in autogen.beta.middleware. A hook is an async callable with the same parameters as BaseMiddleware.on_tool_execution, except the first argument is the inner ToolExecution (the next step in the chain), not self.

• Pass middleware=[hook, ...] to @tool, Agent.tool, or Toolkit.tool.
• Multiple hooks use the same nesting as agent tool middleware: the first entry in the list is the outermost layer around the tool body.
• If the agent also registers BaseMiddleware with on_tool_execution, agent middleware runs outside tool-scoped hooks (it sees the full execution, including hooks).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

from typing import Annotated

from autogen.beta import Agent, Context, tool, Variable
from autogen.beta.config import OpenAIConfig
from autogen.beta.events import ToolCallEvent, ToolResultEvent
from autogen.beta.middleware import ToolExecution

async def add_request_id(
    call_next: ToolExecution,
    event: ToolCallEvent,
    context: Context,
) -> ToolResultEvent:
    context.variables.setdefault("request_id", "unknown")
    return await call_next(event, context)

@tool(middleware=[add_request_id])
def search(query: str, request_id: Annotated[str, Variable()]) -> str:
    """Runs a search. request_id may be injected by middleware."""
    return f"results-for-{query}-{request_id}"

agent = Agent("assistant", config=OpenAIConfig("gpt-4o-mini"))