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

Use a experiência de avaliação da CLI do desenvolvedor Azure (azd) para adicionar um loop de qualidade medido a um agente criado com Microsoft Foundry. Este artigo se concentra no ciclo de vida do agente hospedado em azd, no qual você cria, provisiona, implanta, inicializa os ativos de avaliação, executa uma primeira avaliação, inspeciona a execução e reutiliza a configuração de avaliação em execuções posteriores.

Os agentes baseados em prompts também podem ser avaliados quando estiverem disponíveis como alvos de agente no projeto Foundry. As etapas de implantação do agente hospedado se aplicam somente aos agentes hospedados.

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

Pré-requisitos

• Uma assinatura do Azure com acesso ao Microsoft Foundry.
• A CLI do Desenvolvedor do Azure (azd). Para obter instruções de instalação, consulte Instale a CLI do Desenvolvedor do Azure.
• A extensão azd ai agent instalada (azd extension install azure.ai.agents). Se você não tiver a extensão instalada, ao inicializar o modelo inicial ou executar azd ai agent, a extensão será instalada automaticamente. Para saber mais sobre a extensão de agente de IA azd, consulte extensão de agente do Microsoft Foundry
• 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.
• Para agentes hospedados: Nenhum projeto de Foundry pré-inicial é necessário. azd ai agent init e azd provision criam os recursos necessários.
• Para agentes baseados em prompt: Um projeto Foundry existente com o agente já implantado e disponível como alvo de avaliação.
• Uma implantação de modelo que oferece suporte a complementos de chat no mesmo projeto do Foundry.
• Opcional: um conjunto de dados de avaliação JSONL com exemplos representativos, se você não quiser eval init gerar um conjunto de dados de fumaça.

Como funcionam as avaliações do agente azd

A experiência de avaliação da CLI do azd principal foi projetada 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 artefatos e comandos.

azd provision não cria conjuntos de dados de avaliação, avaliadores, conjuntos ou trabalhos de otimização. A configuração da avaliação pode envolver trabalho de geração que leva minutos, por isso ela permanece explícita e pode ser repetida.

Para agentes hospedados, a primeira avaliação exige um destino do agente implantado e invocável. Para agentes baseados em prompt, a etapa de implantação não se aplica; o agente já deve existir no projeto Foundry e estar disponível como alvo de avaliação.

Criar e implantar um agente hospedado

Se você ainda não tiver um projeto de agente hospedado, inicialize um com azd:

azd ai agent init

Provisione os recursos da Foundry e implante o agente:

azd provision
azd deploy

Após a implantação ser concluída, verifique se o agente pode ser invocado:

azd ai agent status

O agente hospedado deve estar implantado e poder ser invocado antes de inicializar os ativos de avaliação.

Após uma implantação bem-sucedida, a CLI sugere a avaliação como uma próxima etapa explícita:

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 prompt, ignore os comandos de criação e implantação do agente hospedado. Prossiga para a próxima seção após confirmar que o agente baseado em prompts existe no projeto do Foundry e está disponível como alvo de avaliação.

Inicialize os ativos de avaliação

Execute eval init no espaço de trabalho do azd ou na pasta do projeto do agente:

azd ai agent eval init

Sem sinalizadores, o comando inicia um assistente interativo. O assistente detecta o destino do agente a partir do ambiente do azd e, em seguida, solicita 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 em scripts, passe 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 tem como padrão eval.yaml na raiz do projeto do agente. Use --output <path> para gravar a configuração em um local diferente.

Para usar 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 seu próprio conjunto de dados de avaliação.

O --dataset valor pode apontar para um arquivo local ou um nome de conjunto de dados registrado. Repita --evaluator para incluir vários avaliadores personalizados internos ou registrados. As referências do avaliador usam o formato <source>.<name>:

• builtin.<name> — faz referência a um avaliador interno fornecido pelo Foundry.
• <name> — faz referência a um avaliador personalizado registrado no projeto Foundry. Use o nome registrado do avaliador sem o sufixo de versão.

Adiar a geração usando --no-wait

Se a geração do conjunto de dados ou do avaliador demorar muito, use --no-wait para enviar trabalhos de geração e sair imediatamente:

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

Os IDs de operação pendentes são gravados em eval.yaml. Quando você executar azd ai agent eval runposteriormente, ele retomará automaticamente essas operações antes de iniciar a execução de avaliação.

Use um alvo de agente baseado em prompts

Se você inicializou ativos de avaliação para um agente baseado em prompt, poderá usar o mesmo fluxo de receita de avaliação. A etapa de implantação do agente hospedado não é necessária para agentes baseados em prompt.

Antes de executar uma avaliação, confirme se:

• O agente baseado em prompt existe no projeto Foundry.
• O agente está disponível como um alvo de avaliação.
• Você tem acesso ao endpoint do projeto e ao alvo do agente.
• eval.yaml seleciona o agente baseado em prompts desejado.

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

azd ai agent list

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

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

Revisar eval.yaml

Depois que eval init for concluído com sucesso, abra eval.yaml na raiz do projeto do agente. Por exemplo:

src/reservation-agent/eval.yaml

