Testando o Agent Component com Datasets, Avaliações e Versionamento

Aprenda como simular variações de entrada e verificar automaticamente saídas estruturadas antes de publicar em produção.

Ao desenvolver lógica orientada por IA, o comportamento do prompt precisa ser validado em múltiplas variações de entrada. Diferentemente de código determinístico, as saídas de LLM são probabilísticas e sensíveis a mudanças de contexto.

O Agent Component oferece um mecanismo estruturado de testes por meio de Datasets, Experimentos e Avaliações, permitindo validação mensurável antes do release em produção.

Consulte a documentação de configuração do Agent Component antes de testar este componente.

Quando usar Datasets e Avaliações?

Utilize essa estrutura de testes quando:

• Você quiser medir o quão preciso é o seu agente de IA.

• Você quiser comparar diferentes estratégias de implementação, como mudanças na configuração do agente ou a introdução de novas ferramentas.

• Você estiver atualizando prompts e quiser evitar regressões.

• Você precisar de validação determinística sobre saídas probabilísticas.

• Você precisar de auditabilidade antes do deploy em produção.

• Você quiser comparar diferentes versões do Agent, por exemplo, atualizações de modelo ou refatorações de prompt, usando as mesmas regras de avaliação e o mesmo dataset.

Visão conceitual

Componentes principais

A estrutura de testes é composta por três elementos centrais:

• Dataset: Conjunto de cenários de teste relacionados, organizados como uma única suíte de testes.

• Caso de Teste: Configuração de entrada definida que representa um caso de execução.

• Regras de Avaliação: Regra de validação que verifica um campo ou condição específica na saída do modelo.

Em conjunto, esses elementos permitem variar entradas de forma controlada e verificar se a saída gerada atende aos requisitos estruturais definidos.

Comportamento de execução ao usar Datasets

Antes de criar um Dataset, certifique-se de que o prompt de Sistema ou de Usuário inclua pelo menos uma variável, representada por uma expressão Double Braces. Casos de Teste só podem ser configurados quando há variáveis presentes, e os Datasets são usados para fornecer valores para essas variáveis. Por esse motivo, criar um Dataset só faz sentido quando o prompt inclui variáveis.

Por padrão, quando não existe nenhum Dataset, o componente é executado normalmente e não exige um Caso de Teste. No entanto, assim que um Dataset é criado, o modelo de execução muda: pelo menos um Caso de Teste deve ser configurado para que o componente seja executado.

Para retornar ao modo de execução original, basta remover os Datasets criados. Sem nenhum Dataset, o componente volta a ser executado normalmente e não exige um Caso de Teste.

Guia de implementação

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.

Para criar um Dataset:

1. No Agent Component, acesse a aba Datasets em Detalhes do Output.

2. Clique em Criar Dataset ou, se já existir um, clique em Selecione um Dataset e depois em Criar um novo dataset.

3. Informe um nome e confirme a criação.

O Dataset estará pronto para receber Casos de Teste.

2

Criar Casos de Teste

Um Caso de Teste representa um cenário controlado de entrada.

Em testes tradicionais de software, você variaria parâmetros ou payloads. Aqui, você varia variáveis de prompt.

Como declarar variáveis dinâmicas no prompt usando Double Braces

Agents corporativos operam com entradas recebidas de usuários ou de sistemas externos. Na Digibee Platform, essas entradas só se tornam variáveis configuráveis quando são explicitamente declaradas no prompt usando a sintaxe de Double Braces.

Uma expressão Double Braces define um placeholder de variável:

{{ message.topic }}

Essa sintaxe não é um elemento opcional de formatação. Ela é o que informa à plataforma que:

• Esse valor é dinâmico

• Esse valor pode ser injetado a partir de um Dataset

• Esse valor pode ser controlado por um Caso te Teste

Sem Double Braces, o valor é tratado como texto estático e não pode ser configurado nem testado.

Como funciona no momento da execução

Essas expressões funcionam como placeholders. Durante a execução completa do pipeline, elas capturam dados de conectores anteriores. Ao executar o Agent Component isoladamente, elas são substituídas pelos valores definidos no Caso de Teste, permitindo avaliação controlada e repetível.

Exemplo

Prompt de Usuário:

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

Valor definido no Caso de Teste

Arquitetura Orientada a Eventos

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

Isso permite avaliar como o mesmo prompt se comporta em múltiplos contextos semânticos sem modificar os conectores anteriores.

Criando um Caso de Teste

1. Abra o Dataset desejado.

2. Clique em Novo Caso de Teste.

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

4. Se existirem expressões em Double Braces no prompt, elas serão detectadas automaticamente como variáveis.

5. Informe valores para cada variável.

6. Clique em Salvar.

Você pode criar quantos Casos de Teste forem necessários para simular diversidade realista de entradas.

