> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Avaliações de traces

> Associe evaluators a Deployments e Agents no Toqan Router para pontuar de forma assíncrona traces de produção amostrados e monitorar a qualidade continuamente.

As avaliações de traces executam Evaluators no tráfego de produção que passa por um Deployment ou Agent. Os resultados aparecem como spans na hierarquia de [Traces](/docs/pt-BR/ai-studio/observability/traces.md), oferecendo monitoramento contínuo da qualidade sem revisão manual.

## Como funcionam as avaliações de traces

Um Evaluator associado a um Deployment ou Agent é executado em solicitações amostradas. Evaluators de entrada pontuam o prompt antes de o modelo gerar; Evaluators de saída pontuam a resposta após a geração. Ambos são executados de forma **assíncrona** e nunca bloqueiam o chamador.

Isso é diferente dos Guardrails, que são executados de forma **síncrona** e podem negar uma geração se a avaliação falhar.

> [!NOTE]
>
> Os Evaluators não são executados ao usar o painel Test no AI Studio. Invoque o Deployment pela API ou SDK para acionar os evaluators.

## Trace scrubbing e dados de evaluators

O [Trace Scrubbing](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#plugins) altera os dados armazenados nos traces. Ele não altera os dados processados por um **Evaluator** ou **Guardrail**. A verificação continua recebendo a entrada, a saída, as instruções de sistema e as variáveis originais em tempo de execução antes que seus spans sejam limpos para armazenamento.

Quando a chamada de origem limpa qualquer categoria de conteúdo (`system`, `input`, `output` ou `variables`), a política se aplica a toda a subárvore do evaluator. Todas as categorias de conteúdo são limpas juntas, porque um prompt de evaluator, uma explicação ou o `stdout` do Python podem repetir dados de qualquer uma delas. Selecionar apenas `metadata` não aciona a limpeza de conteúdo do evaluator.

| Dados do trace | Resultado armazenado |
| - | - |
| Snapshot de entrada do Evaluator | Armazenado como um objeto vazio. |
| Mensagens filhas do LLM Evaluator | Preservam a estrutura das mensagens, os papéis e os nomes das chamadas de tools, mas armazenam texto, raciocínio e argumentos de tools vazios. |
| Explicação, motivo, texto de resposta do provedor e `stdout` do Python | Removidos ou armazenados como valores vazios. |
| Veredito do Evaluator | Preserva `passed`, `value` e `type`. Preserva os campos disponíveis de pontuação, rótulo, confiança, categorias, resultado, status e ação do Guardrail. |

Por exemplo, um Evaluator booleano limpo ainda pode produzir este resultado visível:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "passed": true,
  "type": "boolean",
  "value": true
}
```

Use o veredito preservado para filtrar traces e monitorar a qualidade sem armazenar o conteúdo de origem usado para calculá-lo.

## Associar evaluators

> [tab] Agent
>
> Na configuração do Agent, adicione Evaluators como evaluators de entrada ou de saída.
>
> * **Evaluator de entrada**: avalia a entrada antes de o modelo gerar uma resposta.
> * **Evaluator de saída**: avalia a saída após a geração.
>
> Defina uma **Sample Rate** (`1` a `100`%) para controlar a porcentagem de solicitações que acionam a avaliação. Uma taxa de amostragem de `100`% avalia todas as solicitações; uma taxa de `10`% avalia uma em cada dez.
>
> Consulte Configurar Evaluators e Guardrails para ver o guia completo.

> [tab] Deployment
>
> Os Evaluators são associados a Deployments com o mesmo estágio de entrada/saída e uma **Sample Rate** de `0` a `100`%.

> [tab] Guardrail Rules
>
> Para avaliação condicional, use [Guardrail Rules](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) para definir condições baseadas em CEL que determinam quando os evaluators são executados. A avaliação pode ser acionada com base em metadados, identidade, modelo ou outros atributos da solicitação.

## Amostragem e controle de volume

Todo trace e log é coletado por completo. A amostragem decide quais avaliações e ações são executadas sobre esse tráfego, e não o que é armazenado.

| Onde a taxa é definida | Escala | O que ela controla |
| - | - | - |
| **Sample Rate** em um Evaluator associado a um Agent ou Deployment | Porcentagem: `1` a `100` em um Agent, `0` a `100` em um Deployment | A parcela de solicitações que o Evaluator pontua. Um Guardrail ignora o valor e é executado em todas as solicitações. |
| `sample_rate` em uma entrada `guardrails[]` de uma solicitação Responses | Fração, `0` a `1` | Se essa entrada é executada. Em chat completions, o mesmo campo é uma porcentagem, `0` a `100`. Consulte [Guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md#timeout). |
| **Sample Rate** em uma [Trace Automation](/docs/pt-BR/ai-studio/observability/automations.md) | Porcentagem, `0` a `100` | A parcela de spans correspondentes cuja Action é executada. |

Cada taxa é sorteada por solicitação para um Evaluator e por span para uma Automation, portanto uma taxa de 10% mantém aproximadamente uma solicitação em cada dez, e não exatamente a cada décima solicitação em sequência. A taxa se aplica ao tráfego que chega depois de salva; os resultados já registrados permanecem.

## Ver os resultados dos evaluators

Os resultados dos evaluators são associados a spans individuais dentro de um trace. Cada resultado inclui o nome do Evaluator, a pontuação ou o veredito da avaliação e o estágio da avaliação (`input` ou `output`).

Na seção [Traces](/docs/pt-BR/ai-studio/observability/traces.md), os resultados dos evaluators aparecem na hierarquia do trace junto com chamadas de LLM, invocações de tools e outros spans. Use o filtro **Evals** para restringir os traces por nome do evaluator, pontuação ou status de aprovação/reprovação.

Se um resultado de evaluator precisar de correção, passe o cursor sobre o resultado em um span e selecione o ícone de edição. Defina o valor corrigido e, opcionalmente, adicione uma explicação. As correções são gravadas de volta no span e podem ser consultadas pelo **Toqan Router MCP**.

## Criar um Evaluator

Navegue pelo Marketplace para encontrar evaluators prontos ou crie um personalizado:

* **LLM Evaluator**: usa um modelo para julgar as saídas com base em critérios definidos em um prompt.
* **Python Evaluator**: executa código Python personalizado para pontuação determinística.

Consulte Criar Evaluators para ver o guia completo.

> [card] [Trace Automations](/docs/pt-BR/ai-studio/observability/automations.md)
>
> Encaminhe automaticamente traces com pontuações baixas de evaluators para Annotation Queues.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.