# Construindo testes no Agent: Datasets, Casos de Teste e Avaliações ## **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](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview), 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: {% code overflow="wrap" %} ``` 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 ``` {% endcode %} 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`. {% hint style="warning" %} O nome não pode conter espaços. Use underscores ou hífens (por exemplo, `verificar-descricao`). {% endhint %} #### **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](https://app.gitbook.com/s/XfrDexGOLMin51pAiWkq/quickstarts/turn-ai-into-structured-output), 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](https://app.gitbook.com/s/XfrDexGOLMin51pAiWkq/quickstarts/turn-ai-into-structured-output) 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. {% hint style="info" %} **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. {% endhint %}
#### **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. {% hint style="warning" %} **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. {% endhint %} 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**](#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. 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:** {% code overflow="wrap" %} ``` 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. ``` {% endcode %} O scorer LLM sempre retornará um de dois vereditos: **Aprovado** ou **Reprovado**. Em [**Definindo valores esperados por Caso de Teste**](#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**.