Saltar para o conteúdo principal
Você tem uma política que quer colocar na frente da produção. O medo não é a política — é ligá-la e descobrir que ela bloqueia uma ferramenta de que seu agente realmente precisa, ou mascara um campo do qual sua app depende. A correção não é mais teste em um sandbox; é fazer o rollout contra tráfego real em uma postura que não pode quebrar nada, depois apertar só depois de ter visto o que dispara. Esta receita é esse rollout: observe → shadow → enforce, com autonomia balanced antes de tight. Você fica no console (ou na API REST) o caminho todo; o agente continua chamando https://api.orcarouter.ai/v1/... exatamente como antes.
Novo no modelo? Leia Modos de enforcement para o que cada postura faz mecanicamente, e a linha de base de Agentes Seguros para o que cada nível de autonomia define. Esta página é a sequência — a ordem em que você vira os interruptores.

​
1. O rollout de segurança de IA em três movimentos

Todo o rollout troca autonomia por segurança em três passos, cada um verificado contra tráfego ao vivo antes do próximo:

Observe

Permita tudo, registre tudo. Chamadas de ferramenta não cobertas caem em Discovered Tools; regras de guardrail flag registram matches sem mudar o tráfego. Você aprende o formato real do seu agente.

Shadow

Uma política real avalia cada chamada, mas todo veredito de enforcement é rebaixado para audit e registrado [shadow] would …. Você vê exatamente o que bloquearia — com nada de fato bloqueado.

Enforce

Shadow off. deny bloqueia, mask redige, pending_approval retém. A autonomia vai de ampla (balanced) para apertada (tight), e seu agente está governado.
A disciplina é o ponto: você nunca aplica enforcement de uma regra que não tenha primeiro observado disparar em shadow contra o seu próprio tráfego.

​
2. Movimento um — observe (autonomia = permissive)

Comece o mais amplo possível. Aplique o nível de autonomia permissive a partir de Firewall → Posture (Developer+) — ou POST /api/workspace/firewall/autonomy. Ele habilita o observe mode do workspace e não deixa nenhuma política de enforcement, então cada chamada é permitida e cada chamada não coberta é registrada como um gap de cobertura. 
# Console: Firewall → Posture → apply "permissive"
# or, via the REST API on your session token:
curl https://api.orcarouter.ai/api/workspace/firewall/autonomy \
  -H "Authorization: Bearer <your console access token>" \
  -H "X-Workspace-Id: <workspace>" \
  -H "Content-Type: application/json" \
  -d '{"level": "permissive"}'
