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

Use a experiência de avaliação CLI do Azure Developer CLI (azd) para adicionar um ciclo de qualidade medido a um agente criado com Microsoft Foundry. Este artigo foca-se no ciclo de vida do agente alojado em azd, onde cria, provisiona, implementa, inicializa ativos de avaliação, executa uma primeira avaliação, inspeciona a execução e reutiliza a receita de avaliação para execuções posteriores.

Agentes baseados em prompts também podem ser avaliados quando estão disponíveis como alvos de agentes no projeto Foundry. Os passos de implementação do agente hospedado aplicam-se apenas aos agentes hospedados.

Este artigo aborda como realizar a avaliação do primeiro agente com azd ai agent eval init e azd ai agent eval run.

Pré-requisitos

• Uma subscrição Azure com acesso ao Microsoft Foundry.
• A Azure CLI para Desenvolvedores (azd). Para instruções de instalação, consulte Instale a CLI do Desenvolvedor Azure.
• A azd ai agent extensão instalada (azd extension install azure.ai.agents). Se não tiver a extensão instalada, quando inicializa o template inicial ou executa azd ai agent , a extensão é instalada automaticamente. Para saber mais sobre a extensão do agente de IA azd, consulte extensão de agente do Microsoft Foundry
• 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.
• Para agentes alojados: Não é necessário nenhum projeto de fundição pré-existente. azd ai agent init e azd provision criam os recursos necessários.
• Para agentes baseados em prompts: Um projeto Foundry existente com o agente já implementado e disponível como alvo de avaliação.
• Um modelo de implementação que suporta a conclusão de chats no mesmo projeto Foundry.
• Opcional: um conjunto de dados de avaliação JSONL com exemplos representativos, caso não queira eval init gerar um conjunto de dados de fumo.

Como funcionam as avaliações de agentes do azd

A principal experiência de avaliação do CLI azd é concebida para o ciclo de vida do agente hospedado:

azd ai agent init
azd provision
azd deploy
azd ai agent eval init
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

O fluxo de avaliação inclui os seguintes artefactos e comandos.

azd provision não cria conjuntos de dados de avaliação, avaliadores, suites ou trabalhos de otimização. A configuração da avaliação pode envolver processos de geração que demoram minutos, pelo que se mantém explícita e pode ser repetida.

Para agentes alojados, a primeira avaliação requer um agente alvo implantado e invocável. Para agentes baseados em prompts, a etapa de implementação não se aplica; o agente deve já existir no projeto Foundry e estar disponível como alvo de avaliação.

Crie e implemente um agente alojado

Se ainda não tiver um projeto de agente hospedado, inicie um com azd:

azd ai agent init

Provisione os recursos do Foundry e implemente o agente:

azd provision
azd deploy

Após a conclusão da implementação, verifique se o agente é invocável:

azd ai agent status

O agente hospedado deve ser implementado e invocável antes de inicializar os ativos de avaliação.

