Os controles de gateway de agente de IA são as regras operacionais que decidem o que um agente pode chamar, quanto pode gastar, quais evidências devem ser registradas e quando a execução deve pausar, recorrer a um fallback ou parar. Sem esses controles, um gateway de agente se torna uma maneira mais rápida de ocultar a proliferação de ferramentas, o gasto descontrolado de tokens e falhas de produção pouco claras.
O objetivo não é envolver cada agente em processos. O objetivo é tornar o comportamento do agente inspecionável antes que ele chegue aos usuários de produção. Um agente de suporte que pode consultar pedidos, um agente de codificação que pode editar arquivos e um agente financeiro que pode comparar faturas não devem compartilhar o mesmo acesso a ferramentas, orçamento, registro de logs ou política de parada.
Use este guia para projetar controles de gateway de agente de IA como políticas, campos de evidência e testes de aceitação. Em seguida, valide o modelo, o roteamento, o uso e as evidências de faturamento atuais do Flatkey nos preços do Flatkey antes da implementação.
Os controles de gateway de agente de IA começam com um limite de política
Um gateway de agente fica entre os runtimes do agente, as APIs do modelo, as ferramentas internas e a revisão financeira. Isso o torna um bom lugar para padronizar quatro decisões:
| Área de controle | Pergunta do gateway | Evidência de produção |
|---|---|---|
| Uso de ferramentas | Quais ferramentas este fluxo de trabalho pode chamar, com quais argumentos e sob a aprovação de quem? | Nome da ferramenta, versão do esquema, argumentos, estado de aprovação, status do resultado |
| Orçamentos | Quanto gasto é permitido com entrada, saída, raciocínio, ferramenta, nova tentativa e fallback? | Contagem de tokens, custo da solicitação, chave do proprietário, resultado do orçamento, gasto com fallback |
| Logs | O que aconteceu, qual rota atendeu e o que pode ser revisado posteriormente? | ID da solicitação, fluxo de trabalho, modelo, rota, chamadas de ferramenta, motivo da parada, código de erro |
| Condições de parada | Quando a execução deve terminar, tentar novamente, pedir aprovação, recorrer a um fallback ou falhar de forma segura? | Condição de parada, motivo do fallback, decisão do revisor, estado final |
Esses controles de gateway de agente de IA devem ser revisados como uma política de infraestrutura, não como o texto de um prompt. O prompt pode explicar a intenção, mas a política do gateway deve impor o que acontece quando o modelo solicita uma ferramenta sensível, excede um orçamento, recebe um resultado de ferramenta inesperado ou entra em loop.
Controles de uso de ferramentas: permita menos ferramentas do que o agente conhece
A chamada de ferramentas é poderosa porque conecta modelos a sistemas reais. É também onde um agente passa da sugestão para a ação. A documentação de chamada de função da OpenAI descreve as chamadas de ferramentas como um fluxo de várias etapas: o modelo solicita uma ferramenta, sua aplicação a executa e a saída da ferramenta é retornada ao modelo. A documentação de uso de ferramentas da Anthropic descreve de forma semelhante o Claude retornando blocos tool_use, com o código da aplicação sendo responsável pela execução. A chamada de função do Google Gemini também depende de funções declaradas e chamadas de função geradas pelo modelo.
Esse padrão comum é importante para os controles de gateway de agente de IA: o modelo não deve executar a ferramenta diretamente. Seu gateway ou runtime deve decidir se a ferramenta solicitada é permitida, se os argumentos correspondem à política, se a aprovação é necessária e se o resultado da ferramenta é seguro para ser enviado de volta.
Use uma política de ferramentas de três camadas:
- Catálogo de ferramentas: o conjunto completo de ferramentas que existem na organização.
- Lista de permissões do fluxo de trabalho: o conjunto menor de ferramentas que uma rota de agente específica pode chamar.
- Restrição no nível da interação: as ferramentas disponíveis para esta solicitação após verificações de função, locatário, ambiente, orçamento e risco.
Por exemplo, um agente de suporte ao cliente pode ter acesso a lookup_order, search_policy e open_ticket no modo normal. Ele não deve receber issue_refund, cancel_contract ou delete_account até que o fluxo de trabalho atinja um caminho de escalonamento aprovado.
O controle deve ser explícito:
workflow: support_resolution_agent
tool_policy:
default_mode: deny
allowed_tools:
- lookup_order
- search_policy
- open_ticket
approval_required:
- issue_refund
- cancel_subscription
blocked_tools:
- export_customer_database
schema_rules:
require_strict_arguments: true
reject_unknown_fields: true
log_redacted_arguments: true
on_violation:
action: stop
user_message: ask_for_human_reviewO guia de chamada de função da OpenAI recomenda descrições de função claras, esquemas JSON, modo estrito onde for compatível e manter o número de funções inicialmente disponíveis pequeno. Isso não é apenas um conselho de desempenho do modelo. É também um controle de gateway de agente: menos ferramentas expostas significam menos estados inválidos para revisar após um incidente.
Controles de orçamento: limite a execução inteira, não apenas uma chamada de modelo
O custo do agente raramente vem de uma única solicitação limpa. Ele vem de esquemas de ferramentas, histórico de conversas, contexto de recuperação, tokens de raciocínio, resultados de ferramentas, novas tentativas, modelos de fallback e tentativas repetidas após falhas parciais.
Os controles de gateway de agente de IA para orçamento devem cobrir toda a execução:
| Superfície de orçamento | O que limitar | Por que é importante |
|---|---|---|
| Orçamento da solicitação | tokens de entrada, tokens de saída, tokens de raciocínio, máximo de chamadas de modelo | Evita que um único turno se torne um evento de gasto inesperado |
| Orçamento da ferramenta | número de chamadas de ferramenta, tamanho do resultado da ferramenta, gasto com API externa | Evita loops de ferramentas e extrações de dados dispendiosas |
| Orçamento de nova tentativa | contagem de novas tentativas, códigos de status que permitem nova tentativa, janela de backoff | Separa a resiliência da repetição descontrolada |
| Orçamento de fallback | contagem de modelos de fallback, teto de custo de fallback, motivo do fallback | Impede que a confiabilidade mascare uma rota principal defeituosa |
| Orçamento do proprietário | limite de projeto, equipe, cliente, ambiente, chave ou fluxo de trabalho | Torna os gastos revisáveis pelas equipes de finanças e engenharia |
O gateway deve falhar de forma segura (fail-closed) quando um limite rígido é excedido. Ele pode resumir, solicitar a redução do escopo, enfileirar uma revisão humana ou retornar um erro controlado. Ele não deve enviar silenciosamente um prompt maior, mudar para uma rota mais cara ou continuar tentando novamente.
Use esta forma de orçamento:
budget_policy:
workflow: invoice_reconciliation_agent
owner_key: finance_ops
per_request:
max_input_tokens: 32000
max_output_tokens: 4000
max_model_calls: 4
max_tool_calls: 5
per_session:
max_total_tokens: 90000
max_total_cost_usd: reviewed_threshold
retry:
max_attempts: 2
retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
fallback:
max_fallbacks: 1
require_reason: true
on_over_budget:
action: stop_or_request_scope_reductionÉ aqui que a superfície pública do produto da Flatkey se torna relevante. A página inicial atual da Flatkey posiciona a plataforma em torno do acesso unificado a modelos, roteamento, faturamento, análise de uso e controles operacionais. A página de preços atual descreve recargas pré-pagas, análise de uso, controles de custo, logs de solicitação, uma única fatura para todos os provedores e caminhos de aquisição para equipes. Trate isso como evidência de planejamento público atual e, em seguida, execute sua própria prova no painel antes da produção.
Logs: registre evidências, não apenas prompts brutos
Os logs do agente precisam responder a duas perguntas: o que aconteceu em tempo de execução e quem pode provar que a política funcionou?
A documentação de observabilidade do AI Gateway da Vercel descreve logs de gateway para gastos, uso de modelos, métricas de observabilidade, resumos de solicitações, chaves de API e logs de solicitações. A documentação de observabilidade do SDK de Agentes da OpenAI descreve rastreamentos que podem incluir chamadas de modelo, chamadas de ferramenta, transferências, guardrails e spans personalizados. Esses exemplos apontam para o mesmo requisito operacional: os gateways de agente precisam de logs que conectem o comportamento do modelo às decisões de rota, ferramenta, orçamento e parada.
Para controles de gateway de agente de IA, registre no mínimo estes campos:
| Campo | Exemplo | Por que é importante |
|---|---|---|
request_id | UUID gerado pelo gateway | Une registros de modelo, ferramenta, faturamento e suporte |
workflow_class | support_agent, code_agent, finance_agent | Agrupa políticas e testes de aceitação |
owner_key | equipe, aplicativo, cliente, ambiente | Suporta alocação de gastos e revisão de abusos |
requested_model | alias do modelo ou nome da rota | Mostra o que o aplicativo solicitou |
served_model | provedor/modelo real | Mostra o que o gateway serviu |
tool_calls | nome, versão do esquema, argumentos redigidos, status | Comprova o comportamento da política da ferramenta |
usage | entrada, saída, raciocínio, cache, tokens totais | Conecta o comportamento ao custo |
budget_result | permitido, avisado, bloqueado | Comprova que o portão de custo foi executado |
stop_condition | concluído, max_steps, over_budget, approval_required | Explica como a execução terminou |
fallback_reason | timeout, 429, provider_error, quality_gate | Separa a recuperação do desvio (drift) |
Não registre tudo para sempre só porque é fácil. Dados de clientes, prompts, resultados de ferramentas e arquivos podem conter informações sensíveis. Um design de log durável deve definir redação, retenção, revisão de acesso, necessidades de exportação e procedimentos de incidentes. O gateway deve armazenar evidências suficientes para depurar e reconciliar o uso sem transformar cada solicitação em um arquivo de dados descontrolado.
Condições de parada: defina o fim da execução antes que o modelo comece
Condições de parada não são apenas sequências de parada do modelo. Elas são as regras que encerram a execução de um agente com segurança.
As APIs dos provedores expõem diferentes superfícies de resposta e parada. A API de Mensagens da Anthropic expõe campos stop_reason como uso de ferramenta, fim do turno, máximo de tokens e sequências de parada em sua documentação. A documentação de guardrails do SDK de Agentes da OpenAI enquadra os guardrails e a revisão humana como controles que decidem quando uma execução continua, pausa ou para. Em produção, seu gateway deve normalizar esses estados específicos do provedor para um estado de fluxo de trabalho que sua equipe entenda.
Use uma matriz de parada:
| Condição de parada | Ação do gateway | Comportamento voltado ao usuário | Evidência necessária |
|---|---|---|---|
| Concluído | Retornar resposta final | Resposta normal | modelo final, uso, sem ferramentas não resolvidas |
| Aprovação de ferramenta necessária | Pausar | "Esta ação precisa de revisão" | chamada de ferramenta, argumentos, aprovador, decisão |
| Acima do orçamento | Parar ou solicitar redução de escopo | "Restrinja a solicitação" | campo de orçamento, limite, chave do proprietário |
| Máximo de etapas atingido | Parar | "Não foi possível concluir nesta execução" | contagem de etapas, última ação, sinal de loop |
| Erro da ferramenta | Tentar novamente, usar fallback ou parar | Caminho de falha claro | status da ferramenta, classe de erro, contagem de tentativas |
| Tempo limite do provedor | Tentar novamente ou usar fallback | Resposta degradada, mas controlada | rota, tempo limite, motivo do fallback |
| Violação de política | Parar | Recusar ou encaminhar para um humano | política acionada, amostra editada |
| Baixa confiança ou evidência ausente | Fazer pergunta de acompanhamento ou escalar | "Preciso de mais informações" | campo ausente, resultado da avaliação |
O ponto importante é que todo estado terminal tem um nome. Se os únicos estados forem "sucesso" e "erro", as equipes não conseguem dizer se o agente respeitou a política ou simplesmente parou por acidente.
Um modelo prático de controles de gateway de agente de IA
Use um arquivo de política que engenharia, segurança, finanças e produto possam revisar juntos:
policy_name: ai_agent_gateway_controls_v1
owner:
team: ai_platform
reviewers:
- engineering
- finance
- security
workflow_classes:
support_agent:
route: balanced_text_tool_route
allowed_tools: [lookup_order, search_policy, open_ticket]
approval_tools: [issue_refund, cancel_subscription]
max_tool_calls: 5
max_model_calls: 4
code_agent:
route: code_review_route
allowed_tools: [read_repo, search_repo, propose_patch]
approval_tools: [apply_patch, run_shell_command]
max_tool_calls: 12
max_model_calls: 8
budget_rules:
require_owner_key: true
block_when_owner_budget_exceeded: true
require_fallback_reason: true
log_rules:
capture_request_id: true
capture_requested_and_served_model: true
capture_tool_call_status: true
redact_sensitive_arguments: true
stop_rules:
max_steps: 12
max_retries_per_tool: 1
on_policy_violation: stop
on_approval_required: pause
acceptance_tests:
- blocked_tool_is_not_executed
- over_budget_request_fails_closed
- approval_tool_pauses_run
- fallback_records_reason
- request_log_contains_usage_and_stop_conditionEste arquivo não substitui o código da aplicação. Ele fornece ao código um contrato a ser aplicado e aos revisores um artefato concreto para inspecionar.
Testes de aceitação antes da produção
Execute testes de aceitação para cada classe de fluxo de trabalho antes que o tráfego seja liberado:
- Envie uma solicitação normal e confirme que apenas as ferramentas permitidas são expostas.
- Solicite uma ferramenta bloqueada e confirme que a ferramenta não é executada.
- Solicite uma ferramenta que requer aprovação e confirme que a execução pausa com um estado que pode ser retomado.
- Envie um prompt muito grande e confirme que o gateway para ou solicita uma redução de escopo.
- Acione um erro de ferramenta e confirme que a contagem de tentativas, o motivo do fallback e o estado final são registrados.
- Force um tempo limite do provedor e confirme que o fallback permanece dentro do orçamento de fallback.
- Acione o número máximo de etapas e confirme que a execução não entra em loop.
- Confirme que os logs de solicitação mostram a chave do proprietário, o modelo solicitado, o modelo servido, o uso, o status da ferramenta, o resultado do orçamento e a condição de parada.
- Faça uma amostra da reconciliação financeira dos logs de solicitação para a fatura ou movimentação de saldo pré-pago.
- Execute novamente o mesmo teste após alterar modelos, ferramentas, prompts ou política de rota.
Combine este artigo com os guias da Flatkey sobre arquitetura de gateway de API de IA, arquitetura de gateway de API de LLM, balanceamento de carga e failover de API de IA e design de política de roteamento de modelo. A arquitetura do gateway decide onde os controles residem; os testes de aceitação provam que eles funcionam.
Onde a Flatkey se encaixa
A Flatkey não deve ser o único lugar onde sua política de agente existe. Mantenha a política no código, na configuração ou em um repositório de controle interno. Use a Flatkey como a superfície do gateway onde as equipes podem centralizar o acesso ao modelo, a revisão de rotas, a visibilidade do uso, os logs de solicitação, os controles de custo, o saldo pré-pago e a revisão de faturamento.
Uma implementação prática da Flatkey se parece com isto:
- Escolha um fluxo de trabalho de agente com ferramentas e proprietários conhecidos.
- Defina as ferramentas permitidas, as ferramentas de aprovação, os tetos orçamentários, os campos de log e as condições de parada.
- Verifique o modelo atual e as opções de preço em Preços da Flatkey.
- Execute os testes de aceitação com uma chave de não produção.
- Revise os logs para o modelo solicitado, o modelo servido, o uso, a decisão da rota, o motivo do fallback e a condição de parada.
- Mova apenas o fluxo de trabalho testado para a produção.
- Adicione novas ferramentas e rotas de fallback uma linha de política de cada vez.
Quando a prova for bem-sucedida, obtenha uma chave e mantenha a primeira implementação restrita. Os controles de gateway de agente de IA mais robustos são entediantes em produção: toda chamada de ferramenta tem um motivo, toda decisão de orçamento tem um rastro, toda falha tem uma condição de parada nomeada e todo revisor pode ver o que aconteceu.
FAQ
O que são controles de gateway de agente de IA?
Os controles de gateway de agente de IA são políticas que governam o acesso a ferramentas, orçamentos, logs, comportamento de fallback e condições de parada para fluxos de trabalho de agentes que chamam modelos e ferramentas por meio de um gateway.
Os controles de gateway de agente de IA são o mesmo que o roteamento de modelos?
Não. O roteamento de modelos decide qual modelo ou provedor deve atender a uma solicitação. Os controles de gateway de agente de IA decidem se o agente pode chamar uma ferramenta, gastar mais orçamento, tentar novamente, recorrer a um fallback, pausar para aprovação ou parar.
O que deve ser registrado para o uso de ferramentas do agente?
Registre o ID da solicitação, a classe do fluxo de trabalho, a chave do proprietário, o modelo solicitado, o modelo servido, o nome da ferramenta, a versão do esquema, os argumentos redigidos, o status do resultado, o uso, o resultado do orçamento, o motivo do fallback e a condição de parada.
Ferramentas sensíveis devem estar disponíveis para o modelo o tempo todo?
Não. Mantenha o catálogo completo de ferramentas separado da lista de permissões do fluxo de trabalho. Ferramentas sensíveis devem exigir aprovação, um escopo mais restrito ou uma rota de escalonamento separada.
Como devem ser tratados os estouros de orçamento?
Estouros de orçamento rígidos devem resultar em falha, bloqueando a operação. O gateway pode solicitar a redução do escopo, resumir, enfileirar para revisão ou retornar um erro controlado, mas não deve mudar silenciosamente para uma rota mais cara.
Como o Flatkey ajuda com os controles de gateway de agente de IA?
O Flatkey oferece às equipes uma única superfície de gateway para acesso a modelos, revisão de roteamento, visibilidade de uso, logs de solicitações, controles de custos, saldo pré-pago e revisão de faturamento. Use essa superfície juntamente com política como código (policy-as-code) e testes de aceitação para fluxos de trabalho de agentes de produção.
