Saltar para o conteúdo principal
Você tem uma chave que seu agente usa em api.orcarouter.ai, e quer que cada chamada de ferramenta que essa chave faça seja governada — bloqueada, auditada, sanitizada ou retida para aprovação — sem tocar no código do seu agente. Essa é uma configuração do agent firewall em dois passos: crie uma política de firewall uma vez, depois aponte a chave para ela. A partir da próxima chamada, cada ferramenta que a chave emite é verificada contra a política no gateway. Esta página é o caminho de criar-e-vincular. Para o modelo de política completo (superfícies, vereditos, resolução) veja a Visão geral do Firewall; para a gramática de regras veja Regras do Firewall.
Toda a configuração de política e chave acontece no console (ou nas rotas de gerenciamento /api/workspace/firewall/*, que usam sua sessão / token de acesso — não uma chave de relay sk-orca-…). Apenas as chamadas /v1/* do seu agente usam a chave de relay. Criar e vincular uma política é uma ação Developer+.

​
1. Configuração do agent firewall em resumo

Uma política de firewall é um objeto nomeado e com escopo de workspace: uma lista ordenada de regras mais um veredito padrão para tudo que nenhuma regra corresponde. Uma chave opta por uma política através de seu campo firewall_policy_id. Nada mais na sua stack muda.

Crie a política

Nomeie-a, escolha um veredito padrão, adicione regras — ou semeie a partir de um nível de autonomia / preset e edite.

Vincule uma chave

Defina o firewall_policy_id da chave para a política, ou marque a política como padrão do workspace para que toda chave não vinculada a herde.

​
2. Crie uma política no console

  1. Abra Security → Firewall → Policies e escolha New policy.
  2. Nomeie-a (única no workspace) e deixe Enabled ligado.
  3. Escolha um veredito padrão — veja §3.
  4. Adicione regras no editor de regras, ou comece vazio e deixe as Ferramentas descobertas conduzirem a criação a partir do tráfego real depois.
  5. Salve. A política existe mas não governa nada até que uma chave aponte para ela ou você a torne o padrão do workspace.
Não quer criar regras à mão primeiro? Aplique um nível de autonomia (balanced é o início recomendado) — ele materializa linhas reais e editáveis de política e guardrail que você pode então ajustar. Ou inicie uma regra a partir de um preset embutido e edite-a. De qualquer forma você chega ao mesmo lugar: uma política nomeada que você vincula a uma chave.

​
3. Escolha o veredito padrão

O veredito padrão é o que a política faz quando nenhuma regra corresponde a uma chamada de ferramenta. É o piso da sua postura. Ele aceita exatamente três valores:
default_verdictQuando nenhuma regra corresponde…
audit (padrão)Permite a chamada, mas a registra. Observe tudo, bloqueie nada — o lugar seguro para começar.
allowPermite e registra, sem registro de revisão.
denyBloqueia qualquer coisa que uma regra não permita explicitamente — uma postura default-deny que você combina com regras de allow.
deny é default-deny: qualquer chamada de ferramenta que suas regras não permitam explicitamente é bloqueada. Poderoso, mas vai parar chamadas que você esqueceu de adicionar à allowlist. Faça o rollout de uma política default-deny primeiro sob shadow mode e observe o feed de events antes de aplicá-la.
Os vereditos que uma regra pode produzir (allow, audit, deny, sanitize, pending_approval, cap_cost) são cobertos em Vereditos — o veredito padrão é limitado aos três acima.

​
4. Vincule a política a uma chave

Uma chave opta por uma política através de seu firewall_policy_id. No console:
  1. Abra Keys, edite a chave que seu agente usa.
  2. Defina Firewall policy para a política que você criou (isso escreve firewall_policy_id).
  3. Salve. A próxima chamada que essa chave faz é governada.
O vínculo vive na chave, no gateway — seu agente continua enviando o mesmo Authorization: Bearer sk-orca-… e o mesmo corpo de requisição. Não há mudança no código de chamada de ferramenta do seu agente. 
# Your agent's relay call is unchanged. The attached policy is enforced
# at the gateway before any tool call in the response is dispatched.
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "delete the staging table"}],
    "tools": [{"type": "function", "function": {"name": "db.query"}}]
  }'
Se uma regra nega uma chamada de ferramenta na superfície inbound, essa chamada volta como HTTP 400 com o código firewall_blocked, nomeando a ferramenta e o motivo — veja como é um block.

​
5. Resolução: vinculada → padrão do workspace

Para qualquer chamada de ferramenta, o gateway resolve qual política se aplica nesta ordem:
Se o firewall_policy_id da chave chamadora aponta para uma política que existe e está habilitada, essa política se aplica.
Caso contrário, a política is_default habilitada do workspace se aplica (se houver uma definida). No máximo uma política por workspace pode ser o padrão; promover um novo padrão rebaixa o antigo na mesma transação.
Nenhum vínculo e nenhum padrão significa nenhuma política. Com o observe mode ligado, a chamada é permitida e registrada como um gap de cobertura; com ele desligado a chamada é permitida silenciosamente.
Uma política vinculada desabilitada cai de volta para o padrão do workspace — ela não desliga o enforcement. (Isso difere dos guardrails, onde um vínculo desabilitado resolve para nenhum.) Para tirar uma chave do escopo do firewall, desvincule-a (defina firewall_policy_id como 0), não apenas desabilite sua política.
Para tornar uma política o padrão de toda chave não vinculada, edite-a e defina-a como padrão do workspace em vez de vincular chaves uma a uma — veja Gerenciar políticas.

​
6. Verifique que entrou em vigor

Antes de depender dela, confirme que a política dispara da maneira que você espera:
  • Teste-a — a aba sandbox Test faz um dry-run da política contra uma chamada de ferramenta de amostra e retorna o veredito, a regra correspondente e o motivo. Nada é despachado ou persistido. Veja Testar regras.
  • Observe o feed de events — uma vez que a chave receba tráfego ao vivo, Events mostra cada avaliação, filtrável por veredito, superfície, ferramenta e run.
Faça o rollout de qualquer política de enforcement primeiro atrás de shadow mode: ela avalia e registra exatamente como faria em produção, mas rebaixa todo veredito de enforcement para audit e prefixa o motivo com [shadow] would …. Desligue o shadow assim que o feed de events mostrar que ela dispara no que você espera e em nada que você não espera.

​
Para onde ir a seguir

Criar regras

A linguagem de correspondência completa — globs de ferramenta, cláusulas de argumento, listas de egress, sanitizers.

Allow-listing de ferramentas

Combine um veredito padrão deny com regras de allow explícitas.

Gerenciar políticas

Padrões, habilitar/desabilitar, versionamento e revert.

Por que zero trust

Por que governar ações — não apenas texto — importa para agentes.
Para as ameaças que uma política pretende deter, veja chamadas de ferramenta perigosas e agência excessiva.