Construindo testes no Agent: Datasets, Casos de Teste e Avaliações

Defina entradas, estruture testes e configure regras de avaliação antes de executá-los.

Visão geral

O Agent Component inclui uma estrutura de testes composta por Datasets, Casos de Teste e Avaliações. Esses elementos permitem testar diferentes entradas de forma controlada e verificar se as saídas atendem aos seus requisitos antes de ir para produção.

Use essa estrutura quando quiser:

• Verificar a precisão do seu agente de IA com diferentes entradas.

• Comparar diferentes abordagens, como mudanças de prompt ou novas ferramentas.

• Evitar regressões ao atualizar prompts.

• Comparar diferentes versões do Agente usando os mesmos testes.

• Garantir que tudo esteja validado antes de fazer o deploy em produção.

Conceitos fundamentais

• Dataset: Um grupo de cenários de teste relacionados, organizados como uma única suíte de testes. Cada Dataset contém Casos de Teste e Avaliações.

• Caso de Teste: Uma configuração de entrada específica que representa um cenário de execução. Define os valores para as variáveis usadas no seu prompt.

• Avaliação: Uma regra usada para verificar um campo ou condição específica na saída do modelo. Ela é vinculada a um Dataset e executada para cada Caso de Teste.

Pré-requisitos

Antes de criar um Dataset, o seu prompt de Sistema ou de Usuário deve conter pelo menos uma variável declarada com a sintaxe de Double Braces, por exemplo:

{{ message.topic }}

Isso informa à plataforma que o valor é dinâmico e pode ser injetado a partir de um Caso de Teste. Sem o uso de Double Braces, os valores são tratados como texto estático e não podem ser configurados nem testados.

Após a criação de um Dataset, pelo menos um Caso de Teste deve ser configurado para que o componente possa ser executado. Para voltar ao modo de execução normal, remova todos os Datasets.

Etapa 1: Criar um Dataset

Um Dataset funciona como uma suíte de testes para o seu agente. Cada Dataset pode conter múltiplos Casos de Teste e Avaliações.

1. No Agent Component, navegue até a aba Datasets em Detalhes da saída.

2. Clique em Criar Dataset (ou clique em Selecionar Dataset e depois em Criar um novo Dataset, caso já exista um).

3. Forneça um nome e confirme.

Etapa 2: Criar Casos de Teste

Um Caso de Teste fornece valores para as variáveis declaradas no seu prompt, simulando um cenário de entrada específico.

Exemplo

Dado este prompt de Usuário:

Use as informações recuperadas sobre {{ message.topic }} para criar uma seção de documentação.
A documentação deve incluir:
- Um título claro
- Uma descrição concisa (2–3 frases)
- Pelo menos três casos de uso práticos
- Pelo menos três boas práticas

Um Caso de Teste forneceria:

Arquitetura Orientada a Eventos

No momento da execução, {{ message.topic }} é substituído por esse valor.

Criando um Caso de Teste:

1. Abra o Dataset e clique em Novo Caso de Teste.

2. Selecione o Caso de Teste recém-criado.

3. Forneça valores para cada variável detectada.

4. Clique em Salvar.

Você pode criar quantos Casos de Teste forem necessários para simular uma diversidade realista de entradas. Ao executar um Dataset, todos os Casos de Teste são executados de forma independente, e cada um consome tokens separadamente.

Etapa 3: Criar Avaliações

Uma Avaliação é uma regra que verifica automaticamente se a saída gerada pelo seu Agente atende a um critério específico. Por exemplo, se um campo está preenchido, se a resposta contém determinada palavra ou se o tom está adequado.

Em vez de revisar cada saída manualmente, você define a regra uma vez e o sistema a aplica automaticamente em todos os seus Casos de Teste.

Criando uma Avaliação:

1. Abra a aba Avaliações.

2. Clique em Adicionar Avaliações.

3. Preencha os campos descritos na próxima seção.

Configurando os campos da Avaliação

Nome da Avaliação

Um rótulo para identificar esta regra de avaliação. Escolha algo descritivo, como titulo_nao_vazio ou verificacao_tom.

