Guardrails

Os Guardrails do AI Gateway são evaluators LLM-as-a-Judge e em Python que validam as solicitações e respostas que passam pelo gateway. Depois de criados, eles podem ser vinculados a Guardrail Rules para bloquear gerações fora de conformidade antes que cheguem ao chamador.

LLM Guardrail

Use um modelo para julgar as saídas com base em quaisquer critérios definidos em um prompt.

Python Guardrail

Escreva código Python personalizado para ter total flexibilidade: verificações com regex, validação de tamanho, chamadas HTTP ou validação de JSON schema.

Comportamento de execução

Defina cada Guardrail como Input, Output ou Both ao adicioná-lo a uma Guardrail Rule. Os Guardrails de entrada, incluindo o Secret Detection, são executados de forma síncrona sobre a entrada completa antes que o AI Gateway envie a solicitação ao modelo. O streaming não altera esse comportamento. Os Guardrails de saída são executados após a geração e antes da resposta em solicitações sem streaming.

Os Guardrails de saída não são executados em respostas em streaming. Um segredo pode se estender por vários chunks, portanto uma verificação chunk a chunk não consegue inspecionar a saída completa. Use uma solicitação sem streaming quando for necessário aplicar verificações na saída.

Chamadas de ferramentas

Uma chamada de ferramenta atendida por um MCP Gateway é verificada pelos Guardrails anexados a esse gateway, nos argumentos da ferramenta, no resultado da ferramenta ou em ambos, e pelos plugins do gateway. A chamada de ferramenta de um Agent também é regida pela aprovação de ferramenta configurada na ferramenta.

Tempo limite

No endpoint Responses, cada entrada do array guardrails[] de uma solicitação pode definir seu próprio timeout em milissegundos. Ele limita a execução dessa entrada e é independente do call_timeout no nível da solicitação, que limita apenas a chamada ao modelo. Consulte Tempos limite de solicitação. Uma entrada é executada como Guardrail bloqueante quando is_guardrail é true e, caso contrário, como Evaluator de monitoramento.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Chave de um Guardrail ou Evaluator publicado.
`execute_on`	string	Sim	`input`, `output` ou `both`. Uma entrada com valor não reconhecido é ignorada sem erro.
`is_guardrail`	boolean	Não	`true` executa a verificação como Guardrail bloqueante, `false` como Evaluator de monitoramento. O padrão é `false`.
`sample_rate`	number	Não	Fração em `[0,1]` das solicitações correspondentes em que será executado. Ignorado em um Guardrail, que sempre é executado; em um Evaluator de monitoramento, o padrão é `0`.
`timeout`	integer	Não	Limite de execução em milissegundos. O padrão é o tempo limite do evaluator ou, se ele não tiver um, `60000` (60 segundos); valores acima de `600000` (10 minutos) são limitados a 10 minutos.
`options`	object	Não	Configuração específica do Guardrail, por exemplo `language` e `threshold` para o PII Detection.

{
  "model": "openai/gpt-5.6-sol",
  "timeout": { "call_timeout": 30000 },
  "guardrails": [
    { "id": "orq_pii_detection", "execute_on": "input", "is_guardrail": true, "timeout": 5000 },
    { "id": "response-quality", "execute_on": "output", "is_guardrail": true, "timeout": 15000 }
  ]
}

No endpoint Responses e no endpoint de chat completions compatível com a OpenAI, um Guardrail que excede seu timeout faz a solicitação falhar com HTTP 408 e error.code guardrail_timeout, junto com as demais falhas de Guardrail. Consulte Resposta de erro de guardrail. O endpoint de chat completions compatível com a OpenAI aceita o mesmo timeout em cada entrada do array guardrails[], mas rejeita valores fora do intervalo de 1000-600000 milissegundos com 400, em vez de usá-los literalmente.

Também é possível definir um tempo limite no Evaluator, em Guardrail configuration, de 1 a 120 segundos. Ele se aplica onde quer que o evaluator seja executado, incluindo as Guardrail Rules. Se uma solicitação também definir timeout, vale o menor valor.

LLM Guardrail

Os LLM Guardrails usam um modelo para julgar solicitações ou respostas com base em critérios definidos em um prompt. Abra Evaluators, clique em + Evaluator e selecione LLM-as-a-judge. Preencha os seguintes campos:

Campo	Descrição
Key	Identificador único do guardrail
Description	Contexto opcional
Model	O modelo usado como juiz. Qualquer modelo habilitado no AI Gateway está disponível
Guardrail configuration	A regra de aprovação que o evaluator aplica quando é executado como guardrail, por exemplo Pass If Greater Or Equal Than

Configurar o prompt