Execute eval run a partir desse diretório ou passe o caminho explicitamente com --config src/reservation-agent/eval.yaml. O arquivo identifica o destino 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 vive na raiz do projeto do agente, por exemplo src/<agent-name>/eval.yaml.
• Os conjuntos de dados gerados ficam em datasets/ e os critérios de avaliação gerados pelo avaliador ficam em evaluators/, na pasta do agente.
• local_uri os caminhos em eval.yaml são relativos ao diretório do projeto do agente.
• Os arquivos locais referenciados por local_uri podem ser editados. Execute azd ai agent eval update para registrar alterações locais como uma nova versão no serviço e incrementar a versão em eval.yaml.
• eval run usa a versão registrada fixada em eval.yaml. Para aplicar edições locais, execute eval update antes eval run.
• Os avaliadores podem ser referências internas (por exemplo, builtin.task_adherence) ou avaliadores personalizados gerados com name, versione local_uri.
• Trate os campos de versão como cadeias de caracteres, mesmo que pareçam numéricos, de modo que a receita permaneça estável entre os analisadores YAML.

Executar a avaliação

Na pasta do projeto do agente, execute:

azd ai agent eval run

Por padrão, o argumento eval run zero é resolvido eval.yaml na raiz do projeto do agente. Você também pode passar o caminho de configuração explicitamente:

azd ai agent eval run --config eval.yaml

Se eval init --no-wait criou 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.

Inspecionar execuções de avaliação

Listar execuções de avaliação recentes:

azd ai agent eval list

Mostrar a última execução:

azd ai agent eval show

Na ausência de sinalizadores, eval show usa por padrão a execução de avaliação concluída mais recentemente.

Mostrar uma execução específica por sua ID de execução. 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 a saída de execução para responder:

• Qual versão do agente foi avaliada.
• Quais versões do conjunto de dados e do avaliador foram resolvidas.
• Se a execução foi concluída, falhou ou foi concluída parcialmente.
• Quais métricas ou pontuações do avaliador foram produzidas.
• Se o uso de token ou os logs do avaliador precisam ser investigados.

Executar novamente depois de alterar o agente

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

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

Para agentes baseados em prompt, atualize o agente na Foundry e execute novamente a mesma receita de avaliação.

Reexecutar o mesmo eval.yaml ajuda a manter estáveis as referências ao conjunto de dados, ao avaliador e ao limiar, mesmo com mudanças no agente.

Atualizar, redefinir ou reparar ativos de avaliação

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

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

Por exemplo, depois de editar uma rubrica de avaliador gerada em evaluators/ na pasta agent, execute:

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

O comando de atualização cria novas versões de conjunto de dados ou avaliador registrados. As execuções de avaliação existentes permanecem vinculadas às versões usadas originalmente.

Quando eval.yaml já existe, eval init detecta-o 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 substituir 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 eval.yaml local e gera novamente os ativos de avaliação padrão. As versões existentes do conjunto de dados e do avaliador registradas no serviço não são excluídas; somente a receita local é substituída.

Não confie em versões remotas mais recentes para alterarem silenciosamente a receita local. O eval.yaml local registra as versões do conjunto de dados, do avaliador ou da suíte usadas pela receita para garantir a reprodutibilidade.

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

Depois que pelo menos uma execução de avaliação for bem-sucedida, você poderá usar eval.yaml como entrada para otimização do agente se o agente e a receita atenderem aos pré-requisitos de otimização.

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

• O alvo do agente está pronto para otimização. Para agentes hospedados, o agente é implantado e pode ser invocado.
• eval.yaml faz referência ao agente, ao conjunto de dados, às versões do avaliador e aos limites pretendidos.
• 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 os pré-requisitos do otimizador e os requisitos para a preparação do agente, consulte Otimizar prompts do agente com o Otimizador de Prompts.

Em seguida, execute:

azd ai agent optimize --config eval.yaml

O comando optimize lê o alvo do agente, o conjunto de dados, os avaliadores e os limiares de eval.yaml. Ele envia uma tarefa de otimização, mas não aplica silenciosamente as alterações no código-fonte nem reimplanta o agente candidato. Examine qualquer saída do otimizador antes de aplicar alterações.

Práticas recomendadas

• Execute azd ai agent eval init somente depois que o agente estiver disponível como um destino de avaliação. Para agentes hospedados, o agente deve ser implantado e poder ser invocado.
• Comece com um pequeno conjunto de dados gerado ou um pequeno subconjunto do conjunto de dados golden.
• Verifique o conjunto de dados gerado e os artefatos da revisão do avaliador antes de confiar nos resultados.
• Depois de editar arquivos de avaliação ou conjunto de dados gerados, execute azd ai agent eval update para registrar os ativos editados antes de executar a avaliação novamente.
• Controle do código-fonte eval.yaml se sua equipe quiser uma receita de avaliação revisável e reproduzível.
• Considere manter sob controle de versão os conjuntos de dados gerados e as rubricas de avaliação em datasets/ e evaluators/ na pasta do agente, se sua equipe os revisar e editar como parte da receita de avaliação.
• Execute novamente o mesmo eval.yaml após as alterações do agente para que as comparações usem a mesma receita de teste.
• Use azd ai agent optimize --config eval.yaml somente depois que você tiver um resultado de avaliação de linha de base útil e o agente estiver preparado para otimização.

Limitações

• O fluxo de comando primário é otimizado para agentes hospedados e o loop de avaliação pós-implantaçã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 de eval init --no-wait.
• Ciclo de vida completo do pacote, avaliação agendada, avaliação contínua, alertas e fluxos de trabalho de comparação não são necessários para o primeiro caminho de avaliação.

Conteúdo relacionado

• Avaliar seus agentes de IA
• Avaliação humana para agentes do Microsoft Foundry
• Análise de cluster de avaliação
• Otimizar prompts do agente com o Otimizador de Prompt
• Configure o rastreamento para agentes de IA no Microsoft Foundry
• Monitorar agentes com o Painel de Monitoramento do Agente
• Agentes hospedados no Serviço do Foundry Agent
• Ciclo de vida de desenvolvimento do agente