Automatize a validação de tarefas de IA com um quality gate

Aprenda a construir um agente que avalia uma lista de tarefas e classifica se elas atendem aos critérios definidos.

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.

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.

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.

• Lido o guia conceitual "Testando seu agente com Datasets, Avaliações e Versionamento" 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.

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": "..."}.

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.

### 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.

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.

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

1

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.

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.

2

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.

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.

3

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:

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

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, você versionará o Prompt do Sistema e implementará o refinamento semântico.