# 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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts). * Lido o guia conceitual [**"Testando seu agente com Datasets, Avaliações e Versionamento"**](https://app.gitbook.com/s/EKM2LD3uNAckQgy1OUyZ/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 `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**](https://docs.digibee.com/documentation/resources/pt-br/quickstarts/optimize-the-ai-auditor-with-semantic-intelligence), você versionará o Prompt do Sistema e implementará o refinamento semântico.