Executar avaliações de agentes com a CLI azd (pré-visualização)

Use a azd ai eval extensão para adicionar um ciclo de qualidade medida a um agente construído com o Microsoft Foundry. Cria a estrutura base de uma avaliação ao lado do seu projeto, gera, opcionalmente, um conjunto de dados e um avaliador de critérios, executa a avaliação sobre o seu agente e lê os resultados sem sair do terminal.

A mesma avaliação pode ser executada num pipeline, e --fail-on transforma os seus resultados num critério de bloqueio da compilação.

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

Pré-requisitos

• Uma subscrição Azure com acesso ao Microsoft Foundry.
• The Azure Developer CLI (azd), versão 1.27.1 ou posterior. Para instruções de instalação, consulte Instale a CLI do Desenvolvedor Azure.
• A azd ai eval extensão: azd extension install azure.ai.evaluations. Executa azd extension list --installed para verificar a versão instalada.
• Uma sessão azd autenticada. Para verificar o seu estado de autenticação, execute azd auth status. Se não tiver iniciado sessão, execute azd auth login.
• O papel Foundry User no recurso Foundry (anteriormente chamado Azure AI User). Para mais informações, consulte Controlo de acesso baseado em funções para Microsoft Foundry.
• Um projeto da Foundry, e um agente para avaliar. Para deixar init detetar o alvo, o agente deve ser declarado como um serviço no projeto azure.yaml, tal como azd ai agent init faz. Caso contrário, nomeie com --target. Para agentes alojados, veja Agentes alojados.
• Um modelo de implementação que suporta a conclusão de chats no mesmo projeto. Os avaliadores julgam usando-o.
• Opcional: um conjunto de dados JSONL com exemplos representativos, caso não queiras generate sintetizar um.

Como funcionam as avaliações AZD

Uma avaliação é descrita por um ficheiro, evals/azure.eval.yaml, que pode ler, editar e submeter. Os comandos ou escrevem esse ficheiro ou agem com base no 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

Todos os comandos aceitam -o json para criação de scripts e --debug para diagnósticos. Todos os comandos, exceto init aceitam --project-endpoint.

Escolhe de onde vêm as linhas

Uma avaliação classifica as linhas. Eles vêm de um de dois lugares, e esta é a primeira decisão:

• --source traces avalia o que o seu agente já fez, com base nos rastreios que emitiu. Nada para escrever.
• --source dataset Avalia um conjunto fixo de exemplos, sejam teus ou gerados. Reproduzível e comparável entre diferentes versões do agente.

As avaliações baseadas em rastos precisam de um agente que emita rastos. As avaliações baseadas em conjuntos de dados necessitam de um .jsonl ficheiro ou de um conjunto de dados registado.

Estruture a avaliação

Run init a partir da raiz do teu projeto:

azd ai eval init

Sem flags, init deteta o agente quando azure.yaml declara um, indica quando declara vários, e pergunta com que modelo de implementação os avaliadores julgam e que 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, por isso é seguro executá-lo antes de implementar qualquer coisa.

Num projeto que não declara serviço de agente, init para em vez de adivinhar:

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

Nesse caso, nomeie o agente por si próprio, com --target.

Para utilização em scripts, 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 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 Toma um caminho local .jsonl ou o nome de um conjunto de dados registado. --evaluator é repetível e separado por vírgula; builtin.<name> Faz referência a um avaliador incorporado, e um nome simples faz referência a um avaliador personalizado registado no projeto. Passar --evaluator substitui os predefinidos, por isso também opta por não gerar rubricas.

Para descobrir os nomes incorporados:

azd ai eval evaluator list --builtin

Gerar um conjunto de dados e um avaliador

Se não tiver um conjunto de dados, ou quiser escrever uma rubrica para este agente em vez de uma genérica, gere-os:

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 predefinição, este comando gera tanto um conjunto de dados como um avaliador de critérios, transfere-os para evals/ e adiciona uma entrada no catálogo para cada um em evals/azure.eval.yaml. Estreita com --dataset ou --evaluator para gerar apenas uma, e limita as linhas com --max-samples (15 a 1000, padrão 15).

generate Submete trabalhos que custam chamadas de modelo. A instrução é importante: é o que o serviço usa para determinar a que dizem respeito as linhas e a rubrica, por isso descreva o que o agente faz e o que deve ser testado.

Uma entrada de catálogo declara o artefacto; não determina qual avaliação o utiliza. Após generate, abra evals/azure.eval.yaml e verifique se a avaliação que pretende executar faz referência ao que foi produzido — uma avaliação de origem traçada lê traços, pelo 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 submeter 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, escolha em que coleção aplicar a ação, sendo obrigatório indicar uma delas.

