Execute avaliações de agente com a CLI do azd (versão prévia)

Use a azd ai eval extensão para adicionar um loop de qualidade medido a um agente criado com Microsoft Foundry. Você estrutura uma avaliação ao lado do projeto, opcionalmente gera um conjunto de dados e um avaliador de rubrica, executa a avaliação em seu agente e lê os resultados sem sair do terminal.

A mesma avaliação pode ser executada em um pipeline, e --fail-on converte os resultados em um gate de build.

Este artigo aborda a primeira avaliação com azd ai eval init e azd ai eval run start.

Pré-requisitos

• Uma assinatura do Azure com acesso ao Microsoft Foundry.
• A CLI do Desenvolvedor do Azure (azd), versão 1.27.1 ou posterior. Para obter instruções de instalação, consulte Instale a CLI do Desenvolvedor do Azure.
• A extensão azd ai eval: azd extension install azure.ai.evaluations. Execute azd extension list --installed para verificar a versão instalada.
• Uma azd sessão autenticada. Para verificar o status da autenticação, execute azd auth status. Se você não estiver conectado, execute azd auth login.
• A função Foundry User no recurso Foundry (anteriormente denominado Azure AI User). Para obter mais informações, consulte o controle de acesso baseado em funções do Microsoft Foundry.
• Um projeto do Foundry e um agente a ser avaliado. Para que init detecte o destino, o agente deve ser declarado como um serviço no azure.yaml do projeto, como azd ai agent init faz. Caso contrário, nomeie-o com --target. Para agentes hospedados, consulte Agentes hospedados.
• Uma implantação de modelo que oferece suporte a compleções de chat no mesmo projeto. Os alunos julgam com ele.
• Opcional: um conjunto de dados JSONL de exemplos representativos, se você não quiser generate sintetizar um.

Como funcionam as avaliações do azd

Uma avaliação é descrita por um arquivo, evals/azure.eval.yamlque você pode ler, editar e confirmar. Os comandos gravam esse arquivo ou agem sobre o que ele declara.

azd ai eval init          # scaffold the configuration. Makes no service calls
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results

Cada comando aceita -o json para scripts e --debug para diagnósticos. Todos os comandos exceto init aceitam --project-endpoint.

Escolha de onde vêm as linhas

Uma avaliação atribui notas às linhas. Eles vêm de um dos dois lugares, e esta é a primeira decisão:

• --source traces avalia o que seu agente já fez a partir dos rastreamentos que ele emitiu. Não há nada para criar.
• --source dataset avalia um conjunto fixo de exemplos, seus ou gerados. Repetível e comparável entre versões do agente.

As avaliações baseadas em rastreamentos exigem um agente que emita rastreamentos. As avaliações baseadas em conjunto de dados exigem um arquivo .jsonl ou um conjunto de dados registrado.

Estruture a avaliação

Execute init na raiz do projeto:

azd ai eval init

Sem sinalizadores, init detecta o agente quando azure.yaml declara um, solicita quando ele declara vários e pergunta com qual implantação de modelo os alunos avaliam e quais avaliadores usar. Escreve evals/azure.eval.yaml e adiciona um serviço de avaliação a azure.yaml. Não faz chamadas de serviço, portanto pode ser executado com segurança antes de implantar qualquer coisa.

Em um projeto que não declara nenhum serviço de agentes, init interrompe em vez de adivinhar:

ERROR: this project declares no agent service to evaluate. Add one, or name an existing agent with --target

Dê você mesmo um nome ao agente nesse caso, com --target.

Para uso com script, passe as decisões diretamente:

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model gpt-4.1-nano \
  --name support-trace-eval \
  --no-prompt

Para avaliar um conjunto de dados que você já tem:

azd ai eval init \
  --source dataset \
  --target support-agent \
  --dataset ./tests/support-golden.jsonl \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model gpt-4.1-nano

--dataset usa um caminho local .jsonl ou o nome de um conjunto de dados registrado. --evaluator é repetível e separado por vírgula; builtin.<name> faz referência a um avaliador interno e um nome nu faz referência a um avaliador personalizado registrado no projeto. Fornecer --evaluator substitui os valores padrão, portanto também desabilita a geração de rubrica.

Para descobrir os nomes integrados:

azd ai eval evaluator list --builtin

Gerar um conjunto de dados e um avaliador

Se você não tiver um conjunto de dados ou quiser uma rubrica elaborada para este agente em vez de uma genérica, gere um deles:

azd ai eval generate \
  --target support-agent \
  --generation-model gpt-4.1-nano \
  --agent-instruction "Handles support requests. Test triage, policy adherence, and escalation."

Por padrão, isso gera um conjunto de dados e um avaliador de rubrica, baixa-os em evals/ e adiciona uma entrada de catálogo para cada um em evals/azure.eval.yaml. Restrinja com --dataset ou --evaluator para gerar apenas um, e limite as linhas com --max-samples (de 15 a 1000, padrão 15).

generate submete tarefas que consomem chamadas ao modelo. A instrução faz diferença: é o que o serviço usa para determinar do que tratam as linhas e a rubrica, portanto descreva o que o agente faz e o que deve ser testado.

Uma entrada de catálogo declara o artefato; ela não decide qual avaliação o utiliza. Depois de generate, abra evals/azure.eval.yaml e verifique se a avaliação que você pretende executar faz referência ao que foi produzido — uma avaliação baseada em rastreamentos lê rastreamentos, de modo que um conjunto de dados gerado só é usado quando uma avaliação o nomeia:

datasets:
    - name: support-agent-dataset
      source: ./datasets/support-agent-dataset.jsonl
evals:
    - name: support-agent-eval
      dataset: support-agent-dataset   # point the eval at the generated dataset

Para enviar os trabalhos e voltar mais tarde:

azd ai eval generate --target support-agent --generation-model gpt-4.1-nano --no-wait
azd ai eval job list --dataset
azd ai eval job show <job-id> --dataset

--dataset e --evaluator em job permitem escolher sobre qual coleção atuar, e um deles é obrigatório.

Revisar azure.eval.yaml

init grava um arquivo que você deve ler. Uma avaliação baseada em rastreamento se parece com isto:

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        max_traces: 20
        agent_name: support-agent
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano

Uma avaliação de origem de conjunto de dados nomeia o conjunto de dados em vez de uma fonte de rastreamento e registra o agente de destino:

datasets:
    - name: support-golden
      source: ../tests/support-golden.jsonl
evals:
    - name: support-agent-eval
      description: Basic quality evaluation for support-agent
      dataset: support-golden
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initialization_parameters:
            model: gpt-4.1-nano
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano
      target:
        type: agent
        name: support-agent

Os caminhos abaixo source: são relativos ao arquivo de configuração. O JSON gerado .jsonl e o avaliador são arquivos comuns: edite-os e, em seguida, execute create novamente para registrar uma nova versão.

Confirme este arquivo. É a parte reproduzível da avaliação.

Criar a avaliação e executá-la

Use create para registrar tudo o que a configuração declara — conjuntos de dados, avaliadores e a própria avaliação:

azd ai eval create

Em seguida, execute-o:

azd ai eval run start

run start aguarda a execução por padrão e exibe uma tabela por avaliador contendo a taxa de aprovação e a pontuação média, além de um link para a execução no portal. Use --no-wait para enviar e retornar e --max-samples para limitar as linhas enviadas.

Se a configuração declarar mais de uma avaliação, nomeie a que você quer dizer:

azd ai eval run start --eval support-trace-eval

Inspecionar os resultados

O resumo informa se a qualidade mudou. As linhas por amostra mostram o motivo:

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

Para ver as execuções ao longo do tempo e o que o serviço armazena para uma avaliação:

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show retorna a identidade do eval no projeto – ID, nome e quando ele foi criado. O que o eval faz está no seu evals/azure.eval.yaml.

run list carrega uma taxa de aprovação por execução. O detalhamento por avaliador está em -o json, em per_testing_criteria_results, porque uma coluna por avaliador deixa de ser legível quando as execuções recebem pontuações de avaliadores diferentes.

Para levar os resultados para outro lugar:

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --format csv --output-file summary.csv

Os dois diferem, e a diferença importa: run output list --output-file grava as linhas por amostra, enquanto run output export grava uma linha por execução — os totais por trás do sumário.

Controlar um build

Passe --fail-on para converter a execução em uma verificação. Ele retorna um código diferente de zero quando a execução não atinge o limite, que é como um pipeline rejeita uma alteração que causou regressão na qualidade:

azd ai eval run start --fail-on pass-rate=0.8
azd ai eval run start --fail-on any-failure

Sem --fail-on, uma execução concluída com amostras com falhas ainda retorna 0. Amostras com falha são a saída esperada de uma avaliação em funcionamento, não um erro da ferramenta; portanto, o bloqueio é opcional.

pass-rate usa um número entre 0 e 1. Um limiar que não seja 1 é rejeitado antes de a execução ser enviada, portanto, um gate digitado incorretamente não gera custo algum.

--fail-on requer uma execução concluída. No run show, emparelhe-o com --wait.

Implemente avaliações junto com o restante do projeto

init adiciona um serviço de avaliação a azure.yaml, portanto, a avaliação faz parte do projeto em vez de um artefato lateral:

azd up

Isso configura o projeto e registra os conjuntos de dados, avaliadores e execuções de avaliação declarados, o mesmo trabalho que azd ai eval create faz por conta própria.

Alterar o agente e reavaliar

Depois de alterar e reimplantar o agente, execute a mesma avaliação novamente:

azd deploy
azd ai eval run start --eval support-trace-eval

A reutilização da mesma avaliação mantém o conjunto de dados, os avaliadores e os limites fixos, portanto, a comparação é sobre o agente.

Para alterar o que a avaliação mede, edite evals/azure.eval.yaml ou os artefatos gerados em evals/ e depois execute create novamente. create registra uma nova versão de qualquer coisa que foi alterada e deixa execuções anteriores fixadas nas versões usadas.

Práticas recomendadas

• Comece com --source traces se o agente já estiver em execução e gerar rastreamentos. Mede o que aconteceu, e não há nada para criar.
• Mova para --source dataset quando quiser um conjunto fixo de casos que você pode comparar entre versões.
• Leia o conjunto de dados gerado e a rubrica antes de confiar nas pontuações. generate os gera com base na instrução que você fornece, de modo que uma instrução vaga produz linhas imprecisas.
• Use mais de um avaliador. Um único critério move o número sem dizer por quê.
• Confirme evals/azure.eval.yaml e os artefatos gerados, para que a avaliação seja revisável.
• Entre com --fail-on a CI e mantenha o limite em que uma regressão real o atinge.

Limitações

• A extensão está em versão prévia e a superfície de comando pode ser alterada.
• generate envia tarefas faturadas. Conjuntos de dados e avaliadores não são criados por azd provision.
• Uma avaliação baseada em rastros só pode ler os rastros que o agente já emitiu.
• azd reduz o código de saída de uma extensão, de modo que tanto uma falha no gate quanto uma falha operacional resultam em um código de saída diferente de zero. Leia a mensagem do portão para diferenciá-los.

Conteúdo relacionado

• Avaliar seus agentes
• Avaliadores internos
• Avaliadores personalizados
• Avaliação de rastreio
• Configurar o rastreamento para seu agente
• Monitorar agentes com o Painel de Monitoramento do Agente