> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm/testing-your-agent.md). # 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](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md), 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](/documentation/resources/pt-br/quickstarts/turn-ai-into-structured-output.md), 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](/documentation/resources/pt-br/quickstarts/turn-ai-into-structured-output.md) 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. **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:** {% 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**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm/testing-your-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.