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

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 e Avaliações para verificar automaticamente se seu agente gera consistentemente os campos obrigatórios, mesmo quando o tópico muda, garantindo respostas estruturadas 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 e Avaliações” 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 estruturada em JSON.

Essa saída será consumida por sistemas downstream, portanto a consistência estrutural é essencial. 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:

{
  "$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

Passo a passo

Nos próximos passos, você criará testes estruturados para garantir que campos obrigatórios, como description, sejam sempre gerados, independentemente do tópico fornecido.

1

Crie três Experimentos 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 Experimentos para simular diferentes cenários de execução. Como sua Mensagem do Sistema contém a variável {{ message.topic }}, cada Experimento pode definir um valor diferente para ela.

Use a seguinte configuração:

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

Cada Experimento 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_exists

JSONPath $.body.description

Tipo de Scorer String

Variante

Não Vazio

Considerando que a IA foi instruída a seguir estritamente o JSON Schema definido anteriormente, essa regra verifica se o campo description está presente no JSON de saída e contém um valor não vazio.

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.

Como a operação selecionada é Não Vazio, não é necessário definir um valor esperado nos Experimentos. A Avaliação será aprovada automaticamente desde que o campo alvo exista e contenha um valor não vazio.

4

Execute o Dataset

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

Quando o Dataset for executado:

• Os três Experimentos são executados sequencialmente.

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

• A Avaliação verifica se o campo está presente e não está vazio.

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

Isso permite confirmar que o campo description é gerado consistentemente em diferentes tópicos.

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

O que isso valida

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

Mesmo que os tópicos sejam significativamente distintos, o agente deve sempre:

• Respeitar o JSON schema

• Preencher todos os campos obrigatórios

• Produzir uma string válida em description

Se algum tópico resultar em ausência do campo description, a Avaliação falhará, evidenciando imediatamente uma regressão estrutural.

Por que isso é importante

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

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

• Estabilidade do formato de saída

• Conformidade com o schema

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

Este é um exemplo simples, porém poderoso, de como Datasets e Avaliações introduzem confiabilidade mensurável em workflows orientados por IA.