Middleware
See the order create_agent runs middleware hooks in, deny a tool call, and write middleware with decorators or by subclassing AgentMiddleware.
See the order hooks run in, deny a tool call, and write your own middleware.
Middleware wraps every stage of the agent loop, from the prompt and the model call to each tool call. CocoGuard from the Coco SDK is a middleware on wrap_tool_call, so this page is also how the guard sees each call.
Prerequisites: The framework, installed as in the Quickstart, with OPENAI_API_KEY set.
The order hooks run in
With middleware=[m1, m2], create_agent runs the hooks in this order:
Agent entry
├── m1.before_agent(state, runtime)
└── m2.before_agent(state, runtime)
│
▼
┌───► Agent turn loop ────────────────────────────────────────────┐
│ ├── m1.before_model(state, runtime) │
│ └── m2.before_model(state, runtime) │
│ │ │
│ ▼ │
│ ┌── m1.wrap_model_call(request, handler) [outermost] │
│ │ └── m2.wrap_model_call(request, handler) [innermost] │
│ │ └── the chat model │
│ │ │
│ ▼ │
│ ├── m2.after_model(state, runtime) [reverse order] │
│ └── m1.after_model(state, runtime) │
│ │ │
│ ▼ (if the AIMessage has tool_calls) │
│ ┌── ToolNode (parallel per tool call) ───────────────────── │
│ │ └── m1.wrap_tool_call(request, handler) [outermost] │
│ │ └── m2.wrap_tool_call(request, handler) [innermost] │
│ │ └── the tool │
└───────────┘ (loops back to before_model)
│
▼ (when no tool calls remain)
├── m2.after_agent(state, runtime) [reverse order]
└── m1.after_agent(state, runtime)
Agent exit| Hook | Runs | Order |
|---|---|---|
before_agent | Once, at the start of a run | List order |
before_model | Before each model call | List order |
wrap_model_call | Around each model call | First in the list is outermost |
after_model | After each model call | Reverse list order |
wrap_tool_call | Around each tool call | First in the list is outermost |
after_agent | Once, before the run exits | Reverse list order |
Each hook has an async version with an a prefix, such as awrap_tool_call.
Deny a tool call
A wrap_tool_call hook which returns a ToolMessage without calling handler stops the tool from running, and the model receives the message instead:
from coco.agents import create_agent
from coco.agents.middleware import wrap_tool_call
from coco_core.messages import ToolMessage
from coco_core.tools import tool
@tool
def transfer_funds(from_account: str, to_account: str, amount: float) -> str:
"""Transfer funds between two accounts."""
return f"Transferred ${amount:.2f} from {from_account} to {to_account}."
@wrap_tool_call
def enforce_transfer_limit(request, handler):
if request.tool_call["name"] == "transfer_funds":
amount = request.tool_call["args"].get("amount", 0)
if amount > 10_000:
return ToolMessage(
content="Policy denial: transfers over $10,000 require manual approval.",
tool_call_id=request.tool_call["id"],
name=request.tool_call["name"],
status="error",
)
return handler(request)
agent = create_agent(
model="openai:gpt-4o",
tools=[transfer_funds],
middleware=[enforce_transfer_limit],
)A transfer over 10,000 never runs, and the model reads Policy denial: transfers over $10,000 require manual approval.
Good to know: CocoGuard denies a call the same way, with content starting Coco denied this action. See Where Coco attaches.
Write middleware with decorators
Decorators suit a policy that needs one hook:
from coco.agents import create_agent
from coco.agents.middleware import (
before_model,
dynamic_prompt,
wrap_model_call,
wrap_tool_call,
)
from coco_core.messages import SystemMessage, ToolMessage
@dynamic_prompt
def inject_tenant_prompt(request):
tenant = request.state.get("messages", [])
return SystemMessage(content=f"You are an assistant. Current message count: {len(tenant)}.")
@wrap_model_call
def audit_model_request(request, handler):
# Override model settings immutably before calling the handler
updated_request = request.override(
model_settings={**request.model_settings, "temperature": 0.0}
)
response = handler(updated_request)
return response
@wrap_tool_call
def guard_tool_call(request, handler):
tool_name = request.tool_call["name"]
tool_args = request.tool_call["args"]
if tool_name == "execute_sql" and "DROP " in tool_args.get("query", "").upper():
return ToolMessage(
content="Blocked: destructive DDL statements are prohibited by policy.",
tool_call_id=request.tool_call["id"],
name=tool_name,
status="error",
)
return handler(request)@before_agent, @before_model, @after_model and @after_agent turn a (state, runtime) function into that hook. Pass the decorated functions in middleware=[...].
Write middleware as a class
Subclass AgentMiddleware to combine hooks, add fields to the agent's state, or supply tools:
from typing import Any
from typing_extensions import NotRequired
from coco.agents.middleware import (
AgentMiddleware,
AgentState,
ModelRequest,
ModelResponse,
ToolCallRequest,
hook_config,
)
from coco_core.messages import AIMessage, ToolMessage
from coco_graph.runtime import Runtime
from coco_graph.types import Command
class CustomMetricsState(AgentState):
tool_invocations: NotRequired[int]
class GovernanceMiddleware(AgentMiddleware[CustomMetricsState, Any, Any]):
state_schema = CustomMetricsState
def before_agent(self, state: CustomMetricsState, runtime: Runtime[Any]) -> dict[str, Any] | None:
return {"tool_invocations": state.get("tool_invocations", 0)}
@hook_config(can_jump_to=["end"])
def before_model(self, state: CustomMetricsState, runtime: Runtime[Any]) -> dict[str, Any] | None:
if state.get("tool_invocations", 0) >= 20:
return {
"messages": [AIMessage(content="Tool call budget exhausted for this session.")],
"jump_to": "end",
}
return None
def wrap_tool_call(
self,
request: ToolCallRequest,
handler,
) -> ToolMessage | Command[Any]:
result = handler(request)
return result
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler,
) -> ToolMessage | Command[Any]:
result = await handler(request)
return resultA hook marked @hook_config(can_jump_to=[...]) can return "jump_to" set to "model", "tools" or "end" to change where the loop goes next.
Keep in mind: A middleware with only awrap_tool_call fails under the synchronous agent.invoke() with NotImplementedError. Implement wrap_tool_call too, as above, or call agent.ainvoke().
Related Resources
Human in the loop
Pause a tool call with interrupt() until a person decides, inspect the pending request, resume with Command, and use HumanInTheLoopMiddleware.
Built-in middleware
Add call limits, retries and fallbacks, PII redaction, summarization, context editing, and trace scrubbing from coco.agents.middleware.