Governança de ferramentas de agente por meio de um gateway de API de IA: escopos, aprovações, orçamentos e trilhas de auditoria
Uma arquitetura de referência prática para controlar ferramentas de agente por meio de um gateway de API de IA: registros de ferramentas, chaves com escopo, portas de aprovação, orçamentos por ferramenta, listas de permissões de MCP e trilhas de auditoria de modelos/ferramentas unidas.
O risco do agente não está mais limitado ao prompt do modelo. Um agente de produção pode pesquisar arquivos internos, consultar registros de clientes, ligar para um servidor MCP, executar código, abrir um navegador, enviar e-mail, atualizar um CRM ou acionar um fluxo de trabalho de cobrança. A questão da governança passa a ser: qual usuário, chave, modelo, agente e ferramenta foi autorizado a realizar qual ação, com qual orçamento, trilha de auditoria e caminho de reversão?
Se cada equipe lidar com o acesso a ferramentas dentro de seu próprio código SDK, a política ficará espalhada por variáveis de ambiente, painéis de provedores, middleware de aplicativos e servidores MCP não documentados. Um padrão mais seguro é tratar a execução da ferramenta do agente como um problema de plano de controle e aplicá-la por meio de um gateway de API de IA ou de um wrapper de execução de ferramenta padrão que todo agente deve usar.
Este artigo separa fatos, recomendações e previsões. Os fatos são extraídos de orientações públicas atuais: o LLM Application Top 10 da OWASP inclui riscos como divulgação de informações confidenciais, vulnerabilidades da cadeia de suprimentos e agência excessiva; O perfil de IA generativa do NIST para a estrutura de gerenciamento de riscos de IA enfatiza o mapeamento, a medição e o gerenciamento de riscos de IA generativa; A orientação do agente da OpenAI recomenda avaliar o risco da ferramenta por acesso de leitura/gravação, reversibilidade, permissões e impacto financeiro; e a orientação de autorização do MCP usa conceitos de autorização com escopo definido para recursos e operações confidenciais. As recomendações abaixo são padrões de implementação, não requisitos universais.
O problema do leitor: o acesso ao modelo e o acesso à ferramenta estão sendo confundidos
Em muitos dos primeiros aplicativos LLM, uma chave de API respondia a uma pergunta básica: esse serviço pode chamar um modelo? Os agentes tornam isso muito grosseiro. Uma chave que pode enviar conclusões de bate-papo não deve ser capaz de exportar automaticamente dados de clientes, executar comandos shell, postar no Slack, modificar tickets, navegar em sites arbitrários ou enviar alterações de pagamento.
A camada de governança precisa responder a perguntas mais específicas:
- Qual locatário, espaço de trabalho, usuário, conta de serviço ou cliente revendedor iniciou a execução?
- Qual modelo, modelo de prompt, versão do agente e esquema de ferramenta foram usados?
- A ferramenta solicitada era somente leitura, reversível, irreversível, externa, financeira ou privilegiada?
- O solicitante tinha o escopo necessário?
- A aprovação foi exigida, concedida, negada, expirou ou foi ignorada pela política de emergência?
- Quanto custou a ferramenta, quantas vezes ela foi chamada e qual orçamento cumulativo restou?
- Quais evidências existem para depuração, revisão de conformidade e reversão?
A arquitetura abaixo pressupõe que o gateway já recebe chamadas de modelo. A execução da ferramenta pode então ser roteada pelo mesmo gateway, por um serviço secundário ou por uma biblioteca padrão que reporta ao gateway antes e depois de cada chamada de ferramenta.
Arquitetura de referência: uma camada de governança de ferramentas em nível de gateway
Um sistema prático de governança de agentes tem sete componentes:
- Registro de ferramentas: a lista oficial de ferramentas aprovadas, servidores MCP, funções hospedadas, ferramentas de execução local e APIs internas.
- Identidade e camada de chave: chaves de gateway, usuários, locatários, contas de serviço, equipes e clientes revendedores.
- Mecanismo de escopo: verificações de políticas que decidem se uma chave ou usuário pode invocar um recurso específico da ferramenta.
- Classificador de risco: metadados que descrevem o raio da explosão, a sensibilidade dos dados, a reversibilidade, o impacto externo e a exposição aos custos.
- Fluxo de trabalho de aprovação: aprovação humana ou de sistema para ações de alto risco antes da execução.
- Lista de orçamento e limite de taxa: limites por ferramenta e por agente, não apenas limites de token por modelo.
- Armazenamento de auditoria e rastreamento: registros unidos para chamadas de modelo, chamadas de ferramenta, aprovações, erros e resultados.
A importante decisão de design é tornar o gateway o ponto de decisão política, mesmo que a ferramenta real seja executada em outro lugar. Por exemplo, uma ferramenta de navegador pode ser executada em um trabalhador em área restrita e uma gravação de CRM pode ser executada dentro de um serviço interno. O gateway ainda avalia se a chamada é permitida, registra a decisão, rastreia o custo e retorna uma decisão ou negação de autorização assinada.
Etapa 1: Crie um registro central de ferramentas
Um registro de ferramenta é o inventário que evita que a “capacidade desconhecida do agente” se torne o padrão. Cada ferramenta deve ter um proprietário, um nível de risco e metadados operacionais. Um registro mínimo de registro pode ter esta aparência:
Para servidores MCP, o registro também deve incluir o URL do servidor, as ferramentas anunciadas, a versão do esquema, o método de autorização, a data da última revisão e se as novas ferramentas estão desabilitadas por padrão. O MCP melhora a interoperabilidade, mas a compatibilidade do protocolo não é o mesmo que autorização de produção. Recursos e operações confidenciais ainda precisam de escopos explícitos, verificações de rotas e isolamento de locatários.
Campos de registro recomendados
- Nome da ferramenta, ID canônico, proprietário e contato de plantão.
- Local de execução: ferramenta de provedor hospedado, servidor MCP, API interna, trabalhador de navegador, executor de código, trabalho de fila ou ferramenta SDK local.
- Locatários, equipes, usuários, versões de agente e perfis de modelo permitidos.
- Classificação de dados: públicos, internos, metadados do cliente, conteúdo do cliente, segredos, dados de pagamento, credenciais, dados regulamentados.
- Nível de risco e reversibilidade.
- Escopos obrigatórios e política de aprovação.
- Tempos limite, limites de taxa, número máximo de chamadas por execução, orçamento cumulativo de execução e custo máximo por chamada.
- Modo de registro: carga útil completa proibida, editada, com hash, amostrada ou retida explicitamente.
- Instruções de reversão e caminho de escalonamento.
Etapa 2: separar escopos de modelo dos escopos de ferramentas
Uma chave de gateway de produção deve expressar o que o chamador pode fazer. O acesso ao modelo e o acesso à ferramenta devem ser independentes. Por exemplo:
Isso evita que um chatbot de baixo risco se torne um agente de automação acidental. Ele também oferece suporte a modelos de funções:
- Assistente de desenvolvedor: chat de modelo, pesquisa de documentação, explicação de código, sem ferramentas de gravação de produção.
- Bot de suporte: pesquisa de clientes, criação de tickets, elaboração de respostas, aprovação necessária para envios externos.
- Agente analista: consultas de data warehouse somente leitura com limites de linhas, sem exportações de clientes por padrão.
- Agente administrativo: operações com privilégios restritos, aprovação forte, chaves de curta duração, auditoria completa.
- Agente revendedor de locatários: acesso ao modelo com escopo de locatário, ferramentas com escopo de locatário, tetos orçamentários por cliente.
A recomendação é falhar no fechamento: ferramentas desconhecidas são negadas, escopos ausentes negam a execução, as ferramentas MCP recém-anunciadas ficam inativas até serem aprovadas e as ferramentas locais devem usar o mesmo wrapper de política que as ferramentas hospedadas.
Etapa 3: Classifique as ferramentas por raio de explosão
Nem toda chamada de ferramenta precisa de aprovação humana. A governança deve ser proporcional ao risco. Um modelo de classificação útil é:
Essa classificação deve estar visível na revisão do código e na UI do administrador. As descrições das ferramentas por si só não são suficientes porque os agentes podem tratar as descrições como instruções. O mecanismo de política deve contar com metadados e escopos de registro, e não apenas com nomes de ferramentas em linguagem natural.
Etapa 4: adicionar portas de aprovação para ações de alto risco
A aprovação deve ser direcionada. Se cada chamada de ferramenta exigir uma pessoa, o agente se tornará inutilizável. Se nenhuma chamada de ferramenta exigir aprovação, o sistema poderá conceder agência excessiva.
Um fluxo de aprovação comum:
- O agente solicita uma chamada de ferramenta com argumentos estruturados.
- O gateway avalia identidade, escopo, nível de risco, orçamento e política.
- Se a aprovação for necessária, o gateway retornará um evento de aprovação pendente em vez de executar a ferramenta.
- O aplicativo mostra uma visualização ao usuário ou envia uma notificação operacional para um canal de aprovação.
- O aprovador pode aprovar, negar, editar argumentos se a política permitir ou solicitar esclarecimentos.
- O gateway registra a decisão e executa apenas a versão aprovada.
O payload de aprovação deve mostrar a ação em termos humanos, não apenas em JSON bruto:
A aprovação é mais útil para comunicação externa, ações financeiras, gravações irreversíveis, administração privilegiada e exportações amplas de dados. Geralmente é desnecessário para pesquisas de documentação pública de baixo volume.
Etapa 5: Rastreie orçamentos e limites de taxas por ferramenta
Os orçamentos de tokens não são suficientes. Um modelo barato pode desencadear pesquisas caras, sessões de navegador, execuções de código, chamadas de API de terceiros ou longos loops de ferramentas. O gateway deve rastrear pelo menos quatro contadores:
- Contagem de chamadas por ferramenta: máximo de chamadas por execução, usuário, locatário e janela de tempo.
- Custo por ferramenta: cobranças diretas de terceiros, custo do navegador/tempo de execução, custo de pesquisa ou estimativa de estorno interno.
- Custo cumulativo de execução do agente: tokens de modelo mais custos de ferramentas.
- Profundidade do loop: número máximo de iterações modelo-ferramenta-modelo.
Quando um limite é atingido, o gateway deve evitar uma falha grave silenciosa quando possível. Padrões de degradação mais seguros incluem retornar um resumo do progresso, solicitar aprovação para continuar, diminuir a profundidade de recuperação, colocar um trabalho em segundo plano na fila ou mudar para o modo somente leitura. A negação total ainda é apropriada para ferramentas bloqueadas, escopos ausentes, recursos de MCP desconhecidos e ações perigosas.
Etapa 6: Unir telemetria de modelo e ferramenta em um registro de auditoria
A depuração do agente falha quando os logs do modelo ficam em um local e os logs da ferramenta ficam em outro lugar. O registro de auditoria deve conectar toda a cadeia:
- Locatário, espaço de trabalho, usuário, conta de serviço e chave de gateway.
- ID do agente, versão do agente, versão do modelo de prompt e ID do modelo.
- Nome da ferramenta, versão do registro, URL do servidor ou ambiente de execução e hash do esquema.
- Hash de entrada da ferramenta ou entrada editada, nunca cargas confidenciais brutas por padrão.
- Status de aprovação, identidade do aprovador, carimbo de data/hora da aprovação e hash de argumento aprovado.
- Latência, novas tentativas, erros de provedor, erros de ferramenta, custo de token, custo de ferramenta e resultado final.
- Referência de reversão, se a ação mudou de estado.
A documentação de rastreamento do SDK de agentes da OpenAI inclui rastreamentos para gerações de LLM, chamadas de ferramentas, transferências, proteções e eventos personalizados, que suportam um princípio de observabilidade mais amplo: os rastreamentos de agentes devem incluir a atividade da ferramenta, não apenas o uso de token e a latência. No entanto, um único pipeline do SDK pode não cobrir todas as ferramentas hospedadas, caminhos de execução locais ou APIs internas. A auditoria em nível de gateway ajuda a normalizar registros entre provedores e estruturas.
Privacidade é importante. Logs detalhados melhoram a depuração e a revisão de conformidade, mas a retenção bruta de prompt e carga útil da ferramenta pode criar uma nova responsabilidade de segurança. Edite ou faça hash de entradas que contenham segredos, credenciais, dados de pagamento, dados pessoais ou documentos proprietários. Armazene cargas brutas somente sob política de retenção explícita, controles de acesso e regras de exclusão.
Etapa 7: trate servidores MCP e ferramentas de terceiros como dependências da cadeia de suprimentos
Os servidores MCP e as ferramentas de terceiros devem passar pelo mesmo processo de revisão que as bibliotecas, webhooks e dependências de infraestrutura. Os controles recomendados incluem:
- Mantenha uma lista de permissões de servidores MCP aprovados e origens de ferramentas.
- Fixar versões sempre que possível e registrar hashes de esquema.
- Exigir um proprietário para cada servidor e ferramenta de alto risco.
- Revise os nomes das ferramentas, as descrições, os esquemas e as solicitações de permissão antes de ativá-las.
- Desative as ferramentas recém-adicionadas até serem revisadas.
- Verifique os escopos necessários por rota ou capacidade.
- Separe as credenciais do locatário e evite tokens compartilhados entre clientes.
- Execute ferramentas não confiáveis ou de alto risco em sandboxes com restrições de rede e sistema de arquivos.
O fato de uma ferramenta ser exposta através de um protocolo padrão não a torna segura. A camada de governança ainda precisa de privilégios mínimos, autorização explícita, controle de versão e auditabilidade.
Lista de verificação de implementação
Desenho de políticas
- Defina modelos de funções para usuários de agentes comuns e contas de serviço.
- Crie escopos separados para chamadas de modelo e chamadas de ferramenta.
- Classifique as ferramentas por sensibilidade dos dados, reversibilidade, impacto externo, impacto financeiro e nível de privilégio.
- Defina o comportamento de negação por padrão para ferramentas desconhecidas e escopos ausentes.
- Defina regras de aprovação apenas para ações de alto risco.
Aplicação do gateway
- Exigir que cada agente chame ferramentas por meio do gateway ou de um wrapper de política assinado.
- Verifique o locatário, o usuário, a chave, o agente, o modelo, a ferramenta, o escopo, o orçamento e o status de aprovação antes da execução.
- Aplicar profundidade máxima de chamada de ferramenta e custo cumulativo de execução.
- Registre a versão do registro da ferramenta e o hash do esquema para cada chamada.
- Falha fechada quando o mecanismo de política não consegue tomar uma decisão.
Auditoria e operações
- Junte chamadas de modelo e chamadas de ferramenta em um único rastreamento ou ID de execução de agente.
- Edite ou faça hash de entradas de ferramentas sensíveis por padrão.
- Mantenha as evidências de aprovação com o registro de execução final.
- Exponha análises de custo por ferramenta e limite de taxa aos administradores.
- Documente os proprietários da reversão para ferramentas que mudam de estado.
Compensações esperadas
Consistência versus esforço de integração. A governança em nível de gateway oferece aplicação consistente em modelos, SDKs e equipes. O custo é a adoção: os desenvolvedores devem encaminhar a execução da ferramenta pelo caminho aprovado, em vez de chamar as ferramentas diretamente do código do aplicativo.
Privilégio mínimo versus complexidade de política. Escopos refinados reduzem o raio de explosão, mas exigem modelos, convenções de nomenclatura e limpeza regular. Sem modelos, as equipes podem conceder permissões em excesso para avançar mais rapidamente.
Aprovação versus autonomia. A aprovação humana reduz o risco de ações irreversíveis, mas aumenta a latência. Use aprovações para ferramentas de alto risco, não para todas as pesquisas.
Auditabilidade versus exposição de dados. Logs avançados ajudam na resposta a incidentes e na depuração. O registro de carga bruta pode expor segredos e dados pessoais. Redação, hash, retenção configurável e revisão de acesso não são detalhes opcionais.
Limites rígidos versus conclusão de tarefas. Limites de custo por ferramenta evitam agentes fugitivos. Eles também podem interromper trabalhos legítimos de longa duração. Forneça caminhos de continuação, como aprovação para continuar, filas em segundo plano ou resultados parciais resumidos.
Previsões: para onde esse padrão está indo
Previsão: a governança dos agentes se tornará mais centrada na identidade. As equipes perguntarão com menos frequência “qual modelo foi usado?” e mais frequentemente “qual pessoa ou serviço autenticado permitiu a ação desta ferramenta?”
Previsão: os registros de ferramentas se tornarão tão normais quanto os registros de modelos. À medida que os servidores MCP, as APIs internas e as ferramentas hospedadas se multiplicam, as equipes de produção precisarão de um inventário de recursos permitidos, proprietários, esquemas e níveis de risco.
Previsão: a governança de custos passará de relatórios apenas de token para relatórios em nível de ação. A parte mais cara da execução de um agente pode ser a recuperação, a automação do navegador, a execução de código ou APIs de terceiros, em vez da chamada do modelo em si.
Conclusão acionável
Comece com uma regra: uma chave de modelo não é uma chave de ferramenta. Em seguida, construa para fora. Crie um registro de ferramentas aprovadas, atribua proprietários e níveis de risco, exija escopos explícitos, adicione aprovações apenas quando a ação tiver um raio de ação significativo, aplique orçamentos por ferramenta e junte eventos de modelo e ferramenta em uma trilha de auditoria.
O objetivo não é tornar os agentes impotentes. O objetivo é tornar o seu poder legível, com escopo definido, reversível sempre que possível e responsável. Essa é a base prática para a governança da API da equipe à medida que os agentes passam da resposta às perguntas para a execução das ações.