> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Guardrails > Crie guardrails LLM-as-a-Judge e em Python no AI Gateway para validar solicitações e respostas e bloquear gerações fora de conformidade. 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](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) para bloquear gerações fora de conformidade antes que cheguem ao chamador. > [card] [LLM Guardrail](#llm-guardrail) > > Use um modelo para julgar as saídas com base em quaisquer critérios definidos em um prompt. > [card] [Python Guardrail](#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](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md). 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. > [!WARNING] > > 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](/docs/pt-BR/ai-gateway/features/timeouts.md). 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. | ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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. > [!NOTE] > > 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](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md). 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](/docs/pt-BR/ai-gateway/using-the-router.md) 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. > [accordion] 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. > [tab] Boolean > > 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. > [tab] Number > > O modelo retorna uma pontuação numérica. Use qualquer escala adequada ao caso de uso (por exemplo, 1-5, 0-100). > > **Condição de aprovação**: insira um limite em **Pass if greater or equal than**. O guardrail é aprovado quando a pontuação atinge ou ultrapassa o limite. > [tab] Categorical > > O modelo classifica a saída em um dos rótulos predefinidos. > > Quando **Categorical** é selecionado, aparece um editor de rótulos. Adicione um rótulo por linha: insira um **Value** (a string exata que o modelo deve retornar) e uma **Description** opcional para orientar o modelo. > > **Condição de aprovação**: selecione um ou mais valores em **Pass if output is one of**. O guardrail é aprovado quando a saída do modelo corresponde a qualquer rótulo selecionado. > [tab] String > > O modelo retorna uma resposta em string de formato livre. Não está disponível como condição de aprovação de guardrail. ### Testes O painel **Playground** oferece um **Editor** para testes. Preencha o payload manualmente: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "messages": [], "input": "", "retrievals": [], "output": "", "reference": "" } ``` Clique em **Run test** para executar o guardrail. O resultado aparece no campo **Response**. > [!NOTE] > > 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**. > [!NOTE] > > 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"]` ``: a última mensagem enviada para gerar a saída * `log["output"]` ``: a resposta gerada pelo modelo * `log["reference"]` ``: a referência usada para comparar a saída * `log["messages"]` `list`: todas as mensagens anteriores enviadas ao modelo * `log["retrievals"]` `list`: todas as recuperações da Knowledge Base A função deve retornar um **Boolean** ou um **Number**: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} def evaluate(log): return True ``` Para explicar um resultado, retorne um dict em vez de um valor simples: `{"value": , "explanation": }`. `explanation` é opcional, deve ser uma string e aparece como `reason` no painel **Output** do span do evaluator em [Traces](/docs/pt-BR/ai-studio/observability/traces.md). Ele não altera a aprovação do guardrail. Um dict com qualquer outra chave é retornado como está, sem explicação. > [!NOTE] > > 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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. > [!NOTE] > > 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. > [!NOTE] > > 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](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md). 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](/docs/pt-BR/ai-gateway/configuration/external-guardrails.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.