Criar um conjunto de dados de avaliação (pré-visualização)

O otimizador de agentes avalia o seu agente com base num conjunto de dados — uma coleção de tarefas com critérios de avaliação. Pode gerar um conjunto de dados automaticamente a partir da CLI ou criar um manualmente para controlo total.

Pré-requisitos

• Um projeto Foundry com um agente alojado implementado
• A azure.ai.agents extensão CLI instalada (ver Quickstart: Otimizar um agente alojado)

Gerar um conjunto de dados (recomendado)

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

azd ai agent eval init

O assistente interativo deteta automaticamente o seu agente a partir de azure.yaml e solicita uma instrução para geração que descreva o que o seu agente faz e que 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 scriptados, 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

Utilize os seus próprios dados com avaliadores gerados

Se já tem um conjunto de dados dourado mas quer avaliadores gerados automaticamente:

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

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

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

azd ai agent optimize

Ou passe-o explicitamente:

azd ai agent optimize --config eval.yaml

Para o fluxo de trabalho completo da CLI de avaliação, veja Executar avaliações de agentes com a CLI azd.

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

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

Por defeito, azd ai agent optimize utiliza um conjunto de dados incorporado com 3 tarefas gerais de codificação e 25 critérios. Para uma otimização significativa do seu agente específico, crie um conjunto de dados personalizado que reflita os casos de uso reais do seu agente.

Formato do conjunto de dados

Os conjuntos de dados utilizam o formato JSONL (JSON Lines). Cada linha é um objeto JSON que representa uma única tarefa de avaliação. Uma tarefa é um cenário individual no conjunto de dados. Contém um enunciado 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 programaçã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"}]}

Use um conjunto de dados personalizado

Referencia o teu conjunto de dados num ficheiro 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 executares o comando, valida 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

Seja específico nos critérios

Fraco:

{"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 claro e binário. Critérios vagos levam a pontuações inconsistentes.

Incluir casos excepcionais

Teste para além do cenário ideal. Inclui:

• Pedidos fora do âmbito — Entradas que o seu agente deve recusar ou redirecionar
• Consultas ambíguas — Tarefas onde o agente deve pedir esclarecimentos
• Inputs adversariais — Tentativas de levar o agente a comportar-se mal
• Tarefas em vários passos — Pedidos complexos que requerem raciocínio estruturado

Diretrizes de tamanho

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

Escrever pedidos como utilizadores reais

Use mensagens reais dos seus utilizadores, se possível. As instruções reais refletem o vocabulário e o contexto que o agente enfrenta em ambiente de produção.

Os critérios são avaliados de forma independente

Cada critério recebe 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 global é a média em todas as tarefas. Isto significa:

• Uma tarefa com 4 critérios, em que 3 são aprovados, obtém uma pontuação de 0,75
• Um agente que cumprir todos os critérios em 2 de 3 tarefas obtém uma pontuação de 0,67

A verdade de base é opcional

A groundTruth área fornece uma resposta de referência para avaliadores que a apoiam. Este campo não é obrigatório. O builtin.task_adherence avaliador funciona exclusivamente com base nas instruções relativas aos 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"}]}

Troubleshooting

Conteúdo relacionado

• Executa avaliações de agentes com o CLI azd
• Visão geral do otimizador de agentes
• Otimizar as instruções, competências, ferramentas e modelos do agente
• Quickstart: Otimizar um agente hospedado