Após uma implantação bem-sucedida, o CLI sugere a avaliação como um passo explícito seguinte:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval init`

Para avaliar um agente baseado em prompts, ignore os comandos de criação e implementação do agente hospedado. Continue na secção seguinte depois de confirmar que o agente baseado em prompts existe no projeto Foundry e está disponível como alvo de avaliação.

Inicializar ativos de avaliação

Execute eval init a partir da área de trabalho do azd ou da pasta do projeto do agente:

azd ai agent eval init

Sem bandeiras, o comando inicia um mago interativo. O assistente deteta o agente de destino a partir do ambiente azd e, em seguida, pede uma instrução para geração, para que o serviço possa criar dados iniciais úteis para avaliação e uma rubrica de avaliação.

Exemplo de saída interativa:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Para uso scriptado, passa diretamente as entradas de geração:

azd ai agent eval init \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--output é opcional e assume, por predefinição, o valor eval.yaml na raiz do projeto do agente. Use --output <path> para escrever a configuração noutro local.

Para utilizar um conjunto de dados existente e avaliadores selecionados:

azd ai agent eval init \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --output eval.yaml

Substitua ./tests/support-golden.jsonl pelo caminho para o seu próprio conjunto de dados de avaliação.

O --dataset valor pode apontar para um ficheiro local ou para o nome de um conjunto de dados registado. Repita --evaluator para incluir múltiplos avaliadores personalizados incorporados ou registados. As referências dos avaliadores utilizam o formato <source>.<name>:

• builtin.<name> — faz referência a um avaliador incorporado fornecido pela Foundry.
• <name> — refere-se a um avaliador personalizado registado no projeto Foundry. Use o nome registado do avaliador sem o sufixo de versão.

Adiar geração com --no-wait

Se a geração de conjuntos de dados ou avaliadores demorar demasiado, use --no-wait para submeter trabalhos de geração e sair imediatamente:

azd ai agent eval init \
  --gen-instruction "..." \
  --no-wait

Os IDs de operações pendentes são escritos em eval.yaml. Quando mais tarde executar azd ai agent eval run, retoma automaticamente essas operações antes de iniciar a execução de avaliação.

Use um agente alvo baseado em prompts

Se inicializou ativos de avaliação para um agente baseado em prompts, pode utilizar o mesmo fluxo da receita de avaliação. A etapa de implementação do agente hospedado não é obrigatória para agentes baseados em prompts.

Antes de fazer uma avaliação, confirme que:

• O agente baseado em prompts existe no projeto Foundry.
• O agente está disponível como alvo de avaliação.
• Tens acesso ao endpoint do projeto e ao alvo do agente.
• eval.yaml seleciona o agente baseado em instruções desejado.

Para listar agentes disponíveis no atual projeto Foundry, execute:

azd ai agent list

Depois, use os mesmos comandos para executar e inspecionar a avaliação:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

Review eval.yaml

Depois de eval init ter sucesso, abre eval.yaml na raiz do projeto agente. Por exemplo:

src/reservation-agent/eval.yaml

Execute eval run a partir deste diretório, ou passe o caminho explicitamente com --config src/reservation-agent/eval.yaml. O ficheiro identifica o alvo do agente, a referência do conjunto de dados, as referências do avaliador e as opções de geração. Uma forma simplificada é:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100

• eval.yaml encontra-se na raiz do projeto do agente, por exemplo src/<agent-name>/eval.yaml.
• Os conjuntos de dados gerados encontram-se em datasets/ e as rubricas de avaliação geradas encontram-se em evaluators/, na pasta do agente.
• local_uri Os caminhos em eval.yaml são relativos ao diretório do projeto do agente.
• Os ficheiros locais referenciados por local_uri são editáveis. Execute azd ai agent eval update para registar as alterações locais como uma nova versão no serviço e incremente a versão em eval.yaml.
• eval run usa a versão registada fixada em eval.yaml. Para aplicar edições locais, execute eval update antes de eval run.
• Os avaliadores podem ser referências integradas (por exemplo, builtin.task_adherence) ou avaliadores personalizados gerados com name, version e local_uri.
• Trate os campos de versão como cadeias de caracteres, mesmo que pareçam numéricos, para que a receita se mantenha estável em todos os analisadores YAML.

Faz a avaliação

Da pasta do projeto do agente, execute:

azd ai agent eval run

Por defeito, eval run sem argumentos é resolvido em eval.yaml na raiz do projeto do agente. Também pode passar explicitamente o caminho de configuração:

azd ai agent eval run --config eval.yaml

Se eval init --no-wait tiver criado operações de geração pendentes, eval run retoma essas operações antes de iniciar a execução da avaliação. Não inicia novos trabalhos de geração de conjuntos de dados ou de avaliadores do zero.

Inspeção das execuções de avaliação

Lista de corridas de avaliação recentes:

azd ai agent eval list

Mostrar a execução mais recente:

azd ai agent eval show

Sem opções, eval show, por predefinição, usa a execução de avaliação concluída mais recentemente.

Mostra uma execução específica pelo respetivo ID. Copie o ID da saída azd ai agent eval list:

ID                                         Status     Agent              Date
run-a1b2c3d4-e5f6-7890-abcd-ef1234567890   completed  reservation-agent  2026-05-20

azd ai agent eval show --eval-id run-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Use o resultado da execução para responder:

• Qual versão do agente foi avaliada.
• Quais as versões do conjunto de dados e do avaliador foram resolvidas.
• Quer a corrida tenha sido concluída, falhada ou parcialmente concluída.
• Quais métricas ou pontuações dos avaliadores foram produzidas.
• Se o uso de tokens ou os registos do avaliador precisam de investigação.

Repetição após mudar o agente

Depois de atualizar e redistribuir um agente alojado, execute novamente a mesma receita de avaliação:

azd deploy
azd ai agent eval run --config eval.yaml

Para agentes baseados em prompts, atualize o agente no Foundry e depois execute novamente o mesmo procedimento de avaliação.

Executar novamente o mesmo eval.yaml ajuda a manter estáveis as referências ao conjunto de dados, aos avaliadores e aos limiares entre alterações aos agentes.

Atualizar, reiniciar ou reparar os ativos de avaliação

O fluxo de avaliação do agente utiliza eval.yaml como receita de avaliação local. Use azd ai agent eval update quando editar ficheiros de conjunto de dados locais ou rubricas de avaliadores e quiser registar essas edições como novas versões de serviço.

Para atualizar o que uma execução de avaliação utiliza, escolha o caminho que corresponde ao tipo de alteração:

Por exemplo, após editar uma rubrica de avaliação gerada na evaluators/ pasta agente, execute:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

O comando update cria novos conjuntos de dados registados ou versões do avaliador. As execuções de avaliação existentes permanecem associadas às versões que utilizaram originalmente.

Quando eval.yaml já existe, eval init deteta e imprime a configuração existente:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval init --reset-defaults

Para sobrescrever a configuração local e regenerar os ativos de avaliação padrão, execute:

azd ai agent eval init --reset-defaults

--reset-defaults sobrescreve o local eval.yaml e regenera os ativos de avaliação padrão. As versões existentes do conjunto de dados registados no serviço e dos avaliadores não são eliminadas; apenas a receita local é substituída.

Não dependa de as versões remotas mais recentes alterarem silenciosamente a receita local. O eval.yaml local regista as versões do conjunto de dados, do avaliador ou da suite utilizadas pela receita para garantir a reprodutibilidade.

Opcional: iniciar otimização a partir do sinal de avaliação

Depois de pelo menos uma execução de avaliação bem-sucedida, podes usar eval.yaml como input para otimização do agente se o agente e a receita cumprirem os pré-requisitos de otimização.

Antes de iniciar a otimização, confirme que:

• O agente alvo está pronto para otimização. Para agentes hospedados, o agente está implantado e pode ser invocado.
• eval.yaml Refere o agente pretendido, o conjunto de dados, as versões do avaliador e os limiares.
• Pelo menos uma execução de avaliação foi concluída com sucesso.
• A preparação do agente exigida pelo otimizador está concluída. Para conhecer os pré-requisitos do otimizador e os requisitos de preparação do agente, consulte Otimizar prompts de agente com o Prompt Optimizer.

Em seguida, execute:

azd ai agent optimize --config eval.yaml

O comando optimizar lê o alvo do agente, o conjunto de dados, os avaliadores e os limiares a partir de eval.yaml. Submete uma tarefa de otimização, mas não aplica silenciosamente alterações na origem nem reimplanta o agente candidato. Revise qualquer saída do otimizador antes de aplicar alterações.

Melhores práticas

• Execute azd ai agent eval init apenas depois de o agente estar disponível como alvo de avaliação. Para agentes hospedados, o agente deve ser implementado e invocável.
• Comece com um pequeno conjunto de dados gerado ou um pequeno subconjunto do seu conjunto de dados dourado.
• Verifique o conjunto de dados gerado e o avaliador analise artefactos antes de confiar nas pontuações.
• Após editar o conjunto de dados gerado ou ficheiros avaliadores, execute azd ai agent eval update para registar os ativos editados antes de executar novamente a avaliação.
• Controlo eval.yaml de versões se a sua equipa quiser uma receita de avaliação revisível e reproduzível.
• Considere controlar o código-fonte dos conjuntos de dados gerados e as rubricas dos avaliadores sob datasets/ e evaluators/ dentro da pasta agente se a sua equipa os rever e editar como parte da receita de avaliação.
• Repete o mesmo eval.yaml depois de mudar o agente para que as comparações usem a mesma receita de teste.
• Utilize azd ai agent optimize --config eval.yaml apenas depois de obter um resultado útil de uma avaliação de referência e de o agente estar preparado para a otimização.

Limitações

• O fluxo de comandos primário é otimizado para agentes alojados e para o ciclo de avaliação pós-implementação.
• azd provision não cria ativos de avaliação.
• eval run não gera novos conjuntos de dados ou avaliadores, exceto para retomar operações pendentes a partir de eval init --no-wait.
• Ciclo de vida completo do conjunto, avaliação agendada, avaliação contínua, alertas e fluxos de trabalho de comparação não são necessários para o primeiro percurso de avaliação.

Conteúdo relacionado

• Avalie os seus agentes de IA
• Avaliação humana para agentes Microsoft Foundry
• Análise de clusters de avaliação
• Otimize os prompts dos agentes com o Prompt Optimizer
• Configurar rastreamento para agentes de IA no Microsoft Foundry
• Monitorize os agentes com o Painel de Monitorização de Agentes
• Agentes alojados no serviço Foundry Agent
• Ciclo de vida do desenvolvimento do agente