Faça referência à execução avaliada com as seguintes variáveis string. Digite {{ no editor de prompt para escolher uma na lista completa.

Variável	Descrição
`{{input.user_query}}`	A última mensagem enviada ao modelo
`{{input.all_messages}}`	A conversa completa, incluindo o turno avaliado
`{{input.system_instructions}}`	O system prompt usado na execução
`{{input.retrievals}}`	Recuperações da Knowledge Base
`{{input.expected_output}}`	A referência usada para comparar a saída
`{{output.response}}`	A resposta gerada pelo modelo avaliado
`{{output.tools_called}}`	As chamadas de ferramentas feitas durante a execução, com seus resultados

Consulte Formatos de variáveis estruturadas para ver os campos disponíveis ao indexar mensagens e chamadas de ferramentas.

Variáveis log legadas

As variáveis log.* continuam compatíveis, portanto os Guardrails existentes continuam funcionando. Prefira as variáveis acima nos novos.

Variável	Descrição
`{{log.input}}`	Igual a `{{input.user_query}}`
`{{log.output}}`	Igual a `{{output.response}}`
`{{log.retrievals}}`	Igual a `{{input.retrievals}}`
`{{log.reference}}`	Igual a `{{input.expected_output}}`
`{{log.tool_calls}}`	Igual a `{{output.tools_called}}`
`{{log.messages}}`	A conversa sem o turno avaliado. `{{input.all_messages}}` o mantém.

Saída e configuração do guardrail

Selecione o tipo de saída e defina a condição de aprovação. O painel Guardrail configuration fica visível diretamente nas configurações.

Boolean
Number
Categorical
String

O modelo retorna uma resposta True ou False. Use para verificações binárias de aprovação/reprovação.Condição de aprovação: selecione True ou False. O guardrail é aprovado quando o modelo retorna o valor selecionado.

Testes

O painel Playground oferece um Editor para testes. Preencha o payload manualmente:

{
  "messages": [],
  "input": "",
  "retrievals": [],
  "output": "",
  "reference": ""
}

Clique em Run test para executar o guardrail. O resultado aparece no campo Response.

A aba Dataset não está disponível para Guardrails.

Python Guardrail

Os Python Guardrails aceitam código Python personalizado para total flexibilidade na avaliação. A interface tem três painéis: Settings, Code e Playground.

O código Python é limitado a 1 MB (1.048.576 bytes) por guardrail: cerca de 1 milhão de caracteres, ou aproximadamente 20.000 linhas de Python típico. Códigos maiores retornam o erro Code exceeds maximum size e não são executados.

Abra Evaluators, clique em + Evaluator e selecione Python. A função de avaliação recebe um objeto log com os seguintes campos:

log["input"] <str>: a última mensagem enviada para gerar a saída
log["output"] <str>: a resposta gerada pelo modelo
log["reference"] <str>: a referência usada para comparar a saída
log["messages"] list<str>: todas as mensagens anteriores enviadas ao modelo
log["retrievals"] list<str>: todas as recuperações da Knowledge Base

A função deve retornar um Boolean ou um Number:

def evaluate(log):
    return True

Para explicar um resultado, retorne um dict em vez de um valor simples: {"value": <value>, "explanation": <str>}. explanation é opcional, deve ser uma string e aparece como reason no painel Output do span do evaluator em Traces. Ele não altera a aprovação do guardrail. Um dict com qualquer outra chave é retornado como está, sem explicação.

Defina funções auxiliares em qualquer parte do código. O executor chama evaluate(log) pelo nome, portanto mantenha esse nome de função.

Ambiente e bibliotecas

O Python Guardrail é executado em Python 3.13 com as seguintes bibliotecas pré-carregadas:

numpy==2.5.0
nltk==3.10.3
requests
pydantic
json
re

Os dados do tokenizador punkt_tab do NLTK são pré-carregados, portanto nltk.word_tokenize() funciona sem baixar dados adicionais.

Configuração do guardrail

Defina a condição de aprovação com base no tipo de retorno:

Boolean: selecione True ou False. O guardrail é aprovado quando a função retorna o valor selecionado.
Number: insira um limite de pontuação. O guardrail é aprovado quando o valor retornado é maior ou igual ao limite.

Testes

O painel Playground oferece um Editor para testes. Preencha o payload manualmente e clique em Run test para executar o guardrail.

A aba Dataset não está disponível para Guardrails.

Versões

Clique em Publish para salvar as alterações. Escolha o tipo de incremento de versão:

Patch (por exemplo, v1.0.0 → v1.0.1): pequenas correções, sem mudança de comportamento
Minor (por exemplo, v1.0.0 → v1.1.0): nova funcionalidade, compatível com versões anteriores
Major (por exemplo, v1.0.0 → v2.0.0): mudança incompatível ou reformulação significativa

A aba Versions mostra o histórico completo, com o autor e a data e hora de publicação de cada versão.

Restaurar uma versão

Clique no ícone de comparação de qualquer versão na aba Versions para abrir Compare e, em seguida, clique em Restore ao lado de uma versão mais antiga para carregá-la no rascunho de trabalho atual. A restauração não publica automaticamente: o guardrail é carregado no rascunho como alterações não publicadas na aba Settings, e ainda é preciso clicar em Publish para que ele se torne uma versão de fato. As versões anteriores nunca são excluídas, portanto a restauração é sempre reversível.

Se já houver alterações não publicadas, uma caixa de diálogo pede confirmação antes de sobrescrevê-las.

Usar Guardrails

Os Guardrails criados aqui ficam disponíveis para seleção ao configurar Guardrail Rules. Para bloquear com base na decisão de um mecanismo de políticas ou de um provedor de terceiros, como Guardrails AI ou Lakera, consulte Guardrails externos.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

LLM Guardrail

Python Guardrail

Comportamento de execução

Chamadas de ferramentas

Tempo limite

LLM Guardrail

Configurar o prompt

Saída e configuração do guardrail

Testes

Python Guardrail

Ambiente e bibliotecas

Configuração do guardrail

Testes

Versões

Restaurar uma versão

Usar Guardrails

LLM Guardrail

Python Guardrail

​Comportamento de execução

​Chamadas de ferramentas

​Tempo limite

​LLM Guardrail

​Configurar o prompt

​Saída e configuração do guardrail

​Testes

​Python Guardrail

​Ambiente e bibliotecas

​Configuração do guardrail

​Testes

​Versões

​Restaurar uma versão

​Usar Guardrails

Comportamento de execução

Chamadas de ferramentas

Tempo limite

LLM Guardrail

Configurar o prompt

Saída e configuração do guardrail

Testes

Python Guardrail

Ambiente e bibliotecas

Configuração do guardrail

Testes

Versões

Restaurar uma versão

Usar Guardrails