Governança de ferramentas de agente por meio de um gateway de API de IA: escopos, aprovações, orçamentos e trilhas de auditoria

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, chamar 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 à ferramenta dentro de seu próprio código SDK, a política ficará espalhada entre 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 AI API 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 OpenAI recomenda avaliar o risco da ferramenta por acesso de leitura/gravação, reversibilidade, permissões e impacto financeiro; e MCP orientação de autorização usa conceitos de autorização com escopo 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 muitas das primeiras aplicações LLM, uma chave API respondia a uma pergunta básica: este 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 ferramenta em nível de gateway

Um sistema prático de governança de agentes tem sete componentes:

1. Registro de ferramentas: a lista oficial de ferramentas aprovadas, MCP servidores, funções hospedadas, ferramentas de execução local e APIs internas.
2. Identidade e camada de chave: chaves de gateway, usuários, locatários, contas de serviço, equipes e clientes revendedores.
3. Mecanismo de escopo: verificações de política que decidem se uma chave ou usuário pode invocar um recurso de ferramenta específico.
4. 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.
5. Fluxo de trabalho de aprovação: aprovação humana ou de sistema para ações de alto risco antes da execução.
6. Lista de orçamento e limite de taxa: limites por ferramenta e por agente, não apenas limites de token por modelo.
7. 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: criar um registro central de ferramentas

Um registro de ferramenta é o inventário que impede que “capacidade de agente desconhecida” 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:

{
  "tool_id": "crm.create_ticket",
  "display_name": "Create CRM support ticket",
  "owner_team": "support-automation",
  "execution_type": "internal_api",
  "server_url": "https://tools.internal.example/crm",
  "allowed_tenants": ["enterprise", "support"],
  "allowed_models": ["general-large", "general-fast"],
  "risk_tier": "reversible_write",
  "data_classification": "customer_metadata",
  "required_scopes": ["tool:crm.create_ticket"],
  "approval_policy": "not_required_under_100_tickets_per_day",
  "default_timeout_ms": 8000,
  "max_cost_per_call_usd": 0.05,
  "max_calls_per_run": 3,
  "rollback_owner": "support-ops-oncall",
  "retention_policy": "redacted_30_days"
}

Para MCP servidores, 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. MCP melhora a interoperabilidade, mas compatibilidade de 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 rota e isolamento de locatário.

Campos de registro recomendados

• Nome da ferramenta, ID canônico, proprietário e contato de plantão.
• Local de execução: ferramenta do provedor hospedado, MCP servidor, API interno, trabalhador do navegador, executor de código, tarefa de fila ou ferramenta local SDK.
• 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:

model:chat
model:embeddings
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blocked

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 de locatário revendedor: 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, ferramentas recém-anunciadas MCP 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 IU 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:

1. O agente solicita uma chamada de ferramenta com argumentos estruturados.
2. O gateway avalia identidade, escopo, nível de risco, orçamento e política.
3. Se a aprovação for necessária, o gateway retornará um evento de aprovação pendente em vez de executar a ferramenta.
4. O aplicativo mostra uma visualização ao usuário ou envia uma notificação de operações para um canal de aprovação.
5. O aprovador pode aprovar, negar, editar argumentos se a política permitir ou solicitar esclarecimentos.
6. 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 brutos JSON:

{
  "approval_id": "appr_123",
  "agent_run_id": "run_456",
  "requested_by_user": "user_789",
  "tool_id": "email.send",
  "risk_tier": "external_communication",
  "summary": "Send a reply to customer@example.com about ticket #4812",
  "redacted_arguments": {
    "to": "customer@example.com",
    "subject": "Update on ticket #4812",
    "body_hash": "sha256:..."
  },
  "expires_at": "2026-08-09T12:30:00Z"
}

A aprovação é mais útil para comunicação externa, ações financeiras, gravações irreversíveis, administração privilegiada e amplas exportações 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 acionar pesquisas caras, sessões de navegador, execuções de código, chamadas 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, capacidades MCP desconhecidas 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.

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 SDK pode não cobrir todas as ferramentas hospedadas, caminhos de execução locais ou API internos. A auditoria em nível de gateway ajuda a normalizar registros entre provedores e estruturas.

A 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 MCP servidores e ferramentas de terceiros como dependências da cadeia de suprimentos

MCP servidores e ferramentas de terceiros devem passar pelo mesmo processo de revisão que bibliotecas, webhooks e dependências de infraestrutura. Os controles recomendados incluem:

• Mantenha uma lista de permissões de MCP servidores e origens de ferramentas aprovados.
• Fixar versões sempre que possível e registrar hashes de esquema.
• Exige um proprietário para cada servidor e ferramenta de alto risco.
• Revise nomes de ferramentas, descrições, esquemas e 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 por meio 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

Elaboração 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 de execução cumulativo.
• 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 rastreamento ou ID de execução de agente.
• Redigir ou usar hash nas entradas da ferramenta 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 proprietários de 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. Registros 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 esta ação da ferramenta?”

Predição: os registros de ferramentas se tornarão tão normais quanto os registros de modelos. À medida que MCP servidores, APIs internas e 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 equipe API à medida que os agentes passam da resposta a perguntas para a tomada de ações.

Leitura relacionada

• práticas de rotação e isolamento de chaves da equipe API
• traços de união, registros de token e prompt seguro registro
• saídas estruturadas e padrões de validação de chamada de ferramenta