Ferramentas são APIs com marketing melhor. Quando um agente de IA consegue chamá-las, todos os assuntos chatos de backend voltam: identidade, escopos, contratos, quotas, idempotência, retries, audit logs, detecção de abuso e modos de falha seguros.
MCP dá aos agentes uma forma estruturada de descobrir e invocar tools. OpenAPI dá contratos legíveis por máquina para APIs HTTP. Webhooks e CloudEvents permitem que sistemas reportem mudanças de estado de forma assíncrona. OAuth dá vocabulário para autorização delegada. A arquitetura interessante não é escolher um deles; é colocá-los atrás de um tool gateway que aplica política sempre que o agente tenta agir.
O modelo não deve virar a camada de autorização. Ele pode propor uma chamada de ferramenta, mas o gateway decide se ela é permitida para este usuário, tenant, tarefa, escopo, nível de risco, janela de tempo e estado atual do sistema.
Um agente pode gerar JSON plausível e ainda perigoso: tenant errado, idempotency key ausente, escopo amplo demais, versão stale de objeto ou ação destrutiva escondida em linguagem amigável. Definições de tools devem ser contratos rígidos. Schemas de entrada, saída, erros, retries, paginação, rate limits e rótulos de side effect precisam ser explícitos.
O padrão mais útil é classificar tools por blast radius. Consultas read-only podem ser mais fáceis. Tools que mutam estado precisam de gates mais fortes. Ações destrutivas ou financeiras precisam de aprovação, revisão dupla ou playbook pré-aprovado.
Agentes tendem a agir como se toda operação acabasse imediatamente. Sistemas reais não funcionam assim. Pagamentos liquidam depois. Jobs de CI demoram. Aprovações humanas pausam. Exportações entram em fila. Dispositivos ficam offline. Webhooks e formatos como CloudEvents tornam a arquitetura assíncrona em vez de fingir que tudo é RPC bloqueante.
O gateway deve emitir eventos como solicitado, aprovado, rejeitado, iniciado, concluído, falhou, expirou e compensado. O agente pode reagir, mas o sistema de registro continua sendo o event log.
| Camada | Controle de engenharia | Por que agentes precisam |
|---|---|---|
| MCP tool | Capacidade pequena, nome claro, schema, exemplos e side-effect label. | Reduz confusão de tools e ações destrutivas acidentais. |
| Contrato OpenAPI | Requests/responses validados, erros, versionamento e docs geradas. | Transforma argumentos gerados em algo que runtime pode rejeitar. |
| Autorização | OAuth scopes, tenants, decisão de política e aprovação step-up. | Impede que o modelo vire o sistema de permissão. |
| Confiabilidade | Idempotency keys, retries, circuit breakers, timeouts e compensações. | Evita pedidos duplicados, emails repetidos e efeitos colaterais em cascata. |
| Webhooks | Eventos assinados, CloudEvents, correlation ids e proteção contra replay. | Permite ações longas sem bloquear o agente. |
| Auditoria | Prompt, tool, argumentos, caller, política, resposta e aprovação humana. | Torna o comportamento do agente reconstruível após incidentes. |
Eu construiria um tool gateway para agentes que importa specs OpenAPI, expõe tools MCP seguras, mapeia cada tool para OAuth scopes, exige idempotência para mutações, assina callbacks webhook e grava cada tool call em um stream de auditoria. Tools de alto risco teriam dry-run e aprovação antes da execução.
O gateway também teria um registry de tools com owner, SLA, blast radius, classes de dados, rate limits, tenants permitidos, falhas de exemplo e playbooks de rollback. Isso transforma "o agente chama APIs" em uma superfície operacional que backend consegue manter.
Tools de agentes não são atalhos ao redor da arquitetura backend. São arquitetura backend exposta a um novo caller. O padrão mais seguro é tornar tools tediosas: tipadas, escopadas, logadas, limitadas por quota, idempotentes, assíncronas quando necessário e explícitas sobre falhas.
Artigo sobre camada de API para agentes de IA cobrindo MCP tools, contratos OpenAPI, webhooks, CloudEvents, OAuth scopes, ferramentas permissionadas, idempotência, callbacks assinados, tool gateways, audit logs e confiabilidade backend para sistemas agentic.