# Automatize a validação de tarefas de IA com um quality gate Este guia rápido mostra como configurar um **Agent Component** como um auditor automatizado para validar tarefas geradas por IA com base em um padrão definido e como analisar seu comportamento após a execução. ## **O que você vai construir** Você vai configurar um Agent **Avaliador** que verifica se uma lista de tarefas está correta antes do pipeline continuar. Neste exemplo: * Um **Gerador de Passos** cria tarefas para consolidar dados de vendas de várias planilhas. * O **Avaliador** compara essas tarefas com as esperadas e decide se elas passam. {% hint style="info" %} #### **Para manter o foco neste guia:** * As tarefas geradas vêm de um **Dataset.** * As tarefas esperadas são definidas diretamente na **Mensagem de Usuário**. Em um cenário real, ambas viriam de fontes externas. {% endhint %} ## **Pré-requisitos** Antes de começar, certifique-se de que você tem: * Uma API key de um provedor de LLM (por exemplo, OpenAI, Anthropic ou Google). * A API key registrada na Digibee como uma conta **Secret Key**. Para mais detalhes, consulte [como criar uma conta Secret Key](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md). * Lido o guia conceitual [**"Testando seu agente com Datasets, Avaliações e Versionamento"**](/documentation/connectors-and-triggers/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 `GPT-4o Mini` (recomendado para este guia). Este modelo foi escolhido porque tende a seguir instruções estruturadas de forma consistente, o que torna os resultados da avaliação mais previsíveis. Os resultados podem variar se você usar um modelo diferente. * **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, configure as seguintes mensagens e o JSON Schema: **Mensagem do Sistema** Esta versão é intencionalmente rígida. Você verá por que isso é um problema após a primeira execução. {% code overflow="wrap" %} ``` Você é um auditor de conformidade rigoroso. Você deve comparar as "Tarefas Esperadas" com as "Tarefas Geradas". REGRA CRÍTICA: Aceite apenas tarefas que usem exatamente a mesma terminologia ou sinônimos muito diretos. Se uma tarefa estiver descrita de forma que exija interpretação profunda ou jargão técnico não presente na lista esperada, marque-a como Ausente. Você não tem permissão para ser "flexível". Em caso de dúvida, marque como Não Aprovado. Retorne JSON: {"reasoning": "...", "answer": "..."}. ``` {% endcode %} **Mensagem do Usuário** O prompt inclui tanto as Tarefas Esperadas (fixas) quanto a variável `{{ message.agent1_output }}`, que é injetada automaticamente a partir do seu Dataset em tempo de execução. {% code overflow="wrap" %} ``` ### SOLICITAÇÃO DE AVALIAÇÃO DE TAREFAS ### **Contexto:** Consolidar dados de vendas trimestrais de três arquivos CSV em uma planilha mestre formatada. **Tarefas Esperadas (Protocolo Padrão):** 1. Mesclar os 3 arquivos CSV de origem em uma única aba principal da planilha. 2. Remover todas as linhas com IDs de Transação duplicados para garantir a integridade dos dados. 3. Converter todas as colunas de data para o formato DD/MM/AAAA. 4. Formatar a coluna "Valor Total" como moeda local (BRL/R$). 5. Criar uma aba secundária com uma Tabela Dinâmica resumindo o total de vendas por vendedor. **Tarefas Geradas pela IA (Output do Agente 1):** {{ message.agent1_output }} ### INSTRUÇÕES DE AVALIAÇÃO ### Compare as "Tarefas Geradas pela IA" com as "Tarefas Esperadas" acima. 1. Identifique tarefas **Correspondentes** (verifique a intenção funcional). 2. Identifique tarefas **Ausentes** (etapas obrigatórias não encontradas). 3. Identifique tarefas **Extras** (etapas desnecessárias). Analise com cuidado e retorne o resultado estritamente como um JSON estruturado. ``` {% endcode %} **JSON Schema** Clique no ícone de engrenagem (⚙️) ao lado de **Modelo**, ative **Usar Esquema JSON** e defina o schema abaixo. Isso garante um formato de output consistente para que seu pipeline possa sempre interpretar o resultado de forma confiável. ```json { "type": "object", "properties": { "reasoning": { "type": "string" }, "answer": { "type": "string", "enum": ["Passed", "Not Passed"] } }, "required": ["reasoning", "answer"], "additionalProperties": false } ``` ## **Passo a passo** Nas próximas etapas, você criará um Dataset mockado para simular o comportamento do Agente 1 e configurará uma Regra de Avaliação para automatizar o veredicto. {% stepper %} {% step %} ### Crie dois Casos de Teste em um Dataset Crie um novo **Dataset** com o nome `Avaliação de Precisão de Tarefas`. Dentro dele, crie dois **Casos de Teste** para simular diferentes comportamentos do Agente 1. Como sua Mensagem do Usuário contém a variável `{{ message.agent1_output }}`, cada Caso de Teste pode injetar um output gerado diferente sem modificar o prompt.
Nome do Caso de TesteValor injetado em message.agent1_outputO que testa
Consistência Semântica

