Testando o Agent Component com Datasets e Avaliações

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.

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.

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

• 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

Você pode executar o Agent Component normalmente enquanto nenhum Dataset existir. Nesse caso, ele funciona de forma independente e não exige Experimentos nem Avaliações.

Após a criação do primeiro Dataset, o comportamento muda. O componente passa a exigir pelo menos um Experimento vinculado a um Dataset para executar. Se nenhum Experimento estiver configurado, a execução não ocorrerá.

Para retornar ao modo padrão, é necessário remover todos os Datasets.

Isso garante que, uma vez habilitado o modo de testes, as execuções permaneçam consistentes com a configuração definida.

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 Experimentos

• Múltiplas Avaliações

• Resultados de execução independentes

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 Experimentos.

2

Criar Experimentos

Um Experimento 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.

Mock de variáveis com Double Braces

Para permitir variação de cenários, o Prompt do Sistema ou do Usuário deve incluir variáveis usando a sintaxe de Double Braces, como:

{{ message.topic }}

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 Experimento, permitindo validação controlada e repetível.

Exemplo de 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

Em um Experimento, você poderia definir {{ message.topic }} como:

Arquitetura Orientada a Eventos

No momento da execução, o placeholder é substituído por esse valor.

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

Criar um Experimento

1. Abra o Dataset desejado.

2. Clique em Novo Experimento.

3. Selecione o Experimento 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 Experimentos forem necessários para simular diversidade realista de entradas.

Ao executar um Dataset, todos os Experimentos são executados em conjunto. Cada Experimento 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

Para cada Avaliação, 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 Experimento.

Limitação importante

As Avaliações validam aspectos estruturais da saída, como presença de campos, tipos de dados e regras determinísticas de valor. Elas não avaliam qualidade semântica nem precisão factual.

Por exemplo, uma Avaliação pode verificar se description não está vazia, mas não pode determinar se o conteúdo está tecnicamente correto.

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

Criar 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 será aplicada. Deve sempre começar com:

$.body

Exemplo:

$.body.title

Tipo de Scorer

Define o tipo de dado esperado:

• String

• Number

• Boolean

• Array

• Object

Variante

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

1. Clique em Criar.

Associar 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.

Definir valores esperados por Experimento

Cada Experimento deve definir o valor esperado para suas Avaliações associadas.

1. Abra o Dataset.

2. Acesse o Experimento.

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 Experimento 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 Experimentos.

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 Experimentos:

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 Experimento, incluindo status de aprovação ou reprovação e detalhes de configuração.

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.

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 Experimentos, 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 e Avaliações.