Coco
Build agents

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
HookRunsOrder
before_agentOnce, at the start of a runList order
before_modelBefore each model callList order
wrap_model_callAround each model callFirst in the list is outermost
after_modelAfter each model callReverse list order
wrap_tool_callAround each tool callFirst in the list is outermost
after_agentOnce, before the run exitsReverse 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 result

A 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().


On this page