- Mesclar o trio de arquivos CSV de entrada em uma única estrutura de array unificada.

- Garantir a unicidade da chave primária eliminando todos os registros de transações duplicados.

- Aplicar uma máscara derivada de ISO-8601 em todas as entradas temporais para exibição com o dia primeiro.

- Padronizar a precisão decimal conforme as especificações monetárias brasileiras (R$).

- Acrescentar uma planilha de resumo multidimensional para agregar os resultados por vendedor.

Todas as 5 tarefas estão funcionalmente corretas, mas descritas com vocabulário técnico diferente. Testa se o auditor resolve sinônimos.
Omissão Funcional

- Mesclar os três documentos fornecidos em uma única aba principal.

- Limpar o banco de dados excluindo registros com IDs duplicados.

- Garantir que todas as datas estejam no padrão DD/MM/AAAA.

- Formatar as colunas financeiras para exibir o símbolo do BRL.

- Alterar a fonte de toda a planilha para Arial e deixar os cabeçalhos em negrito.

A etapa da Tabela Dinâmica está genuinamente ausente e há uma etapa extra. Testa se o auditor identifica ambos.
{% endstep %} {% step %} ### Adicione uma Regra de Avaliação Crie uma **Avaliação** para automatizar o veredicto após cada execução: | Campo | Valor | | --------------------- | -------------------- | | **Nome da Avaliação** | `final_status_check` | | **JSONPath** | `$.body.answer` | | **Tipo de Scorer** | `STRING` | | **Operador** | `Exato` | Em seguida: 1. Clique nos três pontos ao lado da Avaliação e selecione **Adicionar ao Dataset**. Escolha o Dataset `Avaliação de Precisão de Tarefas`. 2. Abra a aba **Datasets**, acesse cada Caso de Teste criado na Etapa 1 e defina o **Valor de Avaliação** como `Passed` para ambos.
{% hint style="warning" icon="vial" %} #### **O que isso verifica?** Após cada execução, a plataforma extrai o valor em `$.body.answer` do output do Agente e compara com `Passed` usando correspondência exata. Se os valores forem iguais, o Caso de Teste passa. Se não, falha. O **Valor de Avaliação** de ambos os Casos de Teste é definido como `Passed` porque o comportamento esperado do Avaliador é aprovar as tarefas em ambos os casos. Quando os resultados reais diferirem disso, o Dataset sinalizará automaticamente a divergência. {% endhint %} {% endstep %} {% step %} ### Execute e inspecione os resultados Na aba **Datasets**, selecione `Avaliação de Precisão de Tarefas` e clique em **Executar**. Aguarde a conclusão de ambos os Test Cases. Quando o Dataset é executado: * Ambos os Casos de Teste são executados sequencialmente. * Para cada execução, a plataforma extrai o valor em `$.body.answer`. * A Avaliação verifica se ele corresponde a `Passed`. * Cada Caso de Teste é marcado como **Aprovado** ou **Falhou** independentemente.
Ambos retornarão `Not Passed`. O resultado do **Omissão Funcional** é esperado, pois uma tarefa está genuinamente ausente. Foque no **Consistência Semântica**: ele falha mesmo com todas as 5 tarefas corretas. Abra-o na aba **Execuções** para inspecionar o output: {% code overflow="wrap" %} ```json { "reasoning": "As tarefas geradas pela IA não correspondem exatamente às tarefas esperadas. Embora a intenção funcional esteja presente em algumas tarefas, a terminologia utilizada difere significativamente em várias partes, o que não atende à regra crítica de aceitar apenas a mesma terminologia ou sinônimos muito diretos. Por exemplo, \"estrutura de array unificada\" não é equivalente a \"aba principal da planilha\" e \"máscara derivada de ISO-8601\" não é a mesma coisa que \"formato DD/MM/AAAA\". Portanto, todas as tarefas geradas são consideradas como não aprovadas.", "answer": "Not Passed" } ``` {% endcode %} {% endstep %} {% endstepper %} ## **O que aprendemos?** Este é um **falso negativo**: todas as 5 tarefas estão funcionalmente corretas, mas o Avaliador as rejeitou completamente. Ele não conseguiu reconhecer terminologias diferentes, nem que "planilha de resumo multidimensional" é o mesmo que uma Tabela Dinâmica. Como o prompt compara tarefas de forma literal em vez de semântica, até outputs corretos falham. ## **Próximos passos** Você construiu e testou com sucesso um **quality gate** e identificou exatamente por que ele ainda não está pronto para produção. Pronto para corrigir? No guia [**Otimize o auditor de IA com inteligência semântica**](/documentation/resources/pt-br/quickstarts/optimize-the-ai-auditor-with-semantic-intelligence.md), você versionará o Prompt do Sistema e implementará o refinamento semântico. --- # 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/automate-ai-task-validation-with-a-quality-gate.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.