Construa seu primeiro workflow de testes de IA com Datasets, Avaliações e Versionamento

Crie um workflow funcional de testes de IA que valide saídas JSON estruturadas em múltiplas variações de entrada.

Este guia rápido mostra como usar Datasets, Avaliações e Versionamento para verificar automaticamente se seu agente gera saídas estruturadas de forma consistente e mantém o conteúdo gerado alinhado ao tópico de entrada, garantindo respostas confiáveis e prontas para produção.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

• Uma chave de API de um provedor de LLM (por exemplo, OpenAI, Anthropic ou Google).

• A chave de API cadastrada na Digibee como uma conta do tipo Secret Key. Para mais detalhes, consulte como criar uma conta Secret Key.

• Leitura do guia conceitual “Testando o Agent Component com Datasets, Avaliações e Versionamento” para entender a estrutura de testes e a terminologia usada neste guia.

Configuração inicial

Adicione o Agent Component ao seu pipeline imediatamente após o trigger e configure-o da seguinte forma:

• Modelo: Selecione o modelo de sua preferência (por exemplo, OpenAI – GPT-4o Mini).

• Conta: Clique no ícone de engrenagem ao lado do parâmetro Modelo, vá em Conta e selecione a conta Secret Key que você criou na Digibee.

Após concluir a configuração básica, você estará pronto para configurar seus testes.

Cenário

Você está construindo um agente de IA que converte informações técnicas recuperadas em documentação JSON estruturada.

Essa saída será consumida por sistemas downstream, portanto a consistência estrutural e o alinhamento com o tópico são essenciais. Até mesmo um campo ausente pode quebrar integrações determinísticas.

Para garantir confiabilidade, configure o Agent com as seguintes mensagens e JSON schema:

Mensagem do Sistema

Define o papel e o tom do agente:

Você é um gerador de documentação técnica. Escreva sempre em português claro e conciso, usando um tom profissional, porém simples.
Sua tarefa é transformar informações brutas obtidas de ferramentas externas em documentação bem estruturada.
Assegure-se de que seu trabalho seja consistente, preciso e esteja alinhado com o formato solicitado.

Mensagem do Usuário

Define a tarefa dinâmica e introduz uma variável:

Utilize as informações obtidas 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.
Formate a resposta seguindo rigorosamente o JSON Schema fornecido.

A variável {{ message.topic }} permite simular diferentes contextos semânticos sem modificar a estrutura do prompt. Isso a torna ideal para testes controlados em múltiplos cenários.

JSON Schema

Defina o schema de saída (saiba mais sobre como transformar respostas de IA em uma saída JSON estruturada):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "DocumentationSection",
  "type": "object",
  "required": ["title", "description", "use_cases", "best_practices"],
  "properties": {
    "title": {
      "type": "string",
      "description": "O título da seção de documentação"
    },
    "description": {
      "type": "string",
      "description": "Uma descrição concisa do tópico (2-3 frases)"
    },
    "use_cases": {
      "type": "array",
      "description": "Casos de uso práticos para o tópico",
      "items": {
        "type": "string"
      },
      "minItems": 3
    },
    "best_practices": {
      "type": "array",
      "description": "Boas práticas recomendadas para o tópico",
      "items": {
        "type": "string"
      },
      "minItems": 3
    }
  },
  "additionalProperties": false
}

Esse schema impõe:

• Campos estruturais obrigatórios

• Restrições mínimas de conteúdo

• Controle estrito de propriedades, sem campos inesperados

Dica: Habilite o guardrail JSON Schema nas Configurações de Guardrails. O Agent valida a saída do modelo com base no schema definido e automaticamente envia um novo prompt ao LLM se o formato da resposta for inválido. Se o modelo continuar retornando uma saída inválida, a execução falha.

Passo a passo

Nos próximos passos, você criará testes estruturados para garantir que a description gerada permaneça relevante para o tópico testado.

1

Crie três Casos de Teste em um Dataset

Crie um novo Dataset, que é um agrupamento lógico de cenários de teste, e nomeie-o como Validador de Documentação.

Dentro desse Dataset, crie três Casos de Teste para simular diferentes cenários de execução. Como sua Mensagem do Sistema contém a variável {{ message.topic }}, cada Caso de Teste pode definir um valor diferente para ela.

Use a seguinte configuração:

Casos de Teste	message.topic
Caso de Teste 1	Arquitetura Orientada a Eventos
Caso de Teste 2	Limitação de Taxa de API
Caso de Teste 3	Indexação de Banco de Dados

Cada Caso de Teste simula um domínio semântico diferente mantendo a estrutura do prompt inalterada. Isso permite validar a consistência estrutural em contextos variados.

2

Crie a regra de Avaliação

Agora que seu Dataset está configurado, crie uma Avaliação, que é uma regra automatizada que valida parte da saída do modelo, com a seguinte configuração:

Nome da Avaliação description_contem

JSONPath $.body.description

Tipo de Scorer String

Operador

Contém

Essa regra verifica se o campo description contém uma palavra-chave relacionada ao tópico solicitado. Isso permite que o teste confirme se o conteúdo gerado está semanticamente alinhado com o tópico de entrada.

3

Associe a Avaliação ao Dataset

Após criar a Avaliação, clique nos três pontos ao lado dela e selecione Adicionar ao Dataset. Em seguida, escolha o Dataset criado no Passo 1.

Para configurar os resultados esperados:

1. Abra o dataset Validador de Documentação na aba Datasets.

2. Abra cada Caso de Teste e role até a seção Avaliações.

3. Insira o valor esperado.