O nome não pode conter espaços. Use underscores ou hífens (por exemplo, verificar-descricao).

JSONPath: Indicando ao sistema onde procurar

Quando o seu Agente gera uma resposta, ela é armazenada internamente como um objeto estruturado chamado body. O JSONPath é o endereço que você escreve para indicar ao sistema qual parte dessa resposta você deseja avaliar.

Pense nisso como apontar para uma célula em uma planilha: em vez de dizer "coluna B, linha 3", você escreve um caminho como $.body.title para indicar "o campo title dentro de body."

O caminho sempre começa com $.body, seguido pelo nome do campo que você deseja verificar.

Quando um JSON Schema está configurado

Se o seu Agente está configurado com um JSON Schema, sua saída é estruturada, ou seja, cada informação é armazenada em um campo nomeado. Nesse caso, você pode apontar para qualquer campo específico:

$.body.title
$.body.description
$.body.use_cases

Cada caminho aponta para um campo, e cada campo pode ter sua própria regra de avaliação independente.

Quando nenhum JSON Schema está configurado

Se nenhum JSON Schema estiver configurado, toda a saída do Agente é tratada como um bloco único de texto, mesmo que visualmente pareça um JSON estruturado na interface. Nesse caso, o sistema não reconhece campos individuais, e o único caminho válido é:

$.body.text

Isso significa que você só pode avaliar a resposta como um todo. Caminhos como $.body.title ou $.body.description retornarão vazio (null), pois não existem campos nomeados para apontar.

Em resumo: Se você precisar validar campos específicos de forma independente, é necessário configurar um JSON Schema para o seu Agente. Sem ele, só é possível validar toda a saída de uma vez.

Tipo de Scorer: Como a avaliação vai julgar a saída

O Tipo de Scorer define que tipo de verificação será realizada no campo selecionado. Existem duas categorias: scorers determinísticos e o scorer LLM.

Scorers determinísticos: String, Número, Booleano, Array, Objeto

São usados quando a verificação tem uma resposta clara e objetiva, sem ambiguidade. O sistema compara a saída com uma regra e retorna aprovado ou reprovado automaticamente, sem nenhuma interpretação.

Escolha o tipo que corresponde ao conteúdo do campo:

Tipo	Use quando o campo contiver…	Exemplo
String	Texto	Um título, uma descrição, um nome
Número	Um valor numérico	Uma pontuação, uma contagem, um preço
Booleano	Verdadeiro ou falso	Se uma flag está ativada
Array	Uma lista de itens	Uma lista de tags ou categorias
Objeto	Uma estrutura aninhada	Um endereço com vários subcampos

Após escolher o tipo, você configura um Operador, que é a lógica da verificação em si. Os operadores disponíveis dependem do tipo selecionado, mas exemplos comuns incluem:

• Não Vazio: Verifica se o campo possui algum conteúdo (qualquer conteúdo).

• Contém: Verifica se o campo inclui uma palavra ou frase específica.

• Começa Com: Verifica se o campo começa com uma string específica.

• Diferente: Verifica se o valor é diferente de algo específico.

Limitação importante: Os scorers determinísticos só conseguem verificar se um campo tem conteúdo ou corresponde a um padrão, não se esse conteúdo é realmente bom. Por exemplo, Não Vazio será aprovado mesmo que a descrição diga "aaa" ou contenha texto sem sentido. Para avaliar qualidade, relevância ou tom, use o scorer LLM.

Ao configurar um Operador, você não definirá o valor esperado aqui. Esse valor é definido individualmente para cada Caso de Teste, conforme descrito em Definindo valores esperados por Caso de Teste.

Scorer LLM

Use o scorer LLM quando a avaliação exigir julgamento, algo que uma regra simples não consegue determinar. Esta é a escolha certa para verificar coisas como:

• O tom é profissional?

• A resposta realmente responde à pergunta do usuário?

• A informação é factualmente precisa?

• O conteúdo é relevante para o contexto?

Em vez de uma regra fixa, você fornece um prompt que instrui um modelo de linguagem a agir como juiz. O modelo lê a saída do Agente e decide se ela é aprovada ou reprovada com base nos seus critérios.

