1. O que é o motor de guardrails
Um guardrail é uma política de conteúdo nomeada e com escopo de workspace — uma lista ordenada de regras que o gateway executa contra a entrada da requisição e a saída do modelo. Você salva um guardrail uma vez, vincula qualquer chave de API a ele (ou define um como padrão do workspace), e o gateway filtra cada chamada antes e depois do modelo upstream. Cada regra decide uma coisa — o que procurar (um tipo de regra), onde procurar (um estágio: entrada da requisição ou saída do modelo) e o que fazer a respeito (uma ação: block, mask ou flag). O motor executa cada regra aplicável e consolida os resultados em uma única decisão. Editar um guardrail entra em vigor em cada chave vinculada a ele já na próxima chamada. Sem redeploy. Sem mudança de código. Sem upgrade de SDK. A política vive no gateway, não na sua aplicação — sua app continua chamando/v1/chat/completions exatamente como antes.
O motor é determinístico e sem dependências para os tipos de regra
embutidos: correspondência pura de string e regex sem chamada de rede,
segura para rodar no caminho quente de relay. Regras avançadas (fornecedores
externos, LLM judge, contextual grounding) fazem chamadas externas e são
despachadas concorrentemente, de modo que uma verificação lenta nunca se
serializa atrás de outra.
Guardrails têm escopo de workspace — cada membro vê os guardrails do
workspace; nada atravessa fronteiras de tenant.
2. Início rápido — filtre sua primeira requisição em 5 passos
Criar um guardrail
/console/guardrails e clique em New
guardrail. Nomeie-o pii-shield. Adicione uma regra:- Tipo: PII detection
- Estágio: Input (requisição)
- Ação: Mask — redigir a correspondência
- Entidades:
email,phone,ssn
Testar no sandbox
input e execute. O sandbox mostra
o veredito e o texto renderizado — email me at [EMAIL] — sem
enviar nada upstream.Vincular uma chave
/console/token, crie ou edite uma chave de API e escolha
pii-shield no menu Guardrail. O vínculo vive na chave dentro do
gateway.Enviar uma requisição
[EMAIL] antes de encaminhar. O
modelo upstream nunca vê o endereço.3. Conceitos: guardrails, regras, estágios, ações
| Conceito | Definição |
|---|---|
| Guardrail | Uma política nomeada, com escopo de workspace. Identificador: name (≤ 64 chars). Tem enabled, is_default e um blob JSON rules. |
| Regra | Uma verificação dentro de uma política: um type, um stage, uma action, mais campos específicos do tipo. As regras rodam em ordem. |
| Estágio | input (a requisição), output (a resposta do modelo) ou both. |
| Ação | block (rejeita a chamada), mask (redige a correspondência) ou flag (apenas registra — observa sem alterar o tráfego). |
Escopo e o padrão do workspace
Guardrails têm escopo exatamente como as chaves de API: compartilhados no workspace quando você tem um workspace ativo, por usuário caso contrário. Resolução para qualquer requisição:- Vínculo da chave — se a chave tem um
guardrail_idexplícito, esse guardrail se aplica (quando existe e está habilitado). Um vínculo explícito nunca cai silenciosamente para outro; desabilitá-lo é o botão de desligar. - Padrão do workspace — se a chave não tem vínculo, o guardrail
is_defaulthabilitado do workspace se aplica. - Nenhum — sem enforcement. A requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
Como é um block
Uma requisição bloqueada retorna HTTP 400 com o código de erroguardrail_blocked e uma mensagem nomeando o guardrail e a regra que
disparou. Uma requisição bloqueada não custa cota — um block no
estágio de input dispara antes da medição, e um block no estágio de output
reembolsa a cota pré-consumida — e é marcada como skip-retry
(reexecutar o mesmo prompt apenas bloquearia de novo).
4. Tipos de regra
As regras se dividem em dois grupos: embutidas (determinísticas, sem rede) e avançadas (fazem chamada a um modelo ou fornecedor).| Tipo | Grupo | O que faz |
|---|---|---|
Keyword denylist (keyword) | Embutida | Corresponde a qualquer um de uma lista de termos literais — sem distinção entre maiúsculas e minúsculas, correspondência por substring (portanto class também corresponde a classic). |
Regular expression (regex) | Embutida | Corresponde a um padrão RE2 (tempo linear, sem backreferences). |
PII detection (pii) | Embutida | Detecta tipos de entidade embutidos (e os seus próprios personalizados). Veja §5. |
Maximum length (max_chars) | Embutida | Limita a contagem de caracteres do texto em um estágio. |
External vendor (external) | Avançada | Delega a verificação a um fornecedor conectado (Aporia, Averta, BYO-webhook, …). Veja §9. |
LLM judge (llm_judge) | Avançada | Roda uma verificação semântica contra um modelo no seu workspace. Veja §6. |
Contextual grounding (grounding) | Avançada | Pontua a fidelidade da resposta em relação às fontes recuperadas na requisição (RAG). Veja §7. |
external, llm_judge, grounding) são despachadas
concorrentemente para que uma verificação lenta não se serialize atrás
de outra.
5. PII detection em profundidade
Uma regrapii detecta entidades sensíveis e aplica a ação da regra a
cada correspondência. O conjunto de detectores embutidos é fechado e
compartilhado pelo motor, pelo validador e pelo construtor de regras:
email, phone, credit_card, ssn, ip, iban, mac_address,
api_key_openai, aws_access_key, jwt, bitcoin_address.
Em uma ação mask, cada correspondência é substituída por uma tag
tipada — um email vira [EMAIL], um SSN vira [SSN], e assim por diante.
Entidades personalizadas
Adicione seus próprios detectores sobre o conjunto embutido. Uma entidade personalizada é:name— ASCII minúsculo / dígitos / underscore, deve começar com uma letra (ex.:employee_id). Flui para os logs de auditoria e a telemetria sem aspas.pattern— um regex Go RE2 (tempo linear, sem backreferences).checksum— opcional;luhnvalida a correspondência com o algoritmo de Luhn (ex.: para números semelhantes a cartões).mask_with— substituição verbatim opcional; o padrão é[<UPPERCASE_NAME>].
Overrides de ação por entidade
Uma única regra PII pode aplicar ações diferentes a entidades diferentes viaentity_actions. Uma regra que mascara emails / phones / IPs por
padrão mas bloqueia em credit_card ou ssn — em vez de três regras
sobrepostas:
block / mask / flag. O validador rejeita qualquer outra coisa.
6. LLM judge
Uma regrallm_judge roda uma verificação semântica contra um modelo que
seu workspace já pode chamar. Use-a para políticas difusas que nenhum regex
captura — toxicidade, assédio, fora de tópico, intenção de prompt-injection.
| Campo | Significado |
|---|---|
judge_model | O modelo ou alias de roteador com o qual avaliar (ex.: gpt-4o-mini, orcarouter/cheap). Resolvido contra os canais do seu workspace. |
judge_rubric | O system prompt que descreve o que sinalizar. |
judge_format | Um entre yes_no, score ou category (obrigatório; o console pré-seleciona yes_no). |
judge_threshold | Para score: bloqueia/sinaliza quando o score está neste valor ou acima dele. |
judge_categories | Para category: a lista negada. |
judge_timeout_ms | Limita a chamada do judge. 0 → padrão do motor. |
judge_fail_open | true (padrão) → um erro do judge é observado mas a requisição continua; false → trata erro/timeout como um block. |
7. Contextual grounding
Uma regragrounding mede a resposta do assistente em relação às fontes
recuperadas na requisição (seu contexto RAG) e sinaliza ou bloqueia
respostas que não sejam fiéis a elas. Ela reutiliza a costura do judge —
mesmos canais do workspace, mesma atribuição de custo.
| Campo | Padrão | Significado |
|---|---|---|
grounding_model | escolha do workspace | O modelo para o qual o runner resolve a verificação de fidelidade. |
grounding_rubric | embutido | Sobrescreve o rubric de fidelidade padrão. |
grounding_threshold | 0.7 | Piso de fidelidade, 0.0–1.0. Abaixo dele, a ação dispara. |
grounding_strict | false | Quando true, “nenhuma fonte fornecida” é tratado como um block (vs. o padrão de permitir). |
grounding_max_bytes | 100000 | Limita o contexto de fontes concatenado entregue ao judge. |
grounding_timeout_ms | 3000 | Limita a chamada do judge. |
8. Templates, o sandbox e o eval harness
Biblioteca de templates
O split-button New guardrail abre direto em um template, e a biblioteca completa fica a um clique de distância. Os presets são escritos no servidor para que o console, o sandbox e estes docs descrevam exatamente o mesmo comportamento. As categorias incluem:- PII (
pii) — PII Shield, PII Blocker (strict), Contact-Info Redactor, redator de PII de resposta. - Secrets (
secrets) — bloqueadores de credenciais AWS / OpenAI / GitHub, chaves privadas e tokens de nuvem, carteiras de cripto, segredos na saída. - Compliance (
compliance) — GDPR (PII da UE), PCI (block total de cartão), HIPAA (PHI), dados financeiros, logger de compliance, enforcement de aviso legal. - Brand (
brand) — palavrões (block / mask / multilíngue), menções a concorrentes, palavras-chave de segurança infantil. - Safety (
safety) — prompt-injection, jailbreak, vazamento de system-prompt, automutilação. - Cost (
cost) — limites de tamanho de prompt/resposta e limites de tokens. - Agent (
agent) — filtros de URL, imagem-markdown, chamada-de-ferramenta-shell e SQL-injection na saída.
O sandbox de testes
Todo editor tem uma aba Test. Cole uma amostra, escolha um estágio e rode a política atual localmente — sem chamada upstream, sem cota. O sandbox retorna o veredito e (para regras de mask) o texto renderizado, para que você prove que uma regra faz o que você espera antes de vincular uma chave.Eval / red-team harness
A aba Eval roda um guardrail contra um corpus de entradas e relata como ele pontuou — útil para ajustar um judge rubric ou provar que uma política pega ataques conhecidos antes de você publicá-la.- Corpora empacotados acompanham o gateway — conjuntos adversariais e de red-team (prompts de comportamento prejudicial, injeção de ferramentas, red-teaming multilíngue) mais conjuntos benignos para medir falsos positivos.
- Corpora personalizados — faça upload do seu próprio JSONL para testar contra as formas reais do seu tráfego.
- Runs são listadas com suas pontuações; abra uma run para inspecionar as falhas amostra por amostra.
9. External vendors
Uma regraexternal delega a verificação a um fornecedor conectado.
Conecte um fornecedor uma vez em Integrations (o CTA do cabeçalho na
página Guardrails), depois referencie a conexão a partir de uma regra.
Fornecedores suportados
| Fornecedor | O que é |
|---|---|
Aporia Guardrails (aporia) | Motor de políticas baseado em ensemble de SLM para prompts e respostas. |
Averta (averta) | Endpoint genérico de classificador SLM (POST de texto → safe / unsafe + reescrita opcional). |
BYO Webhook (webhook) | Sua própria URL — recebe prompts e retorna veredictos allow / block / mask / flag. |
Campos da regra
| Campo | Significado |
|---|---|
connection_id | A integração conectada a usar (caminho recomendado — fornecedor + segredos resolvem a partir da integração do workspace em tempo de execução). |
timeout_ms | Limita a única chamada ao fornecedor. 0 → padrão. |
fail_open | true (padrão) → um erro do fornecedor é observado mas a requisição continua; false → trata erro de transporte / timeout / provedor desconhecido como um block. |
10. Observabilidade
Guardrails deixam migalhas sobre as quais você pode agir.Feed de matches
Toda regra que dispara registra um match — tipo de regra, ação, uma string de detalhe, o estágio e (quando habilitado) a substring correspondente. A aba Matches na página Guardrails é o feed de todo o workspace: listar, agrupar, filtrar, detalhar um único match, exportar para CSV e marcar falsos positivos.Stats
O feed de Matches alimenta as estatísticas por guardrail — cada card de guardrail mostra um sparkline e uma contagem de matches de 7 dias, e a aba Matches traz um total do workspace. Para segmentar a atividade por política, use a visão agrupada e os filtros do feed de Matches (por guardrail, tipo de regra, ação) — é ali que vivem o uso por guardrail, o mix de ações e a taxa de falsos positivos.Histórico de versões e auditoria
Cada criação, atualização e exclusão escreve uma linha de histórico versionada na mesma transação que a mudança. Abra History na linha de um guardrail para:- Ver cada versão com quem a alterou e quando.
- Diff entre quaisquer duas versões.
- Revert para uma versão mais antiga (registrado como uma nova versão — o histórico nunca é mutado).
11. Relacionamento com o resto do gateway
| Superfície | Como se compõe com os Guardrails? |
|---|---|
| Modelos | Guardrails são agnósticos a modelo. A mesma política anda sobre GPT-5, Claude, Gemini — ela filtra texto, não a escolha do modelo. |
| Roteamento | Independente. O roteamento decide qual modelo/canal atende à requisição; os guardrails filtram o mesmo texto de requisição/resposta independentemente disso e nunca sobrepõem a seleção de modelo. A filtragem de input roda antes da chamada upstream, a filtragem de output depois que o modelo responde. As regras de judge e grounding resolvem seu próprio modelo através dos canais do seu workspace, separadamente do roteamento da requisição. |
| Prompts | Independentes e complementares. Prompts injetam uma mensagem de sistema; guardrails inspecionam e gateiam conteúdo. Ambos podem se aplicar a uma requisição e os guardrails sempre rodam. A ordem importa: as regras de input filtram a requisição do chamador antes que um prompt do registro seja injetado (a injeção acontece depois, na etapa de roteamento), então as regras de input veem as mensagens do chamador, não o prompt de sistema injetado; as regras de output filtram a resposta do modelo de qualquer forma. |
| Chaves de API | Uma chave se vincula a um guardrail via guardrail_id. O vínculo vive na chave dentro do gateway, então editar o guardrail desloca todas as chaves vinculadas de uma vez; nenhum vínculo cai para o padrão do workspace. |
| Feed de Matches | Toda regra que dispara cai no feed de Matches do workspace (seu próprio armazenamento, separado do log de requisição). Agrupe e filtre por guardrail, tipo de regra e ação para ver uso, mix de ações e taxa de falsos positivos por guardrail. |
12. Referência da API
Todas as rotas têm escopo de workspace via o headerX-Workspace-Id. RBAC
é aplicado de maneira consistente: leituras e o sandbox de testes são
abertos a cada membro; escritas exigem Developer+ (e a permissão
guardrails:write); mudanças de tráfego de produção (delete, revert,
configuração de fornecedor) são gateadas adequadamente.
Guardrails
| Método e path | Papel | Propósito |
|---|---|---|
GET /api/guardrail/ | Member | Lista guardrails (com contagens de chaves vinculadas). |
GET /api/guardrail/meta | Member | Vocabulário do motor — tipos de regra, estágios, ações, entidades PII, presets, categorias de preset. |
GET /api/guardrail/my-permissions | Member | As permissões de guardrail do chamador (para gating de UI). |
GET /api/guardrail/:id | Member | Detalhe de um único guardrail. |
GET /api/guardrail/:id/tokens | Member | Chaves de API vinculadas a este guardrail (limitado, com o total verdadeiro). |
POST /api/guardrail/test | Member | Sandbox — avalia uma política sobre texto de amostra em um estágio. Nada é persistido. |
POST /api/guardrail/ | Developer+ | Cria um guardrail. |
PUT /api/guardrail/ | Developer+ | Atualiza um guardrail (escreve uma nova versão de histórico). |
DELETE /api/guardrail/:id | Developer+ | Deleta um guardrail. |
History
| Método e path | Papel | Propósito |
|---|---|---|
GET /api/guardrail/:id/history | Member | Histórico de versões (mais nova primeiro). |
GET /api/guardrail/:id/history/diff | Member | Diff entre duas versões. |
GET /api/guardrail/:id/history/:version | Member | Uma única versão histórica. |
POST /api/guardrail/:id/revert | Developer+ | Restaura uma versão mais antiga como uma nova versão. |
Eval e corpora
| Método e path | Papel | Propósito |
|---|---|---|
POST /api/guardrail/:id/eval | Member | Roda um eval sobre um corpus (nome empacotado ou JSONL enviado). |
GET /api/guardrail/:id/eval/runs | Member | Lista runs de eval para um guardrail (paginado). |
GET /api/guardrail/eval/runs/:run_id | Member | Detalhe de uma única run de eval. |
GET /api/guardrail/eval/corpora | Member | Lista corpora do workspace + corpora empacotados. |
POST /api/guardrail/eval/corpora | Developer+ | Faz upload de um corpus JSONL. |
GET /api/guardrail/eval/corpora/:id | Member | Detalhe do corpus. |
DELETE /api/guardrail/eval/corpora/:id | Developer+ | Deleta um corpus. |
Matches
| Método e path | Papel | Propósito |
|---|---|---|
GET /api/guardrail/match | Member | Lista matches (com escopo de workspace). |
GET /api/guardrail/match/grouped | Member | Matches agrupados (ex.: por regra ou guardrail). |
GET /api/guardrail/match/stats | Member | Estatísticas de matches (suporta ?days= e ?group_by=). |
GET /api/guardrail/match/export | Member | Exporta matches como CSV. |
GET /api/guardrail/match/:id | Member | Detalhe de um único match. |
POST /api/guardrail/match/:id/mark-fp | Admin | Marca um match como falso positivo (rate-limited). |
DELETE /api/guardrail/match/:id/mark-fp | Admin | Desmarca um falso positivo (rate-limited). |
Vinculando uma chave
Definaguardrail_id na chave de API (via o editor de chave ou a API de
token). 0/null significa nenhum vínculo explícito — a chave cai para o
guardrail padrão do workspace, se houver um definido.
13. FAQ
E se nenhum guardrail for resolvido em uma requisição?
E se nenhum guardrail for resolvido em uma requisição?
Uma requisição bloqueada custa cota?
Uma requisição bloqueada custa cota?
guardrail_blocked e a requisição é marcada como
skip-retry (reexecutar o mesmo prompt contra outro canal apenas
bloquearia de novo).As regras de output (resposta) são aplicadas em streaming?
As regras de output (resposta) são aplicadas em streaming?
Qual a diferença entre mask e block?
Qual a diferença entre mask e block?
jane@acme.com → [EMAIL]) e
deixa a requisição passar com o texto sanitizado — o modelo upstream
nunca vê o original. Block rejeita a requisição inteira com HTTP
400. Flag não altera nada no tráfego e apenas registra um match —
use-o para medir uma regra antes de aplicá-la.Tokens de prompt injetado e tokens de judge são cobrados?
Tokens de prompt injetado e tokens de judge são cobrados?
llm_judge ou grounding chama
um modelo através dos canais do seu workspace, então esses tokens são
cobrados e atribuídos como uma sub-linha de judge.Como vejo o que uma regra realmente correspondeu?
Como vejo o que uma regra realmente correspondeu?
Posso reverter uma mudança de guardrail?
Posso reverter uma mudança de guardrail?
O que acontece se um fornecedor externo ou judge der timeout?
O que acontece se um fornecedor externo ou judge der timeout?
fail_open (external) ou judge_fail_open (judge) como false
para falhar fechado — tratar o erro como um block — em políticas
onde uma verificação perdida é inaceitável.