Criar um conjunto de dados de avaliação (versão prévia)

O otimizador do agente avalia seu agente em relação a um conjunto de dados – uma coleção de tarefas com critérios de avaliação. Você pode gerar um conjunto de dados automaticamente da CLI ou criar um manualmente para controle total.

Pré-requisitos

• Um projeto da Foundry com um agente hospedado implantado
• A azure.ai.agents extensão da CLI instalada (consulte Início Rápido: Otimizar um agente hospedado)

Gerar um conjunto de dados (recomendado)

A maneira mais rápida de criar um conjunto de dados de avaliação é com azd ai agent eval init. Esse comando gera um conjunto de dados e avaliadores adaptáveis ajustados ao domínio do agente:

azd ai agent eval init

O assistente interativo detecta automaticamente seu agente a partir de azure.yaml e solicita uma instrução de geração que descreva o que seu agente faz e quais cenários testar.

Exemplo de saída:

Detecting agent...
  Found: my-support-agent (hosted)

Generation prompt
  Describe what this agent does and what scenarios to test.
  > This agent handles customer support for electronics. Test returns, troubleshooting, and out-of-scope requests.

Generating dataset and evaluators...
  Dataset generation:    done  (registered: my-support-agent-eval-seed/v1)
  Evaluator generation:  done  (registered: my-support-agent-quality/v1)

Eval suite created
  Config:     eval.yaml
  Dataset:    .azure/.foundry/datasets/my-support-agent-eval-seed.v1.jsonl
  Evaluator:  .azure/.foundry/evaluators/my-support-agent-quality.v1.yaml

Review the generated assets, then run:
  azd ai agent eval run

Modo não interativo

Para fluxos de trabalho com script, passe as entradas diretamente:

azd ai agent eval init \
  --gen-instruction "Customer support agent. Test refund handling, troubleshooting, and out-of-scope deflection." \
  --eval-model gpt-4.1-mini \
  --max-samples 50

Use seus próprios dados com avaliadores gerados

Se você já tiver um conjunto de dados dourado, mas quiser avaliadores gerados automaticamente:

azd ai agent eval init --dataset ./my-golden-dataset.jsonl

Executar a otimização com a configuração gerada

Após a conclusão de eval init, azd ai agent optimize detecta automaticamente o eval.yaml gerado:

azd ai agent optimize

Ou passe-o explicitamente:

azd ai agent optimize --config eval.yaml

Para obter o fluxo de trabalho completo da CLI de avaliação, consulte Executar avaliações do agente com a CLI do azd.

Criar um conjunto de dados personalizado manualmente (avançado)

Para obter controle total sobre tarefas e critérios de avaliação, crie um conjunto de dados JSONL manualmente. Isso é útil quando você precisa de controle preciso sobre cenários de teste ou tem dados de produção para usar diretamente.

Por padrão, azd ai agent optimize usa um conjunto de dados interno com três tarefas gerais de codificação e 25 critérios. Para otimização significativa de seu agente específico, crie um conjunto de dados personalizado que reflita os casos de uso do seu agente no mundo real.

Formato do conjunto de dados

Os conjuntos de dados usam o formato JSONL (Linhas JSON). Cada linha é um objeto JSON que representa uma única tarefa de avaliação. Uma tarefa é um cenário individual no conjunto de dados. Ele contém um prompt e critérios de avaliação.

{"name": "task_1", "prompt": "Your prompt here", "criteria": [{"name": "criterion_name", "instruction": "What the evaluator checks for"}]}
{"name": "task_2", "prompt": "Another prompt", "criteria": [{"name": "check_1", "instruction": "..."}, {"name": "check_2", "instruction": "..."}]}

Referência de campo

Exemplo: agente de suporte ao cliente