Configure os seguintes campos:

• Modelo LLM: O modelo que atuará como juiz. O modelo selecionado deve suportar saída estruturada (JSON Schema). Clique em Abrir configurações para ajustar parâmetros como a conta utilizada, temperatura e outras configurações avançadas.

• Prompt: É aqui que você define o que significa "ser aprovado". Você pode usar nossos Templates disponíveis como guia ou escrever livremente instruções claras e específicas para o modelo juiz.

Usando variáveis no prompt

Você pode referenciar valores dinâmicos no seu prompt usando variáveis. Isso permite que o modelo juiz avalie o output do Agent com contexto, em vez de avaliá-lo de forma isolada.

As seguintes variáveis estão disponíveis para serem inseridas diretamente no seu prompt:

• {{agent.userPrompt}}: Referencia o prompt de Mensagem de Usuário configurado no Agent.

• {{agent.systemPrompt}}: Referencia o prompt de Mensagem de Sistema configurado no Agent.

• {{experiment.sua-variavel}}: Uma variável declarada diretamente no prompt do LLM scorer. Após o eval ser atribuído a um Dataset, você pode definir um valor para cada variável experiment. nos Casos de Teste. O LLM scorer então utiliza esses valores no momento da avaliação, para que o modelo juiz avalie cada caso com o contexto correto. Alguns templates já incluem variáveis experiment. predefinidas para ajudar você a começar.

Diretrizes para escrever um prompt eficaz

• Seja explícito sobre a condição de aprovação/reprovação. Evite instruções vagas como "verifique se está bom". Escreva exatamente o que é necessário para ser aprovado.

• Inclua exemplos do que seria uma aprovação e uma reprovação.

• Liste cada condição separadamente se múltiplos critérios precisarem ser atendidos.

• Exclua fatores irrelevantes. Se formatação ou comprimento não devem afetar o resultado, diga isso explicitamente; caso contrário, o modelo pode levá-los em consideração.

Exemplo:

Você está avaliando se a resposta aborda diretamente a pergunta do usuário.
Aprovado se: a resposta responde à pergunta específica feita.
Reprovado se: a resposta é genérica, evasiva ou responde a uma pergunta diferente.
Não penalize por formatação ou comprimento.

O scorer LLM sempre retornará um de dois vereditos: Aprovado ou Reprovado. Em Definindo valores esperados por Caso de Teste, você configurará qual veredito é esperado para cada Caso de Teste.

Vinculando a Avaliação a um Dataset

Uma regra de Avaliação, por si só, não é executada automaticamente. Ela precisa ser vinculada a um Dataset (a coleção de Casos de Teste contra os quais o Agente será testado).

Para vincular uma Avaliação:

1. Clique no menu de três pontos ao lado do nome da avaliação.

2. Selecione Adicionar ao Dataset e escolha o Dataset de destino.

3. Clique em Adicionar.

Uma vez vinculada, a Avaliação será aplicada a todos os Casos de Teste daquele Dataset.

Definindo valores esperados por Caso de Teste

Cada Caso de Teste pode ter seu próprio resultado esperado para uma determinada Avaliação. É aqui que você define o que "correto" significa para aquele caso específico.

Para configurar:

1. Abra o Dataset e navegue até o Caso de Teste.

2. Vá até a seção Avaliações.

3. Defina o valor esperado com base no tipo de scorer:

• Para scorers String, Número, Booleano, Array ou Objeto: Insira o valor exato que a saída deve corresponder para que o teste seja aprovado. Por exemplo, se o operador for Contém e você estiver testando uma descrição de produto, pode inserir o nome do produto como valor esperado.

• Para o scorer LLM: Selecione se você espera que o resultado seja Aprovado ou Reprovado para este caso específico. Por exemplo, se você estiver testando uma entrada sabidamente incorreta, pode esperar o veredito "Reprovado" — e a avaliação será considerada bem-sucedida se o modelo juiz concordar.

Próximos passos

Agora que você sabe como criar testes, o próximo passo é executar os testes, analisar os resultados e gerenciar versões.