Saltar para o conteúdo principal
Um guardrail é a camada de política de conteúdo do gateway OrcaRouter. Você escreve uma política nomeada no seu workspace, vincula-a a uma chave de API, e cada chamada /v1/* que essa chave faz é filtrada — antes de o modelo ver o prompt e depois de o modelo responder — sem redeploy e sem mudança de SDK. Esta página é o hub da seção Guardrails: o que é um guardrail, os tipos de regra, os estágios e as ações, e como uma política se vincula a uma chave. Cada ramo aprofunda. Para a referência completa do motor, veja Guardrails.

​
1. O que os guardrails de IA fazem no gateway

A maioria dos times recorre aos guardrails para manter dados sensíveis fora dos prompts (PII, segredos), para gatear conteúdo inseguro (jailbreaks, intenção de prompt-injection), ou para satisfazer um controle de compliance. Um guardrail é a resposta do gateway: uma política nomeada, 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. Como o vínculo vive na chave de API dentro do gateway — não na sua aplicação — editar um guardrail desloca cada chave vinculada já na próxima chamada. Seu código continua chamando /v1/chat/completions exatamente como antes.
Guardrails são política de conteúdo (texto entra, texto sai). O companheiro Agent Firewall é política de ferramenta — governa quais chamadas de ferramenta um agente pode fazer. Os dois se compõem; veja Guardrails vs. firewall.

​
2. Um exemplo concreto

Crie um guardrail chamado pii-shield no console (/console/guardrails), adicione uma única regra PII — estágio input, ação mask, entidades email, ssn — e vincule-o a uma chave. A partir daí: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
O gateway reescreve o prompt para Reply to [EMAIL] please antes de encaminhar — o modelo upstream nunca vê o endereço. Mude essa entidade ssn para block e a próxima requisição que carregar um SSN é rejeitada com HTTP 400. Nenhuma mudança na aplicação.
A autoria é uma ação de console / API de gerenciamento na sua sessão — a chave de relay sk-orca-... é apenas para tráfego /v1/*, nunca para editar política. Criar ou editar um guardrail exige o papel Developer+.

​
3. Regras: tipo, estágio, ação

Toda regra responde a três perguntas. O motor executa todas as regras aplicáveis e as consolida em uma única decisão.
Sete tipos de regra. As embutidas são determinísticas (string/regex pura, sem rede); as avançadas chamam um modelo ou fornecedor e rodam concorrentemente.
  • keyword — denylist literal, correspondência por substring sem distinção entre maiúsculas e minúsculas.
  • regex — um padrão RE2 (tempo linear, sem backreferences).
  • pii — detectores de entidade embutidos mais os seus próprios. Veja §5.
  • max_chars — limita a contagem de caracteres em um estágio.
  • external — delega a um fornecedor conectado (Aporia, Averta, ou seu próprio webhook).
  • llm_judge — uma verificação semântica contra um modelo no seu workspace.
  • grounding — pontua a fidelidade da resposta em relação às fontes recuperadas na requisição (RAG).
input (a requisição), output (a resposta do modelo) ou both. As regras de input rodam antes da chamada upstream; as regras de output rodam depois que o modelo responde. Veja estágio de input e estágio de output.
Cinco ações aparecem no construtor de regras:
  • block — rejeita a chamada com HTTP 400.
  • mask — redige a correspondência e deixa o texto sanitizado passar.
  • flag — não muda nada no tráfego; apenas registra o match.
  • annotate — deixa o texto intacto mas injeta uma nota de segurança upstream (ex.: um aviso de CVE antes de o modelo responder).
  • spotlight — envolve o texto não confiável correspondente em delimitadores e instrui o modelo a tratá-lo como dados, não instruções.
Veja Ações. Use flag para medir uma regra no tráfego real antes de aplicá-la.

​
4. Como um guardrail se vincula e resolve

Um guardrail se vincula a uma chave via guardrail_id, ou um workspace pode marcar um guardrail como seu padrão. Para qualquer requisição, o gateway resolve nesta ordem:
  1. Vínculo explícito — se o guardrail_id da chave aponta para um guardrail que existe e está habilitado, esse se aplica. Um vínculo explícito nunca cai para outro: desabilitá-lo é o botão de desligar.
  2. Padrão do workspace — se a chave não tem vínculo, o guardrail padrão habilitado se aplica.
  3. Nenhum — sem enforcement; a requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
Isso difere do firewall. Uma política de firewall vinculada e desabilitada cai para o padrão do workspace; um guardrail vinculado e desabilitado vai para nenhum. O botão de desligar é literal para guardrails.
Passo a passo: crie seu primeiro guardrail, vincule a uma chave, defina um padrão de conta.

​
5. Detectores de PII

Uma regra pii traz um conjunto fechado de detectores embutidos: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — mais os regionais jp_mynumber, kr_rrn e cn_resident_id. Em uma ação mask, cada correspondência vira uma tag tipada — um email é renderizado como [EMAIL], um SSN como [SSN]. Você pode empilhar até 25 entidades personalizadas por regra (um regex com checksum de Luhn opcional), e rotear entidades diferentes para ações diferentes em uma regra via overrides por entidade.
O ponto de partida pronto é o preset PII Shield — uma única regra pii, mask, estágio both. O mascaramento no estágio de input reescreve a requisição antes do modelo (streaming ou não); o mascaramento de output reescreve a resposta apenas em respostas não-streaming — a reescrita in-stream do output está no roadmap. Veja PII Shield, entidades personalizadas e formatos de mascaramento.

​
6. O seletor de presets

New guardrail abre em um template. Os presets são escritos no servidor, então o console, o sandbox e estes docs descrevem o mesmo comportamento. O seletor os agrupa em categorias:
CategoriaPresets de exemploRamo
pii / secretsPII Shield, bloqueadores de credenciaisbloquear segredos
safetyprompt-injection, jailbreak, automutilaçãoprompt injection
complianceGDPR, PCI, HIPAA, compliance loggercompliance logger
brand / costpalavrões, menções a concorrentes, limites de tamanhobrand safety · cost
agentfiltros de URL / shell-tool / SQL-na-saídaagentic
code_securityblocks de arquivos de segredo, revisão de licença copyleftcode security
Um preset é uma semente, não uma trava — aplique-o, depois edite livremente. Mais pontos de partida vivem em templates.

​
7. Quando um guardrail bloqueia

Uma requisição bloqueada retorna HTTP 400 com o código de erro guardrail_blocked e uma mensagem nomeando o guardrail e a regra que disparou.
  • Nenhuma cota é cobrada. Um block no estágio de input dispara antes da medição; um block no estágio de output reembolsa a cota pré-consumida.
  • A requisição é marcada como skip-retry — reexecutar o mesmo prompt apenas bloquearia de novo, então o gateway não desperdiça uma retry em outro canal.
Em streaming, block é aplicado em best-effort — um scanner armazena um pequeno lookahead e corta o stream quando uma regra dispara, de modo que bytes já enviados não podem ser retirados. Mask no output se aplica apenas a respostas não-streaming — em uma resposta streaming o gateway calcula a máscara mas não encaminha o texto redigido; a reescrita in-stream do output está no roadmap. (O mascaramento no estágio de input está ativo tanto em streaming quanto em não-streaming.) Veja o erro guardrail_blocked e cobertura de streaming.

​
8. Depois que está ativo

Feed de matches

Toda regra que dispara registra tipo, ação, estágio e detalhe. Agrupe, filtre, exporte e detalhe um único match.

Logging e privacidade

A substring correspondente é registrada apenas quando Log raw content está ligado — desligado por padrão, a postura conservadora de privacidade.

Versionamento

Cada mudança escreve uma linha de histórico. Faça o diff de quaisquer duas versões e reverta como uma nova versão — o histórico nunca é mutado.

Teste e eval

Uma aba Test de sandbox avalia a política atual sem chamada upstream, e um eval harness a pontua contra corpora empacotados ou personalizados.
Um falso positivo é um sinal de ajuste, não um motivo para desabilitar a regra. Marque-o no feed de Matches e estreite o padrão — veja ajustar falsos positivos.

​
9. Para onde ir a seguir

Guardrails — cada campo, cada rota, as regras de LLM-judge e grounding, e fornecedores externos em profundidade.