Ao executar um Dataset, todos os Casos de Teste são executados. Cada Caso de Teste consome tokens de forma independente e os resultados são gerados e armazenados separadamente.

3

Criar Avaliações

Como as saídas de LLM são não determinísticas, a validação não pode depender apenas de inspeção visual. As Avaliações introduzem regras objetivas aplicadas a saídas estruturadas.

O que uma Avaliação define

Cada Avaliação é configurada com um Tipo de Scorer.

Atualmente, a plataforma oferece suporte a Code Scorers, que definem regras de validação com base na inspeção estruturada da saída.

Para um Code Scorer, você configura:

• Uma expressão JSONPath, como $.body.title

• O tipo de dado esperado

• A operação de comparação, como Diferente, Contém, Não Vazio ou Começa Com

Durante a execução, a plataforma:

1. Extrai o valor usando JSONPath.

2. Aplica a operação selecionada.

3. Compara o resultado com o valor esperado, quando aplicável.

4. Marca a Avaliação como aprovada ou reprovada para cada Caso de Teste

Limitação importante

Para Code Scorers, a validação se concentra em aspectos estruturais da saída, como presença de campos, tipos de dados e regras determinísticas de valor. Eles não avaliam qualidade semântica nem precisão factual.

Por exemplo, um Code Scorer pode verificar se description não está vazio, mas não consegue determinar se o conteúdo está tecnicamente correto.

A validação estruturada aumenta a confiabilidade, mas não substitui a revisão humana quando é necessária precisão semântica.

Criando uma Avaliação

1. Abra a aba Avaliações.

2. Clique em Adicionar Avaliações.

3. Configure os seguintes campos:

Nome da Avaliação Identificador da regra. Não deve conter espaços.

JSONPath Define onde, no JSON de saída, a validação deve ser aplicada. O caminho deve sempre começar a partir do objeto body.

Usando um JSONPath quando o JSON Schema está configurado

Se um JSON Schema estiver configurado, o modelo retorna um objeto JSON estruturado dentro de body. Nesse caso, utilize:

$.body.<nome-do-campo>

Exemplo:

$.body.title

Você pode direcionar qualquer campo definido no seu schema.

Usando JSONPath quando não há JSON Schema configurado

Se nenhum JSON Schema estiver configurado, a saída do Agent é tratada como texto livre, mesmo que visualmente pareça um JSON estruturado na interface.

Nesse caso:

• Toda a resposta é tratada como uma única string.

• O único JSONPath válido é:

$.body.text

Como a saída não é interpretada como um objeto estruturado, não é possível direcionar campos individuais, como:

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

Esses caminhos retornarão null.

Sem um JSON Schema, a validação é aplicada ao output gerado como um todo. Você pode verificar condições como:

• Contém

• Não Vazio

• Começa Com

Mas não é possível validar campos específicos de forma independente.

Para validar campos individuais, é necessário configurar um JSON Schema, para que a saída seja retornada como um objeto JSON estruturado.

Tipo de Scorer Define o tipo de dado esperado:

• String

• Number

• Boolean

• Array

• Object

Operador Define a lógica de validação, de acordo com o Tipo de Scorer.

1. Clique em Criar.

Associando a Avaliação a um Dataset

Após criar a Avaliação:

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

2. Selecione Adicionar ao Dataset.

3. Escolha o Dataset de destino.

4. Clique em Adicionar.

Definindo valores esperados por Caso de Teste

Cada Caso de Teste deve definir o valor esperado para suas Avaliações associadas.

1. Abra o Dataset.

2. Acesse o Caso de Teste.

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

4. Defina o valor que o sistema deverá usar na comparação, quando necessário.

Ao executar, a plataforma avalia cada Caso de Teste de forma independente e exibe se cada regra foi aprovada ou reprovada.

4

Executar os testes

Você pode executar os testes antes ou depois de criar Avaliações. Um fluxo recomendado é:

1. Criar os Casos de Teste.

2. Executá-los para inspecionar as saídas.

3. Definir as Avaliações com base na estrutura esperada.

4. Executar novamente o Dataset para validar automaticamente os resultados de aprovação ou reprovação.

Para executar os Casos de Teste:

1. Selecione o Dataset.

2. Clique em Executar.

Após a conclusão, os resultados aparecem na aba Execuções. Clique em uma execução para visualizar os detalhes.

Detalhes da execução

Resultados do trace

Todos os traces de execução ficam agrupados aqui, oferecendo visibilidade completa do comportamento do componente. Ele incluem:

• Configuração: Configurações de provider e modelo.

• Entrada: Detalhes de contexto, configuração de tools e status de retrieval.

• Sistema: A Mensagem do Sistema enviada ao LLM.

• Usuário: A Mensagem do Usuário enviado ao LLM.