Para nossos Casos de Teste, adicione os seguintes valores:

Casos de Teste	Valor da Avaliação
Caso de Teste 1	eventos
Caso de Teste 2	API
Caso de Teste 3	dados

Assim, será possível validar se os Casos de Teste estão retornando os assuntos solicitados.

Tenha em mente que o operador “Contém” é case sensitive. Isso significa que a verificação considera diferenças entre letras maiúsculas e minúsculas. Portanto, mesmo que o termo esperado esteja presente, se a capitalização estiver diferente da configurada, a avaliação pode não ser aprovada.

4

Execute o Dataset

Na aba Datasets, selecione seu Dataset e clique em Executar.

Quando o Dataset for executado:

• Os três Casos de Teste são executados sequencialmente.

• Para cada execução, a plataforma extrai o valor em $.body.description.

• A Avaliação verifica se a description contém a palavra-chave esperada definida no Caso de Teste.

• Cada Caso de Teste é avaliado de forma independente e marcado como Aprovado ou Falhou.

Isso permite confirmar que a description gerada permanece semanticamente alinhada com o tópico em diferentes entradas.

Você pode consultar informações mais detalhadas sobre cada execução na aba Execuções.

5

Compare diferentes versões de configuração de prompt

Agora que seu Dataset valida tanto a consistência estrutural quanto a qualidade da resposta, você pode refinar iterativamente o prompt para resolver problemas de especificação identificados pelas regras de validação. Quando o prompt funcionar conforme esperado para os casos definidos, evolua o prompt de forma controlada e meça seu impacto.

Quando surgirem problemas de generalização, salve a versão atual do prompt e compare seus resultados com configurações alternativas.

1. Salve a versão baseline

Abra o Agent Component e salve a configuração atual como uma versão chamada baseline.

Essa versão preserva os prompts originais (Sistema e Usuário) e serve como seu ponto de referência estrutural.

2. Modifique o Prompt de Usuário para exigir maior concisão

Substitua a Mensagem de Usuário atual pelo seguinte:

Use as informações recuperadas sobre o tópico {{ message.topic }} para gerar uma seção de documentação estruturada.
Requisitos:
- Forneça um título curto e preciso.
- Inclua pelo menos três casos de uso práticos. Cada caso de uso deve ser uma única frase direta.
- Inclua pelo menos três boas práticas. Cada boa prática deve ser uma única frase acionável.
Evite explicações genéricas. Não adicione introduções ou comentários fora dos campos obrigatórios.
Formate a resposta estritamente de acordo com o JSON schema fornecido.

Essa modificação remove a instrução explícita sobre o campo description do prompt, mantendo-o obrigatório apenas no JSON Schema.

Como resultado:

• O prompt deixa de reforçar o campo no nível da instrução.

• O JSON Schema passa a ser a única restrição que garante a presença do campo description, enquanto a regra de Avaliação valida seu conteúdo semântico.

Isso aumenta a pressão das restrições e permite validar se apenas a aplicação do schema é suficiente para manter a estabilidade estrutural e respostas consistentes em diferentes tópicos.

3. Salve a nova configuração

Salve essa configuração atualizada como uma nova versão e adicione a tag conciso.

Agora você possui duas configurações comparáveis:

• baseline: Reforço do campo description no prompt.

• conciso: Validação apenas no nível do schema.

4. Execute novamente o mesmo Dataset

Vá até a aba Datasets e execute novamente o Validador de Documentação.

Como o Dataset, os Casos de Teste e a regra de Avaliação permanecem inalterados, qualquer diferença de comportamento refletirá apenas a modificação do prompt.

O que observar

Compare as versões baseline e conciso:

• O campo description ainda é gerado com conteúdo relevante para o tópico solicitado?

• Todos os Casos de Teste passam na avaliação?

• O agente mantém respostas consistentes e precisas em diferentes tópicos?

• Remover o reforço no prompt introduziu alguma regressão estrutural ou semântica?

• A saída ficou mais concisa mantendo total conformidade com o schema?

Se algum Test Case falhar, você terá identificado uma regressão causada exclusivamente pela mudança no prompt.

Este exercício demonstra que o Versionamento não se limita à troca de modelos. Ele permite experimentação controlada com qualquer configuração do Agent Component, incluindo prompts, seleção de modelo, parâmetros como temperatura e top K, JSON Schema, tools e uploads de arquivos.

Isso permite medir resultados de validação e testar novos Casos de Teste com segurança, sem afetar pipelines em produção. Em vez de assumir qual prompt funciona melhor, você valida a consistência do agente e a precisão das respostas sob condições de teste idênticas.

O que isso valida

Este experimento confirma a consistência estrutural em diferentes variações semânticas.

Mesmo que os tópicos sejam bastante diferentes, o agente deve sempre:

• Respeitar o JSON schema.

• Preencher todos os campos obrigatórios.

• Gerar uma description que contenha uma palavra-chave relacionada ao tópico.

Se algum tópico resultar em uma description ausente, a avaliação falhará, revelando imediatamente uma regressão estrutural.

Por que isso é importante

As saídas de LLMs são probabilísticas. Um prompt que funciona bem para um tópico pode degradar para outro.

Ao testar múltiplos contextos semânticos com uma única regra estrutural, você garante:

• Consistência do agente em diferentes entradas

• Precisão e relevância das respostas

• Estabilidade do formato de saída e conformidade com o schema

• Detecção de regressões quando prompts ou configurações são modificados

Este é um exemplo simples, mas poderoso, de como Datasets e Evaluations introduzem confiabilidade mensurável em fluxos de trabalho baseados em IA.