Saltar para o conteúdo principal
A maneira mais rápida de impedir um agente de fazer algo perigoso é nomear a ferramenta e negá-la. Um veredito deny em um glob de nome de ferramenta é o primitivo de deny-list do agent firewall: uma regra, um glob, veredito deny, vinculado a uma chave — e a partir daí o gateway recusa essa ferramenta em cada chamada, sem mudança no código do seu agente. Esta página cobre o caso de uso de deny-list e a única decisão que ele força: em qual superfície você bloqueia — as ferramentas que você anuncia (inbound) ou as chamadas de ferramenta que o modelo emite (response). Para o vocabulário de correspondência completo e a semântica de veredito, veja Schema de regra e Vereditos.

​
1. Bloquear uma chamada de ferramenta que um agente de IA faz

Uma regra de deny-list é a coisa mais simples que uma política de firewall pode expressar: corresponda a uma ferramenta por nome, retorne deny. Use-a quando uma ferramenta nunca deve disparar para uma dada chave — shell.exec, *.delete, um plugin da comunidade em que você não confia — independentemente dos argumentos. No console do seu workspace, abra uma política (ou crie uma) e adicione uma regra: 
{
  "label": "block destructive shell",
  "tool_name_glob": "*.exec",
  "verdict": "deny"
}
O tool_name_glob é um glob pequeno e case-sensitive — shell.* captura uma família inteira, *.delete captura um verbo através de servidores, * captura tudo. Nenhuma cláusula de argumento é necessária: um glob puro + deny bloqueia a ferramenta incondicionalmente. Adicione uma cláusula de argumento apenas quando quiser permitir a ferramenta em geral mas negar uma forma de chamada.
O motor percorre as regras de uma política em ordem de prioridade e a primeira correspondência vence. Coloque exceções de allow estreitas em um número de priority menor (elas rodam primeiro) e seu deny amplo abaixo delas — ex.: permita shell.exec de uma skill builtin.* confiável, negue-a em todo o resto. Veja Prioridade de regra.

​
2. Inbound vs response: escolha a superfície

Um deny pode aterrissar em dois pontos diferentes do ciclo de vida da requisição, e a diferença importa. Fixe a regra com o campo stage, ou deixe-o vazio para cobrir ambos.

inbound

As ferramentas que seu agente anuncia ao modelo na requisição (as definições de ferramenta). Um deny aqui remove a ferramenta antes que o modelo sequer possa escolhê-la — o modelo nunca a vê como opção.

response

Os tool_calls que o modelo emite em sua resposta. Um deny aqui captura a chamada que o modelo já decidiu fazer, antes que ela chegue à ferramenta.
Prefira inbound quando quiser que uma ferramenta seja invisível — o modelo não pode chamar o que nunca lhe foi oferecido, então você evita turnos desperdiçados onde ele escolhe uma ferramenta só para ser recusado. Use response (ou deixe stage vazio) quando a ferramenta legitimamente aparece em algumas requisições e você quer capturar a chamada emitida real, ou quando você só controla o loop do agente e não o conjunto de ferramentas anunciado.
Uma regra sem stage se aplica a todas as superfícies — o mesmo deny cobre uma ferramenta independentemente de ela ser anunciada, emitida ou despachada através de MCP. Esse é o padrão de cinto-e-suspensórios; fixe uma superfície apenas quando um deny deva ter escopo para uma. Veja Stages.

​
3. Vincule a política e veja-a disparar