As rotas /api/workspace/firewall/* rodam no seu token de sessão / acesso de console, não em uma chave de relay sk-orca-.... Aplicar um nível de autonomia é uma escrita de workspace — Developer+. Apenas chamadas de modelo /v1/* usam a chave de relay.
Agora aponte tráfego real para ele e deixe rodar. Observe dois feeds:
  • Firewall → Discovered Tools (Member) — cada ferramenta que seu agente chama, marcada covered ou gap. Esta é a entrada para suas regras: você está prestes a escrever política para tráfego que de fato acontece, não hipóteses.
  • Guardrails → Matches (Member) — se você adicionou alguma regra de ação flag, cada match que elas registram, sem tocar na requisição.
Deixe rodar até Discovered Tools parar de exibir novas ferramentas. Essa lista estável é a sua spec de criação de regras.

​
3. Movimento dois — shadow (uma política real, zero bloqueio)

Agora crie a política que você realmente quer — globs de ferramenta, cláusulas de argumento, listas de egress, um teto cap_cost — e ligue o shadow_mode antes de vinculá-la. (Construa regras a partir de regras de firewall; o modelo de política completo está na referência de Firewall.) 
{
  "name": "prod-rollout",
  "enabled": true,
  "shadow_mode": true,
  "default_verdict": "audit",
  "rules": [
    { "priority": 10, "tool_name_glob": "shell.exec", "verdict": "deny" },
    { "priority": 20, "tool_name_glob": "*",          "verdict": "cap_cost", "cap_cost_cents": 1000 }
  ]
}
Com shadow_mode: true, aquele deny e aquele cap_cost são ambos rebaixados para audit no momento da avaliação — o motor computa o veredito real, registra-o prefixado [shadow] would … e deixa a chamada passar. Vincule a política às chaves que você está lançando (defina firewall_policy_id na chave) ou faça dela o padrão do workspace. Depois leia Firewall → Events / Runs (Developer+) filtrado pelo prefixo [shadow] e confirme ambos os lados:
Cada chamada shell.exec mostra [shadow] would deny. Cada run que cruza seu limite mostra [shadow] would cap_cost. A política vê o tráfego para o qual você a construiu.
Nenhuma ferramenta legítima aparece com um veredito de would-block. Esta é a verificação de falso positivo — a razão de o shadow existir. Se uma ferramenta de que você precisa é sinalizada, corrija a regra e observe de novo antes de sequer aplicar enforcement.
Guardrails não têm shadow em nível de política. O equivalente é a ação flag por regra: ela registra uma match no feed de Matches e não muda nada, então você pode medir uma regra de conteúdo antes de trocá-la para block ou mask. Rode suas regras de guardrail como flag através deste mesmo movimento.

​
4. Movimento três — enforce (autonomia balanced, depois tight)

Quando o log de shadow parecer certo, aplique enforcement em dois estágios, não um. Não pule direto para default-deny. Primeiro, balanced. Esta é a primeira postura de enforcement recomendada: o veredito padrão do firewall é audit, mas as ações mais destrutivas (como shell destrutivo) são negadas, e o guardrail PII Shield roda somente audit — ele sinaliza PII sem mascará-la ainda. Você agora está bloqueando a pior coisa enquanto ainda observa o resto. Desligue o shadow_mode na sua própria política no mesmo movimento para que seus vereditos deny / cap_cost entrem ao vivo ao lado da linha de base. 
curl https://api.orcarouter.ai/api/workspace/firewall/autonomy \
  -H "Authorization: Bearer <your console access token>" \
  -H "X-Workspace-Id: <workspace>" \
  -H "Content-Type: application/json" \
  -d '{"level": "balanced"}'
Observe Events por uma hora. Blocks reais agora aparecem sem o prefixo [shadow]. Uma chamada de ferramenta negada retorna HTTP 400 firewall_blocked; ela é skip-retry e custa nenhum token de modelo. Depois, tight. Assim que balanced estiver quieto, vá para default-deny. O nível tight nega por padrão, nega shell destrutivo e egress SSRF, e aplica PII Shield + Secrets Blocker — a PII é mascarada na requisição antes que o modelo a veja, e segredos nas suas requisições são bloqueados. Um prompt bloqueado retorna HTTP 400 guardrail_blocked, custa nenhuma cota e é skip-retry.
EstágioFirewall (ações)Guardrails (texto)O que você está provando
permissiveObserve; nada bloqueadoSó flagFormato de tráfego real
balancedAudit padrão; shell destrutivo negadoPII sinalizadaO pior caso é parado
tightDefault-deny; ferramentas shell + no formato de fetch (SSRF) negadasPII mascarada, segredos bloqueadosZero-trust completo
Ressalva de streaming para PII. Sob tight, o PII Shield mascara PII na requisição antes que o modelo a veja — isso está ao vivo. A máscara do lado de output de uma resposta em streaming ainda não está ao vivo; um block de output é aplicado em streaming (o scanner corta o stream). Se você depende de redigir a saída do modelo, verifique a sua combinação de stage/stream na aba Test do guardrail primeiro. Veja Guardrails.

​
5. A saída de emergência — desfazer em um clique

Toda mudança de autonomia é uma única transação que captura um snapshot da sua postura anterior, então você pode reverter direto a partir de Firewall → Posture (ou POST /api/workspace/firewall/autonomy/undo/:audit_id). Você também pode simplesmente reaplicar um nível mais suave — baixar tight de volta para balanced, ou balanced de volta para permissive — a qualquer momento.
O desfazer restaura a partir do snapshot de auditoria do apply mais recente. Se você fez edições manuais de política desde o apply que está desfazendo, esse snapshot não é mais o último não usado e o desfazer recusa em vez de silenciosamente reverter essas edições. Quando isso acontece, reaplique um nível mais suave — está sempre disponível.

​
6. De onde vêm os vereditos de cada movimento

O rollout nunca bloqueia algo que você não pediu, porque cada postura mapeia para um mecanismo explícito e observável:
PosturaMecanismoResultado
Observefirewall_observe_mode do workspace ligado + flag de guardrailPermitir + registrar gaps / matches
Shadowshadow_mode por políticaVeredito real computado, rebaixado para audit, registrado [shadow] would …
Enforceshadow_mode off + autonomia tight/balanceddeny / mask / cap_cost entram ao vivo
Os quatro termos — observe mode, o veredito audit, a ação flag e shadow_mode — são interruptores distintos, documentados lado a lado em Modos de enforcement.

​
7. Próximos passos

Modos de enforcement

O mapa de mecanismos por trás de observe, shadow e enforce.

Linha de base de Agentes Seguros

O que cada nível de autonomia define, e como simulá-lo primeiro.

Domine um agente autônomo

O próximo passo depois de aplicar enforcement: limites de custo, detecção de anomalias e aprovações.

Agent Firewall

Políticas, regras, vereditos, shadow mode e o gateway MCP por completo.
Um go-live em que você pode confiar é um rollout, não um interruptor. Observe o que seu agente faz, faça shadow da política contra o seu tráfego real, depois aplique enforcement — balanced antes de tight — e cada regra é verificada em produção antes de algum dia bloqueá-la.