{"name": "refund_policy", "prompt": "What is your refund policy?", "criteria": [{"name": "mentions_30_days", "instruction": "Response must mention the 30-day refund window"}, {"name": "polite_tone", "instruction": "Response must be professional and empathetic"}]}
{"name": "order_status", "prompt": "Where is my order #12345?", "criteria": [{"name": "asks_for_details", "instruction": "Agent should ask for email or order details to look up the order"}, {"name": "no_hallucination", "instruction": "Agent must NOT make up a fake order status"}]}
{"name": "out_of_scope", "prompt": "Can you help me fix my car?", "criteria": [{"name": "polite_decline", "instruction": "Agent should politely explain this is outside its scope"}, {"name": "redirect", "instruction": "Agent should suggest contacting an appropriate service"}]}

Exemplo: Assistente de codificação

{"name": "python_function", "prompt": "Write a Python function to reverse a linked list", "criteria": [{"name": "correct_algorithm", "instruction": "The function must correctly reverse a singly linked list"}, {"name": "handles_empty", "instruction": "The function must handle an empty list without errors"}, {"name": "includes_docstring", "instruction": "The function should include a descriptive docstring"}]}
{"name": "explain_concept", "prompt": "Explain what a closure is in JavaScript", "criteria": [{"name": "accurate_definition", "instruction": "Must correctly define a closure as a function that captures variables from its enclosing scope"}, {"name": "includes_example", "instruction": "Must include at least one working code example"}]}

Usar um conjunto de dados personalizado

Faça referência ao conjunto de dados em um arquivo de configuração YAML:

# eval.yaml
agent:
  name: my-agent

dataset_file: ./my_eval_dataset.jsonl

evaluators:
  - builtin.task_adherence

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1
  max_iterations: 10

Em seguida, execute:

azd ai agent optimize --config eval.yaml

Antes de executar o comando, valide a sintaxe JSONL:

python -c "import json; [json.loads(l) for l in open('my_eval_dataset.jsonl')]"

Dicas para escrever bons conjuntos de dados

Ser específico em critérios

Ruim:

{"name": "good_answer", "instruction": "The response should be good"}

Bom:

{"name": "mentions_30_days", "instruction": "Response must explicitly mention the 30-day refund window"}

Critérios específicos dão ao avaliador um sinal binário claro. Critérios vagos levam a pontuação inconsistente.

Incluir casos extremos

Teste além do caminho feliz. Inclua:

• Solicitações fora do escopo — as entradas que seu agente deve recusar ou redirecionar
• Consultas ambíguas – tarefas em que o agente deve pedir esclarecimentos
• Entradas adversariais — Tentativas de enganar o agente a se comportar mal
• Tarefas de várias etapas – solicitações complexas que exigem raciocínio estruturado

Diretrizes de tamanho

Cada tarefa pode ter vários critérios. Um conjunto de dados com 5 tarefas × 4 critérios cada = 20 sinais de avaliação.

Escreva prompts como usuários reais

Use mensagens reais de seus usuários, se possível. Os prompts reais capturam o vocabulário e o contexto que seu agente enfrenta na produção.

Os critérios são pontuados independentemente

Cada critério obtém uma pontuação binária (0 ou 1). A pontuação da tarefa é a média das pontuações dos critérios. A pontuação geral é a média em todas as tarefas. Isso significa que:

• Uma tarefa com 4 critérios em que 3 aprovados resultam em 0,75
• Um agente que passa todos os critérios em 2 de 3 tarefas pontua 0,67

A verdade básica é opcional

O groundTruth campo fornece uma resposta de referência para avaliadores que dão suporte a ele. Este campo não é obrigatório. O builtin.task_adherence avaliador funciona inteiramente a partir de instruções de critérios.

{"name": "geography_fact", "prompt": "What is the largest city in France by population?", "groundTruth": "Paris", "criteria": [{"name": "correct_answer", "instruction": "Response must state that Paris is the largest city in France by population"}]}

Solução de problemas

Conteúdo relacionado

• Executar avaliações de agente com a CLI do azd
• Visão geral do otimizador de agentes
• Otimizar instruções, habilidades, ferramentas e modelos do agente
• Início Rápido: Otimizar um agente hospedado