Adicionando Middleware

A página anterior mostrou como as competências empacotam conhecimentos de domínio reutilizáveis — instruções, material de referência e scripts — em unidades autónomas que qualquer agente pode carregar a pedido. Mas, à medida que se implementam agentes em produção, surge uma nova categoria de problemas: problemas que atravessam todas as interações independentemente do que o agente faça.

Tens de registar todos os pedidos e respostas. Precisas de guardas que bloqueiem conteúdos prejudiciais antes que o modelo o veja. Precisa de impor limites de taxa, detetar exceções com elegância e injetar telemetria — tudo isto sem tocar na lógica central do agente. Copiar e colar estas preocupações em todos os agentes (ou em todas as ferramentas, ou em todas as competências) não é sustentável e cria problemas sérios de manutenção.

Middleware resolve isto. O middleware permite-lhe envolver o pipeline de execução do agente com comportamentos reutilizáveis que intercetam, inspecionam e modificam pedidos e respostas em pontos bem definidos. Pense no middleware como uma série de camadas concêntricas em torno do agente — cada camada tem a oportunidade de agir sobre a entrada antes de chegar ao agente, e sobre a saída antes de chegar ao chamador.

Quando utilizar isto

Adicione middleware ao seu agente quando:

• É preciso mecanismos de proteção para bloquear conteúdos prejudiciais, fora do tópico ou que violem políticas antes ou depois de o modelo o processar.
• Quer registo centralizado ou telemetria para todas as interações com agentes sem modificar cada agente individualmente.
• É necessário modificar pedidos ou respostas — enriquecendo prompts, transformando resultados ou substituindo resultados por completo — sem alterar a lógica do agente.
• Queres impor políticas como limitação de taxas, filtragem de conteúdo ou verificações de autenticação que se aplicam a todas as execuções.
• É necessário gerir exceções de forma consistente — tentar novamente em falhas transitórias, devolver respostas alternativas eficientes, ou registrar erros para diagnósticos.
• Querer partilhar o estado ao longo da cadeia de processamento — por exemplo, acompanhar o tempo de execução dos pedidos ou acumular métricas que vários componentes de middleware necessitam.

Como funciona o pipeline de middleware

Quando chamas o método run do teu agente, o pedido não vai diretamente para o modelo. Em vez disso, flui através de um pipeline de camadas de middleware, cada uma das quais pode inspecionar ou modificar o pedido, delegar à camada seguinte e depois inspecionar ou modificar a resposta no regresso.

┌─────────────────────────────────────────────────────────┐
│  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 continua ou não. Um middleware pode chamar a camada seguinte da cadeia para proceder normalmente, ou pode curto-circuitar o pipeline ao devolver uma resposta diretamente — por exemplo, quando um guardrail bloqueia um pedido.
2. O middleware observa ambos os sentidos. Um middleware executa código antes de delegar (para inspecionar ou modificar a entrada) e depois de a resposta regressar (para inspecionar ou modificar a saída). Este é o padrão clássico da "cebola".
3. Vários middlewares são encadeados juntos. Quando registas vários componentes de middleware, eles aninham-se: o primeiro middleware registado é a camada mais externa, e o último registado é a camada mais interna, mais próxima do agente.

O que o middleware pode fazer

O Agent Framework suporta middleware em três camadas do pipeline — execução do agente, chamada de funções e cliente de chat — dando-lhe controlo detalhado sobre onde interceta a execução. Os padrões comuns incluem:

Para uma explicação completa da definição e registo de middleware, veja Definição de Middleware. Para uma visão geral completa da arquitetura, consulte a Visão Geral do Middleware.

Considerações

Passos seguintes

Agora que o seu agente tem ferramentas, competências e middleware, o próximo passo são os fornecedores de contexto — componentes que injetam memória, perfis de utilizador e conhecimento dinâmico na janela de contexto do agente antes de cada execução.

Vai mais fundo:

• Visão Geral do Middleware — referência completa para todos os tipos de middleware
• Arquitetura do Pipeline de Agentes — como o middleware se integra no pipeline de execução