Ejecutar evaluaciones de agentes con la CLI de azd (versión preliminar)

Use la azd ai eval extensión para agregar un bucle de calidad medido a un agente creado con Microsoft Foundry. Puede crear la estructura de una evaluación junto a su proyecto, generar opcionalmente un conjunto de datos y un evaluador de rúbricas, ejecutar la evaluación con su agente y consultar los resultados sin salir del terminal.

La misma evaluación puede ejecutarse desde un pipeline, y --fail-on convierte sus resultados en una puerta de compilación.

En este artículo se describe la primera evaluación con azd ai eval init y azd ai eval run start.

Prerrequisitos

• Una suscripción de Azure con acceso a Microsoft Foundry.
• La CLI para desarrolladores de Azure (azd), versión 1.27.1 o posterior. Para obtener instrucciones de instalación, consulte Install the Azure Developer CLI.
• Extensión azd ai eval : azd extension install azure.ai.evaluations. Ejecute azd extension list --installed para comprobar la versión instalada.
• Una sesión autenticada azd . Para comprobar el estado de autenticación, ejecute azd auth status. Si no ha iniciado sesión, ejecute azd auth login.
• Rol Foundry User en el recurso Foundry (anteriormente denominado Azure AI User). Para obtener más información, consulte Control de acceso basado en rol para Microsoft Foundry.
• Un proyecto de Foundry y un agente para evaluar. Para permitir que init detecte el destino, el agente debe declararse como servicio en el azd ai agent init del proyecto, como hace azure.yaml. De lo contrario, asígnele el nombre --target. Para los agentes hospedados, consulte Agentes hospedados.
• Un despliegue de un modelo que admite completaciones de chat dentro del mismo proyecto. Los evaluadores toman sus decisiones basándose en ella.
• Opcional: un conjunto de datos JSONL con ejemplos representativos, si no quiere que generate genere uno.

Cómo funcionan las evaluaciones de azd

Una evaluación se describe mediante un archivo, evals/azure.eval.yaml, que puede leer, editar y confirmar. Los comandos o bien escriben ese archivo o bien actúan según lo declarado en él.

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 acepta -o json para scripts y --debug para diagnóstico. Cada comando excepto init acepta --project-endpoint.

Elegir de dónde proceden las filas

Una evaluación califica las filas. Proceden de uno de dos lugares, y esta decisión es la primera decisión:

• --source traces evalúa lo que tu agente ya ha hecho, a partir de los rastros que ha emitido. No hay nada que redactar.
• --source dataset evalúa un conjunto fijo de ejemplos, ya sea el suyo o generado. Repetible y comparable entre versiones de agente.

Las evaluaciones basadas en trazas necesitan un agente que emita trazas. Las evaluaciones basadas en conjuntos de datos necesitan un archivo .jsonl o un conjunto de datos registrado.

Estructurar la evaluación de forma gradual

Ejecute init desde la raíz del proyecto:

azd ai eval init

Sin indicadores, init detecta el agente cuando azure.yaml declara uno, muestra un mensaje cuando declara varios y pregunta con qué implementación del modelo evalúan los correctores y qué evaluadores se deben utilizar. Escribe evals/azure.eval.yaml y agrega un servicio de evaluación a azure.yaml. No realiza llamadas al servicio, por lo que se puede ejecutar de forma segura antes de que se implemente nada.

En un proyecto que no declara ningún servicio de agente, init se detiene en lugar de hacer suposiciones:

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

Ponga usted mismo el nombre del agente en ese caso, usando --target.

Para uso en scripts, pase directamente las decisiones:

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

Para evaluar un conjunto de datos que ya tiene:

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 una ruta de acceso local .jsonl o el nombre de un conjunto de datos registrado. --evaluator es repetible y separado por comas; builtin.<name> hace referencia a un evaluador integrado y un nombre completo hace referencia a un evaluador personalizado registrado en el proyecto. Al pasar --evaluator, se reemplazan los valores predeterminados, por lo que también se desactiva la generación de la rúbrica.

Para descubrir los nombres predefinidos:

azd ai eval evaluator list --builtin

Generación de un conjunto de datos y un evaluador

Si no tiene un conjunto de datos o quiere escribir una rubric para este agente en lugar de una genérica, genere lo siguiente:

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

De forma predeterminada, esto genera un conjunto de datos y un evaluador de rubor, los descarga en evals/y agrega una entrada de catálogo para cada uno a evals/azure.eval.yaml. Restrinjalo con --dataset o --evaluator para generar solo uno y limitar las filas con --max-samples (de 15 a 1000, valor predeterminado 15).

generate envía trabajos que consumen llamadas al modelo. La instrucción es importante: es lo que utiliza el servicio para decidir a qué se refieren las filas y la rúbrica, así que describe qué hace el agente y qué se debe evaluar.

Una entrada de catálogo declara el artefacto; no decide qué evaluación lo usa. Después de generate, abre evals/azure.eval.yaml y comprueba que la evaluación que tienes previsto ejecutar haga referencia a lo que se ha generado: una evaluación basada en trazas lee trazas, por lo que un conjunto de datos generado solo se usa cuando una evaluación lo nombra explícitamente:

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 los trabajos y volver más adelante:

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 y --evaluator en job eligen sobre qué colección actuar, y es obligatorio seleccionar uno de ellos.

