1. Camada 1 — Chave de API com escopo
A chave é o primeiro portão. Antes que qualquer conteúdo seja inspecionado ou qualquer modelo seja chamado, o gateway resolve a chave chamadora e decide se a requisição é sequer permitida. O que a chave carrega:model_limits— o conjunto de modelos que a chave pode chamar. Uma requisição para um modelo fora da lista é rejeitada imediatamente.allow_ips— lista de permissão de IPs opcional. Uma requisição de uma fonte não listada é rejeitada.credit_limit_usd— um limite de gasto fixo. Uma requisição que ultrapassaria o limite da chave é rejeitada.expiry— uma data de expiração fixa. Chaves expiradas são rejeitadas.environment— uma tag (production,staging,dev, …) para organizar e identificar a chave por ambiente de deployment.guardrail_id— a política de guardrail que se vincula a esta chave (veja as Camadas 2 e 4).firewall_policy_id— a política de firewall que se vincula a esta chave (veja a Camada 3).is_firewall_gateway— sinaliza a chave como um token com escopo de firewall-gateway; necessário para as rotas de avaliação e gateway MCP.
is_firewall_gateway e leituras de
chave em texto simples exigem Admin.
Para o modelo completo de chave, veja Escopo, chaves, políticas e workspaces.
2. Camada 2 — Guardrails de entrada
Uma vez que a chave é validada, o gateway executa as regras de estágio de entrada do guardrail vinculado contra o texto da requisição — antes de qualquer chamada ao modelo upstream. O que ele vê: As mensagens do chamador como submetidas. (Um prompt injetado a partir de um prompt de registro é anexado depois, na etapa de roteamento; as regras de entrada não o veem.) Tipos de regra disponíveis:keyword, regex, pii, max_chars,
external, llm_judge, grounding.
Ações que uma regra pode produzir:
| Ação | O que acontece |
|---|---|
block | A requisição é rejeitada — HTTP 400 guardrail_blocked. Nenhuma cota é cobrada. Marcada como skip-retry. |
mask | A correspondência é redigida (ex.: jane@acme.com → [EMAIL]). O texto sanitizado continua para o modelo. |
flag | A correspondência é registrada; o tráfego não é alterado. |
block neste estágio significa que o modelo nunca é chamado. Custo: zero.
O chamador vê um erro estruturado nomeando o guardrail e a regra que disparou.
Onde configurar: Console → Guardrails, ou a API de guardrail. Exige
Developer+ para criar ou modificar. Veja Guardrails
para a referência completa de regras.
3. Camada 3 — Execução do modelo
Se a chave for válida e os guardrails de entrada passarem, o gateway encaminha a requisição para o modelo upstream. Esta é a única camada sem enforcement configurável — é simplesmente o modelo fazendo seu trabalho. O firewall opera nas ações que o modelo produz (Camada 3 → Camada 4 abaixo), não no modelo em si. Roteamento, fallbacks e balanceamento de carga acontecem aqui de forma transparente.4. Camada 4 — Agent Firewall (chamadas de ferramenta e egress)
Depois que o modelo responde — ou inline, à medida que as chamadas de ferramenta são emitidas — o Agent Firewall julga cada ação que o modelo solicita. Quatro superfícies de enforcement:| Superfície | O que o firewall vê |
|---|---|
inbound | Definições de ferramenta que o agente anuncia ao modelo. Bloqueie uma ferramenta perigosa antes que o modelo possa escolhê-la. |
response | tool_calls que o modelo emite em sua resposta. |
mcp | Um tools/call despachado através do gateway MCP do Firewall ou do hook de avaliação. |
egress | Um destino de rede outbound (host / IP / CIDR) reportado por uma ferramenta — a superfície de SSRF e exfiltração de dados. |
| Veredito | O que faz |
|---|---|
allow | A chamada prossegue. Registrada. |
audit | A chamada prossegue; registrada para revisão. O default_verdict padrão. |
deny | A chamada é bloqueada — HTTP 400 firewall_blocked na superfície inbound; um erro de ferramenta no mcp. |
sanitize | Substrings correspondentes são redigidas dos argumentos da ferramenta; a chamada limpa prossegue. No inbound (sem argumentos ainda), escala para deny. |
pending_approval | A chamada é retida; um revisor fora de banda aprova ou rejeita; o agente reenvia com um token de aprovação de uso único. |
cap_cost | Nega assim que o gasto acumulado da run do agente excede um limite por regra em centavos. |
deny na superfície inbound não custa tokens de modelo — o bloqueio
dispara antes da chamada upstream. Um pending_approval retorna HTTP 400
firewall_approval_pending com um id de aprovação que o cliente consulta.
Onde configurar: Console → Firewall, ou a API de firewall. Exige
Developer+ para criar ou modificar políticas e regras. Veja
Firewall e Regras de Firewall
para a linguagem completa de regras.
5. Camada 5 — Guardrails de saída
Depois que o modelo responde (e depois que qualquer ciclo de chamadas de ferramenta é concluído), o gateway executa as regras de estágio de saída do guardrail vinculado contra o texto da resposta antes que ela alcance o chamador. Os mesmos tipos de regra e ações se aplicam como na Camada 2. Umblock de
saída retorna HTTP 400 guardrail_blocked e reembolsa a cota pré-consumida
— o chamador não paga nada.
Streaming e mascaramento de saída. Uma ação
block é aplicada tanto em
respostas streaming quanto não-streaming — em um stream, o scanner corta em
pleno voo e emite uma substituição. Uma ação mask na saída atualmente se
aplica apenas a respostas não-streaming; em uma resposta streaming o chunk
original passa sem ser mascarado. Verifique sua combinação de estágio/stream
no sandbox de guardrail antes de depender dela.6. Camada 6 — Auditoria
Cada correspondência, veredito e decisão de aprovação é escrita na trilha de auditoria, correlacionada à run e sessão do agente que as causou. Isso não é uma etapa de enforcement separada — ela roda em paralelo com as Camadas 2–5 — mas é a camada que torna as outras responsáveis. O que é registrado:- Correspondências de guardrail: tipo de regra, ação, estágio, string de detalhe e (se Log raw content estiver habilitado) a substring correspondente.
- Eventos de firewall: superfície, nome da ferramenta, veredito, regra correspondente, código de motivo, fatores de risco e a run/sessão à qual a chamada pertence.
- Decisões de aprovação: quem aprovou ou rejeitou, quando e se a regra subjacente mudou entre o hold e a decisão.
- Mudanças de política: cada criação, atualização, exclusão e mudança de nível de autonomia escreve uma linha de auditoria versionada.
7. Tabela resumo
| Camada | O que controla | O que vê | Resultado em um hit | Onde configurar |
|---|---|---|---|---|
| 1. Chave com escopo | Identidade, acesso a modelos, gasto, IP, expiração | O token de autenticação da requisição | HTTP 4xx antes de qualquer execução; sem medição | Console → API Keys (Developer+) |
| 2. Guardrails de entrada | Conteúdo de texto da requisição | Mensagens do chamador | Block (HTTP 400 guardrail_blocked, sem cobrança), mask ou flag | Console → Guardrails (Developer+) |
| 3. Modelo | — | — | — | Config de roteamento / canal |
| 4. Agent Firewall | Chamadas de ferramenta, dispatch de MCP, egress | Nome da ferramenta, argumentos, destino | allow / audit / deny / sanitize / pending_approval / cap_cost | Console → Firewall (Developer+) |
| 5. Guardrails de saída | Conteúdo de texto da resposta | Resposta do modelo | Block (HTTP 400, cota reembolsada), mask ou flag | Console → Guardrails (Developer+) |
| 6. Auditoria | Atribuição e trilha | Tudo acima | Entrada de log imutável | Console → Matches (Member) / Events & Runs (Developer+) |
8. Ordem de resolução de política
Para qualquer requisição, o guardrail ativo e a política de firewall são resolvidos independentemente:- Vinculação da chave — se a chave carrega um
guardrail_idoufirewall_policy_idexplícito, essa política se vincula (quando existe e está habilitada). - Padrão do workspace — se a chave não tem vinculação, o guardrail ou
política
is_defaulthabilitado do workspace se aplica. - Nenhum — sem enforcement. A requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
9. Fail-open e fail-closed
Dois comportamentos — aplicados a casos diferentes.Fail-open (erros transitórios): Se a resolução de política encontra um
erro transitório — um soluço do banco de dados, uma falha de rede no caminho
para um fornecedor externo — o gateway degrada para sem enforcement em vez
de derrubar o tráfego. A segurança degrada; a disponibilidade é preservada.
Configure
fail_open: false em regras external ou llm_judge quando uma
verificação perdida for inaceitável para a sua política.Fail-closed (casos ambíguos): Onde não aplicar derrotaria a regra, o
motor falha fechado: um relatório de egress com um destino não resolvível é
negado; um armazenamento de aprovação inalcançável retém a chamada em vez de
passá-la; uma skill cuja propriedade não pode ser resolvida é bloqueada. A
disponibilidade é preservada no caminho feliz; a segurança não é silenciosamente
pulada nos casos extremos que importam.10. Aprofundamentos
Guardrails
Referência completa de regras — tipos, ações, entidades PII, LLM judge,
grounding e o sandbox de testes.
Firewall
Modelo de política, vereditos, superfícies, shadow mode, aprovação HITL
e detecção de anomalias.
Regras de Firewall
A linguagem de correspondência de regras — globs de ferramenta, cláusulas
de argumento, listas de egress e sanitizers.
Guardrails vs. Firewall
Qual camada intercepta qual ameaça — e quando você precisa de ambas.
Escopo, chaves e políticas
O modelo completo de chave: o que uma chave carrega e como as políticas
se resolvem.
Modos de enforcement
Fail-open vs. fail-closed — a árvore de decisão completa.