Uma política não faz nada até que uma chave resolva para ela. Vincule no console definindo firewall_policy_id na chave, ou torne a política o padrão do workspace. A resolução é: a política vinculada da chave (quando ela existe e está habilitada), senão o padrão do workspace. (Uma política vinculada desabilitada cai de volta para o padrão — veja Gerenciar políticas.) Uma vez vinculada, uma chamada negada na superfície inbound retorna HTTP 400 com o código de erro firewall_blocked e um motivo nomeando a ferramenta — ex.: tool "shell.exec" blocked by firewall. O erro é marcado como skip-retry (reexecutar a chamada idêntica apenas bloquearia de novo) e não custa tokens de modelo, já que um block inbound dispara antes da chamada upstream. Um deny despachado através do gateway MCP aparece como um erro de ferramenta em vez disso, de modo que o modelo vê a rejeição e pode reagir.
Um deny na superfície inbound remove a ferramenta do que é oferecido ao modelo. Se o framework do seu agente exige que uma ferramenta que ele anunciou seja chamável, bloqueá-la inbound pode confundir o loop — nesse caso bloqueie em response em vez disso, de modo que a ferramenta permaneça anunciada mas a chamada real seja recusada. Teste a diferença antes de fazer o rollout (veja §5).

​
4. Deny é um entre vários vereditos

Deny é a ferramenta mais contundente na deny-list. Quando um block rígido é demais, o mesmo glob pode carregar um veredito mais suave:
VereditoQuando usar em vez de deny
auditVocê quer ver a ferramenta disparar mas não bloqueá-la ainda.
sanitizeA ferramenta está ok mas seus argumentos podem carregar segredos/PII — redige args, nunca resultados de ferramenta.
pending_approvalUm humano deve aprovar cada chamada fora de banda.
cap_costPermite até o gasto de uma run de agente cruzar um limite em centavos.
Todos esses estão documentados em Vereditos. Uma deny-list é apenas o subconjunto onde o veredito é deny. Para uma postura de allow-list (negar tudo, permitir um conjunto nomeado) alterne o default_verdict da política para deny e adicione regras de allow estreitas — veja Allow-listing de ferramentas.

​
5. Faça o rollout com segurança

A aba Test do console faz dry-run de uma política contra uma chamada de ferramenta de amostra e retorna o veredito, a regra correspondente e o motivo — nada é despachado, nada é persistido. Confirme que seu glob corresponde à ferramenta que você pretendia (e apenas essa ferramenta) antes de vincular uma chave. Veja Testar regras.
Ligue o shadow mode na política e cada veredito de enforcement — incluindo seu deny — é rebaixado para audit, motivo prefixado [shadow] would …. Você mede exatamente o que o deny bloquearia contra o tráfego real, depois desliga o shadow para aplicar.
Não tem certeza do nome exato da ferramenta para fazer glob? A visão de Discovered Tools lista cada ferramenta que o workspace viu, marcada covered ou gap. Crie seu deny direto a partir dos nomes que de fato apareceram. Veja Analytics.
Cada avaliação escreve um evento de firewall com o veredito, a superfície, a ferramenta e a regra correspondente. Depois de aplicar, filtre o log de events por veredito deny para ver a regra disparando nas chamadas que você esperava.

​
6. Quem pode fazer o quê

Toda a configuração de deny-list roda no console sob sua sessão (/api/workspace/firewall/*):
AçãoPapel
Ler políticas, presets, ferramentas descobertas, SimulateMember
Dry-run de uma política (Test)Developer+
Criar / editar / deletar regras e políticasDeveloper+
Ler o log de events e agregados de runDeveloper+
Criar ou alterar uma regra de deny é uma escrita Developer+, e o dry-run do Test no console também. Ler uma política e a visão somente-leitura Simulate (“e-se”) são abertas a cada membro.

​
Relacionados

Sintaxe de glob

Exatamente como shell.*, *.exec e *.shell.* correspondem.

Allow-listing de ferramentas

A postura inversa: default-deny, permitir um conjunto nomeado.

Validar argumentos

Negue apenas uma forma de chamada, não a ferramenta inteira.

Chamadas de ferramenta perigosas

A ameaça que uma deny-list endereça.

Vereditos

O que o deny e seus irmãos mais suaves fazem na prática.

Referência do Firewall

A referência completa de regra + correspondência.