• Tool Call: Invocações de tools, argumentos e resultados.

• Input/Output Guardrail: Guardrails aplicados e seu impacto.

Esses traces auxiliam na validação de resultados e na resolução de comportamentos inesperados.

Saída

O resultado final da execução é retornado em formato JSON. Você pode inspecionar e consultar campos específicos usando expressões JSONPath.

Logs de Avaliação

Exibe os resultados das Avaliações para cada Caso de Teste, incluindo status de aprovação ou reprovação e detalhes de configuração.

Como avaliar manualmente os resultados dos testes

Você pode revisar manualmente uma execução para avaliar sua qualidade e registrar qual Dataset apresenta melhor desempenho. Isso permite comparar sua avaliação com a avaliação automática configurada usando Code Scorers.

Em cada Caso de Teste, você encontrará uma opção de avaliação. Use-a para marcar o resultado como positivo () ou negativo () com base na sua análise.

Após enviar uma avaliação, o sistema adiciona automaticamente uma coluna manual-evaluations aos detalhes da execução na aba Execuções. Essa coluna reflete sua avaliação manual e calcula uma taxa de sucesso para o Dataset com base nas avaliações realizadas.

Exemplo

Suponha que um Dataset contenha três Casos de Teste. Após revisar os resultados:

• Dois Casos de Teste são avaliados como positivos.

• Um Caso de Teste é avaliado como negativo.

O sistema calcula uma taxa de sucesso manual de 67% para esse Dataset.

Essa porcentagem é então combinada com a pontuação gerada pelos Code Scorers, oferecendo uma visão mais completa do desempenho geral do Dataset na coluna Total.

Como salvar os resultados dos testes

Todas as execuções são capturadas automaticamente na aba Execuções.

Regras de retenção:

• Salvamento automático: Execuções ficam armazenadas temporariamente por 5 dias.

• Armazenamento persistente: Para evitar exclusão após 5 dias, abra a aba Execuções, selecione as execuções desejadas e clique em Salvar.

O pipeline deve estar salvo antes que as execuções possam ser armazenadas permanentemente.

5

Versionar para experimentação controlada

Datasets e Avaliações validam a estrutura da saída. O versionamento permite evolução controlada. Quando usados em conjunto, formam um framework de experimentação reproduzível para o desenvolvimento de Agents, no qual mudanças podem ser medidas em vez de presumidas.

Saiba como versionar o Agent Component.

Reutilizando o mesmo Dataset entre versões

Um único Dataset pode ser reutilizado para avaliar múltiplas configurações de Agent. Isso garante que apenas a configuração mude, enquanto os critérios de teste permanecem constantes.

Por exemplo:

• v1 → Modelo: gpt-4o

• v2 → Modelo: gpt-5

• v3 → Prompt de sistema atualizado

Todas as versões são executadas com os mesmos Casos de Teste, Avaliações e lógica de validação. Isso isola o impacto de cada alteração e permite comparação objetiva entre iterações.

Abordagem recomendada de avaliação

1. Comece de forma simples Itere em um único prompt sem salvar versões. Resolva problemas de especificação refinando instruções, estrutura ou restrições no prompt.

2. Crie uma versão de referência quando necessário Ao identificar problemas de generalização que exijam comparação estruturada, salve o prompt atual como uma versão. Coloque uma tag para a sua versão de referência, como por exemplo “main” (principal) ou “latest” (mais recente).

3. Teste alternativas Experimente novas configurações de prompt para resolver o problema. Salve versões apenas quando necessário. Se uma configuração apresentar desempenho superior à versão de referência, promova-a como sua nova versão principal ou mais recente.

4. Valide de forma consistente Use o mesmo Dataset para testar diferentes versões. Manter as condições de teste constantes permite uma comparação confiável.

Aplique a mesma estratégia sempre que atualizar o Dataset ou as métricas de avaliação: defina uma versão de referência estável, teste alternativas nas mesmas condições e promova melhorias quando forem validadas.

Por que esse teste é importante

Saídas de LLM são inerentemente probabilísticas. Um prompt que funciona em um domínio semântico pode degradar em outro.

Ao combinar variação de entrada por meio de Casos de Teste, organização estruturada com Datasets e regras determinísticas de validação com Avaliações, você introduz:

• Estabilidade no formato de saída

• Conformidade com schema

• Detecção antecipada de regressões

• Auditabilidade de execuções

• Fluxos de validação reproduzíveis

Isso transforma prompt engineering de inspeção manual em testes estruturados, aproximando workflows de IA dos padrões tradicionais de qualidade de software.

Próximos passos

Agora que você entende o modelo conceitual e o processo de implementação, aprenda a criar seu primeiro workflow de testes de IA utilizando Datasets, Avaliações e Versionamento.