# 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](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md). * Leitura do guia conceitual [**“Testando o Agent Component com Datasets, Avaliações e Versionamento”**](/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm/testing-your-agent.md) 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**](/documentation/resources/pt-br/quickstarts/turn-ai-into-structured-output.md)): {% 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](/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm.md#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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/resources/pt-br/quickstarts/first-ai-testing-workflow.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.