# Construa seu primeiro workflow de testes de IA com Datasets, Avaliações e Versionamento 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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts). * Leitura do guia conceitual [**“Testando o Agent Component com Datasets, Avaliações e Versionamento”**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/ai-tools/llm/testing-your-agent) 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: {% code overflow="wrap" %} ``` 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. ``` {% endcode %} #### **Mensagem do Usuário** Define a tarefa dinâmica e introduz uma variável: {% code overflow="wrap" %} ``` 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. ``` {% endcode %} 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**](https://docs.digibee.com/documentation/resources/pt-br/quickstarts/turn-ai-into-structured-output)): {% code overflow="wrap" expandable="true" %} ```json { "$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 } ``` {% endcode %} Esse schema impõe: * Campos estruturais obrigatórios * Restrições mínimas de conteúdo * Controle estrito de propriedades, sem campos inesperados {% hint style="warning" icon="lightbulb-on" %} **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. {% endhint %} ## **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. {% stepper %} {% step %} ### **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. {% endstep %} {% step %} ### **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. {% endstep %} {% step %} ### **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. {% hint style="info" %} 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. {% endhint %} {% endstep %} {% step %} ### **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**. {% endstep %} {% step %} ### 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](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/ai-tools/llm#versionando-o-componente) 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: {% code overflow="wrap" %} ``` 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. ``` {% endcode %} 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. {% endstep %} {% endstepper %} ## **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.