Revisa azure.eval.yaml

init escribe un archivo para que lo leas. Una evaluación basada en trazas tiene este aspecto:

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

Una evaluación de origen de conjunto de datos asigna un nombre al conjunto de datos en lugar de a un origen de seguimiento y registra el agente que tiene como 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

Las rutas de acceso en source: son relativas al archivo de configuración. El .jsonl generado y el JSON del evaluador son archivos normales: edítelos y luego vuelva a ejecutar create para registrar una nueva versión.

Confirme este archivo. Es la parte reproducible de la evaluación.

Crea el eval y ejecútalo

Use create para registrar todo lo que declara la configuración: conjuntos de datos, evaluadores y la propia eval:

azd ai eval create

A continuación, ejecútelo:

azd ai eval run start

run start espera la ejecución de forma predeterminada e imprime una tabla por evaluador con una tasa de pase y una puntuación media, además de un vínculo a la ejecución en el portal. Use --no-wait para enviar y devolver y --max-samples para limitar las filas enviadas.

Si la configuración declara más de una evaluación, indica cuál es la que te refieres:

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

Inspección de los resultados

El resumen te indica si la calidad ha cambiado. Las filas por muestra te indican por qué:

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

Para ver las ejecuciones a lo largo del tiempo y lo que el servicio almacena para una evaluación:

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

show devuelve la identidad de eval en el proyecto: identificador, nombre y cuándo se creó. Lo que hace la evaluación se encuentra en tu evals/azure.eval.yaml.

run list incluye un índice de superación por ejecución. El desglose por evaluador se encuentra en -o json, bajo per_testing_criteria_results, ya que una columna por evaluador deja de ser legible una vez que las ejecuciones puntúan a diferentes evaluadores.

Para llevar los resultados a otro 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

Ambos difieren, y la diferencia importa: run output list --output-file escribe las filas por muestra, mientras que run output export escribe una línea por cada ejecución; es decir, los totales en los que se basa el resumen.

Controlar una compilación

Pase --fail-on para convertir la ejecución en una comprobación. Devuelve un valor distinto de cero cuando la ejecución no alcanza el umbral, que es la forma en que una canalización rechaza un cambio que ha supuesto un retroceso en la calidad:

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

Sin --fail-on, una ejecución completada con ejemplos con errores sigue saliendo 0. Las muestras fallidas son el resultado esperado de una evaluación que funciona correctamente, no un error de la herramienta, por lo que el bloqueo es opcional y debe activarse explícitamente.

pass-rate toma un número entre 0 y 1. Un umbral distinto de uno se rechaza antes de que se envíe la ejecución, por lo que un control mal escrito no supone ningún coste.

--fail-on necesita una ejecución que haya finalizado. En run show, adídelo con --wait.

Implementación de evaluaciones con el resto del proyecto

init agrega un servicio de evaluación a azure.yaml, por lo que la evaluación es parte del proyecto en lugar de un artefacto lateral:

azd up

Esto aprovisiona el proyecto y registra los conjuntos de datos, los evaluadores y las evaluaciones declarados, el mismo trabajo que azd ai eval create hace por sí solo.

Cambiar el agente y volver a evaluar

Después de cambiar y volver a implementar el agente, vuelva a ejecutar la misma evaluación:

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

Reutilizar la misma evaluación mantiene fijos el conjunto de datos, los evaluadores y los umbrales, por lo que la comparación se centra en el agente.

Para cambiar qué mide la evaluación, edite evals/azure.eval.yaml o los artefactos generados en evals/, y vuelva a ejecutar create. create registra una nueva versión de todo lo que cambió y deja las ejecuciones anteriores ancladas a las versiones usadas.

procedimientos recomendados

• Comience con --source traces si el agente ya está en ejecución y emite trazas. Mide lo que ha ocurrido y no hay nada que redactar.
• Vaya a --source dataset una vez que desee un conjunto fijo de casos que puede comparar entre versiones.
• Lea el conjunto de datos generado y la rubric antes de confiar en las puntuaciones. generate las genera a partir de la instrucción que le das, por lo que una instrucción imprecisa produce filas imprecisas.
• Use más de un evaluador. Un único criterio mueve el número sin indicarle por qué.
• Realiza un commit de evals/azure.eval.yaml y de los artefactos generados, para que la evaluación sea revisable.
• Aplica el filtro con --fail-on en la integración continua (CI) y mantén el umbral en un nivel en el que una regresión real lo active.

Limitaciones

• La extensión está en versión preliminar y la superficie de comandos puede cambiar.
• generate envía los trabajos facturados. Los conjuntos de datos y evaluadores no se crean mediante azd provision.
• Una evaluación basada en trazas solo puede leer las trazas que el agente ya ha generado.
• azd agrupa el código de salida de una extensión, de modo que tanto el incumplimiento de una puerta de control como un fallo operativo se muestran como una salida distinta de cero. Lea el mensaje de la puerta de embarque para distinguirlos.

Contenido relacionado

• Evaluación de los agentes
• Evaluadores integrados
• Evaluadores personalizados
• Evaluación de seguimiento
• Configurar seguimiento para el agente
• Supervisión de agentes con el panel de supervisión del agente