Middleware

Middleware transforms runtime data without changing the core tool contract. Use guardrails or approvals when behavior decides whether a run continues; use middleware when completion or tool data needs to be transformed.

Create middleware

import { createMiddleware } from '@anvia/core'

const hideInternalErrors = createMiddleware({
  onToolOutput({ result }) {
    if (!result.includes('INTERNAL_')) {
      return
    }

    return 'The tool returned an internal service error.'
  },
})

Attach it to an agent

const agent = new Agent({
  id: 'support',
  model: model,
  middlewares: [hideInternalErrors],
})

Agent middleware applies to every run. Run middleware applies only to one call.

const response = await agent.generate({
    prompt: message,
    middlewares: [hideInternalErrors]
})

Choose an interception point

Method	Runs when
onCompletionRequest	Before a provider-neutral request reaches the model.
onCompletionResponse	After the model responds and before the runtime continues.
onToolInput	Before approval and handler execution; the approval prompt shows the middleware-transformed input.
onToolOutput	Before tool output is sent back to the model.

Agent-level middleware runs before run-level middleware.

Keep contracts in the handler

Middleware is useful for instrumentation, normalization, request shaping, large-result spillover, and output filtering. It must not bypass schema validation or replace handler authorization.