Review azure.eval.yaml

init Escreve um ficheiro que deves ler. Uma avaliação proveniente de rastreamento tem este aspeto:

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 proveniente de um conjunto de dados nomeia o conjunto de dados em vez de uma origem de rastreio e regista o agente a que se destina:

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 sob source: são relativos ao ficheiro de configuração. O JSON gerado .jsonl e o avaliador são ficheiros comuns: edito-os e depois executa-os create novamente para registar uma nova versão.

Confirme este ficheiro. É a parte reprodutível da avaliação.

Cria a avaliação e executa-a

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

azd ai eval create

Depois executa:

azd ai eval run start

run start aguarda, por predefinição, pela execução e apresenta uma tabela por avaliador com a taxa de aprovação e a pontuação média, além de uma ligação para a execução no portal. Use --no-wait para submeter e devolver, e --max-samples para limitar as linhas enviadas.

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

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

Inspecionar os resultados

O resumo diz-lhe se a qualidade se moveu. As linhas de cada amostra mostram-lhe porquê:

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 contém 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 da avaliação no projeto — ID, nome e quando foi criada. O que a eval faz está no seu evals/azure.eval.yaml.

run list tem uma taxa de passe por corrida. A divisão por avaliador está em -o json, sob per_testing_criteria_results, porque uma coluna por avaliador deixa de ser legível quando as corridas pontuam avaliadores diferentes.

Para levar os resultados para outro lado:

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 são diferentes, e essa diferença é importante: run output list --output-file grava as linhas de cada amostra, enquanto run output export grava uma linha por cada execução — os totais subjacentes ao resumo.

Controlar uma compilação

Passar --fail-on para transformar a execução numa verificação. Sai de zero quando a execução não atinge o limiar, que é assim que um pipeline falha numa alteração dessa qualidade regressiva:

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 falhadas ainda sai de 0. As amostras com falha são o resultado esperado de uma avaliação que funciona corretamente, e não um erro da ferramenta, pelo que o bloqueio tem de ser ativado explicitamente.

pass-rate Toma um número entre 0 e 1. Um valor limite diferente de 1 é recusado antes de a execução ser submetida, pelo que uma condição introduzida incorretamente não tem qualquer custo.

--fail-on precisa de uma execução concluída. Em run show, emparelhe-o com --wait.

Implementar avaliações com o resto do projeto

init adiciona um serviço de avaliação a azure.yaml, de modo que a avaliação faz parte do projeto e não um artefacto secundário:

azd up

Isso configura o projeto e regista os conjuntos de dados, avaliadores e evals declarados, o mesmo trabalho que azd ai eval create faz por si só.

Muda o agente e reavalia

Depois de alterar e redistribuir o agente, faça novamente a mesma avaliação:

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

Reutilizar a mesma avaliação mantém o conjunto de dados, os avaliadores e os limiares fixos, por isso a comparação é sobre o agente.

Para alterar o que a avaliação mede, edite evals/azure.eval.yaml ou os artefactos gerados em evals/, e depois execute create novamente. create regista uma nova versão de qualquer coisa que tenha mudado e deixa as corridas anteriores fixadas às versões que usaram.

Melhores práticas

• Começa por --source traces se o agente já está a correr e emite traços. Mede o que aconteceu, e não há nada para escrever.
• Mude para --source dataset quando quiseres um conjunto fixo de casos que possas comparar entre versões.
• Leia o conjunto de dados gerado e a rubrica antes de confiar nas pontuações. generate gera-as a partir da instrução que lhe dá, por isso uma instrução vaga produz linhas imprecisas.
• Use mais do que um avaliador. Um único critério move o número sem lhe dizer porquê.
• Commit evals/azure.eval.yaml e os artefactos gerados, para que a avaliação seja revisível.
• Use --fail-on na CI e mantenha o limiar num valor em que uma regressão real o acione.

Limitações

• A extensão está em fase de pré-visualização e a interface de comandos pode mudar.
• generate submete tarefas faturadas. Conjuntos de dados e avaliadores não são criados por azd provision.
• Uma avaliação de origem de traços só pode ler os traços que o agente já emitiu.
• azd colapsa o código de saída de uma extensão, pelo que uma violação do portão e uma falha operacional surgem ambas como uma saída não nula. Lê a mensagem do portão para os distinguir.

Conteúdo relacionado

• Avalie os seus agentes
• Avaliadores incorporados
• Avaliadores personalizados
• Avaliação de rastreio
• Configura o rastreio para o teu agente
• Monitorize os agentes com o Painel de Monitorização de Agentes