Adicionando Middleware

A página anterior mostrou como o conhecimento especializado de domínio reutilizável é embalado em pacotes de habilidades — incluindo instruções, material de referência e scripts — formando unidades autocontidas que qualquer agente pode carregar sob demanda. Mas à medida que você implanta agentes em produção, surge uma nova categoria de problemas: problemas que permeiam todas as interações, independentemente do que o agente faz.

Você precisa registrar todas as solicitações e respostas em log. Você precisa de guardrails que bloqueiam conteúdo prejudicial antes que o modelo o veja. Você precisa impor limites de taxa, capturar exceções normalmente e injetar telemetria , tudo sem tocar na lógica central do agente. Copiar essas questões em cada agente (ou cada ferramenta, ou cada habilidade) não escala e cria pesadelos de manutenção.

O middleware resolve isso. O Middleware permite encapsular o pipeline de execução do agente com comportamentos reutilizáveis que interceptam, inspecionam e modificam solicitações e respostas em pontos bem definidos. Pense no middleware como uma série de camadas concêntricas ao redor do agente – cada camada tem a chance de agir na entrada antes de chegar ao agente e na saída antes de chegar ao chamador.

Quando usar

Adicione middleware ao seu agente quando:

• Você precisa de guardrails para bloquear conteúdo prejudicial, impróprio ou que violem políticas, antes ou depois de ser processado pelo modelo.
• Você deseja registro centralizado de logs ou telemetria para todas as interações dos agentes sem modificar cada agente individualmente.
• Você precisa modificar solicitações ou respostas – enriquecendo prompts, transformando saídas ou substituindo resultados inteiramente – sem alterar a lógica do agente.
• Você deseja impor políticas como limitação de taxa, filtragem de conteúdo ou verificações de autenticação que se aplicam a cada execução.
• Você precisa lidar com exceções de forma consistente – repetindo falhas transitórias, retornando respostas de fallback normalmente ou registrando erros de diagnóstico.
• Você deseja compartilhar o estado em todo o pipeline, por exemplo, acompanhar o tempo de requisição ou acumular métricas de que vários componentes de middleware precisam.

Como funciona o pipeline de middleware

Quando você chama o método de execução do agente, a solicitação não vai diretamente para o modelo. Em vez disso, ele flui por um pipeline de camadas de middleware, cada uma das quais pode inspecionar ou modificar a solicitação, delegar para a próxima camada e, em seguida, inspecionar ou modificar a resposta no caminho de volta.

┌─────────────────────────────────────────────────────────┐
│  Caller: agent.run("What's the weather?")               │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 1 (Logging)                                  │
│  • Logs the incoming request                            │
│  • Calls next middleware                                │
│  • Logs the outgoing response                           │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 2 (Guardrails)                               │
│  • Checks input against content policy                  │
│  • If blocked → returns early with rejection message    │
│  • If allowed → calls next middleware                   │
│  • Checks output against content policy                 │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Agent core (model invocation, tool calls, etc.)        │
└─────────────────────────────────────────────────────────┘

Pontos principais:

1. Cada middleware decide se deseja continuar. Um middleware pode chamar a próxima camada na cadeia para continuar normalmente ou, assim como, pode interromper o pipeline retornando uma resposta diretamente — por exemplo, quando uma barreira de segurança bloqueia uma solicitação.
2. O Middleware enxerga ambas as direções. Um middleware executa o código antes de delegar (para inspecionar ou modificar a entrada) e depois que a resposta retorna (para inspecionar ou modificar a saída). Este é o padrão clássico de "cebola".
3. Várias cadeias de middleware juntas. Quando você registra vários componentes de middleware, eles aninham: o primeiro middleware registrado é a camada mais externa e o último registrado é a camada mais interna mais próxima do agente.

O que o middleware pode fazer

O Agent Framework dá suporte ao middleware em três camadas do pipeline — execução do agente, chamada de função e cliente de chat — fornecendo controle refinado sobre onde você intercepta a execução. Os padrões comuns incluem:

Para obter um passo a passo completo de definição e registro de middleware, consulte Definir Middleware. Para obter a visão geral da arquitetura completa, consulte a Visão geral do Middleware.

Considerações

Próximas Etapas 

Agora que seu agente tem ferramentas, habilidades e middleware, a próxima etapa são os provedores de contexto – componentes que injetam memória, perfis de usuário e conhecimento dinâmico na janela de contexto do agente antes de cada execução.

Vá mais fundo:

• Visão geral do middleware – referência completa para todos os tipos de middleware
• Arquitetura de Pipeline do Agente – como o middleware se integra ao pipeline de execução