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

Use la experiencia de evaluación de la CLI de Azure Developer (azd) para agregar un bucle de calidad medido a un agente creado con Microsoft Foundry. Este artículo se centra en el ciclo de vida del agente hospedado en azd, donde se crean, aprovisionan, implementan, inicializan recursos de evaluación, ejecutan una primera evaluación, inspeccionan la ejecución y reutilizan la receta de evaluación para ejecuciones posteriores.

Los agentes basados en indicaciones también se pueden evaluar cuando están disponibles como destinos de agente en el proyecto de Foundry. Los pasos de implementación del agente hospedado solo se aplican a los agentes hospedados.

En este artículo se explica cómo ejecutar la primera evaluación del agente con azd ai agent eval generate y azd ai agent eval run.

Prerrequisitos

• Una suscripción de Azure con acceso a Microsoft Foundry.
• La CLI del desarrollador de Azure (azd). Para obtener instrucciones de instalación, consulte Install the Azure Developer CLI.
• La extensión azd ai agent, versión 0.1.40-versión preliminar o posterior, instalada (azd ext install azure.ai.agents). Si no tiene instalada la extensión, al inicializar la plantilla de inicio o ejecutar azd ai agent la extensión se instala automáticamente. Ejecute azd ext list para comprobar la versión instalada y ejecute azd ext upgrade azure.ai.agents si necesita actualizar. Para obtener más información sobre la extensión azd del agente de IA, consulte extensión del agente de Microsoft Foundry.
• 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.
• Para agentes hospedados: No se requiere ningún proyecto foundry preexistente. azd ai agent init y azd provision crean los recursos necesarios.
• Para los agentes basados en mensajes: Un proyecto de Foundry existente con el agente ya implementado y disponible como destino de evaluación.
• Una implementación de modelo que admite finalizaciones de conversaciones dentro del mismo proyecto de Foundry.
• Opcional: un conjunto de datos de evaluación JSONL con ejemplos representativos, si no desea eval generate generar un conjunto de datos de humo.

Cómo funcionan las evaluaciones del agente azd

La experiencia de evaluación de la CLI principal de azd está diseñada para el ciclo de vida del agente hospedado:

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

El flujo de evaluación incluye los siguientes artefactos y comandos.

azd provision no crea conjuntos de datos de evaluación, evaluadores, conjuntos o trabajos de optimización. La configuración de la evaluación puede implicar tareas de generación que tardan minutos, por lo que se mantiene explícita y se puede reintentar.

Para los agentes hospedados, la primera evaluación requiere un destino de agente implementado e invocable. Para los agentes basados en indicaciones, el paso de implementación no se aplica; el agente ya debe existir en el proyecto de Foundry y estar disponible como destino de evaluación.

Creación e implementación de un agente hospedado

Si aún no tiene un proyecto de agente hospedado, inicialice uno con azd:

azd ai agent init

Aprovisione los recursos de Foundry e implemente el agente:

azd provision
azd deploy

Una vez completada la implementación, compruebe que el agente es invocable:

azd ai agent show

El agente hospedado debe implementarse e invocarse antes de inicializar los recursos de evaluación.

Después de una implementación correcta, la CLI sugiere la evaluación como un paso siguiente explícito:

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

Para evaluar un agente basado en mensajes, omita los comandos de creación e implementación del agente hospedado. Continúe con la sección siguiente después de confirmar que el agente basado en mensajes existe en el proyecto Foundry y está disponible como destino de evaluación.

Inicialización de recursos de evaluación

Ejecute eval generate desde el área de trabajo de azd o la carpeta del proyecto del agente:

azd ai agent eval generate

Sin marcas, el comando inicia un asistente interactivo. El asistente detecta el objetivo del agente a partir del entorno de azd y, a continuación, solicita una instrucción de generación para que el servicio pueda crear datos semilla de evaluación y una rúbrica de evaluador.

Salida interactiva de ejemplo:

? 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 usarlo en scripts, pase directamente los parámetros de generación:

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

--out-file es opcional y tiene como valor predeterminado eval.yaml en la raíz del proyecto del agente. Use --out-file <path> para escribir la configuración en una ubicación diferente.

Para usar un conjunto de datos existente y evaluadores seleccionados:

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

Reemplace por ./tests/support-golden.jsonl la ruta de acceso a su propio conjunto de datos de evaluación.

El --dataset valor puede apuntar a un archivo local o a un nombre de conjunto de datos registrado. Repita esta operación --evaluator para incluir varios evaluadores personalizados integrados o registrados. Las referencias del evaluador usan el formato <source>.<name>:

• builtin.<name> : hace referencia a un evaluador integrado proporcionado por Foundry.
• <name> : hace referencia a un evaluador personalizado registrado en el proyecto Foundry. Use el nombre registrado del evaluador sin el sufijo de versión.

Aplazar la generación con --no-wait

Si la generación de conjuntos de datos o evaluador tarda demasiado tiempo, use --no-wait para enviar trabajos de generación y salir inmediatamente:

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

Los identificadores de operación pendientes se escriben en eval.yaml. Cuando se ejecuta azd ai agent eval runposteriormente, reanuda automáticamente esas operaciones antes de iniciar la ejecución de evaluación.

Use un destino de agente basado en indicaciones

Si inicializó recursos de evaluación para un agente basado en indicaciones, puede usar el mismo flujo de fórmula de evaluación. El paso de implementación de agente hospedado no es necesario para agentes basados en indicaciones.

Antes de ejecutar una evaluación, confirme que:

• El agente basado en indicaciones existe en el proyecto de Foundry.
• El agente está disponible como destino de evaluación.
• Usted tiene acceso al punto de conexión del proyecto y al destino de agente.
• eval.yaml selecciona el agente deseado basado en indicaciones.

Para enumerar los agentes disponibles en el proyecto foundry actual, ejecute:

azd ai agent list

A continuación, use los mismos comandos para ejecutar e inspeccionar la evaluación:

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

Revisar eval.yaml

Una vez que eval generate se complete correctamente, abra eval.yaml en la raíz del proyecto del agente. Por ejemplo:

src/reservation-agent/eval.yaml

Ejecute eval run desde este directorio o pase la ruta de acceso explícitamente con --config src/reservation-agent/eval.yaml. El archivo identifica el destino del agente, la referencia del conjunto de datos, las referencias del evaluador y las opciones de generación. Una forma simplificada es:

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 reside en la raíz del proyecto del agente, por ejemplo src/<agent-name>/eval.yaml.
• Los conjuntos de datos generados se encuentran en datasets/ y las rúbricas de evaluación generadas se encuentran en evaluators/ dentro de la carpeta del agente.
• Las rutas local_uri en eval.yaml son relativas al directorio del proyecto del agente.
• Los archivos locales a los que hace local_uri referencia son editables. Ejecute azd ai agent eval update para registrar los cambios locales como una nueva versión en el servicio y aumente la versión en eval.yaml.
• eval run usa la versión registrada anclada en eval.yaml. Para aplicar ediciones locales, ejecute eval update antes de eval run.
• Los evaluadores pueden ser referencias integradas (por ejemplo, builtin.task_adherence) o evaluadores personalizados generados con name, versiony local_uri.
• Trate los campos de versión como cadenas, aunque parezcan numéricos, por lo que la receta permanece estable entre analizadores de YAML.

Ejecución de la evaluación

En la carpeta del proyecto del agente, ejecute:

azd ai agent eval run

De forma predeterminada, eval run sin argumentos resuelve eval.yaml en la raíz del proyecto del agente. También puede indicar explícitamente la ruta de la configuración:

azd ai agent eval run --config eval.yaml

Si eval generate --no-wait creó operaciones de generación pendientes, eval run reanuda esas operaciones antes de iniciar la ejecución de la evaluación. No inicia nuevos trabajos de generación de conjuntos de datos ni evaluadores desde cero.

Inspeccionar ejecuciones de evaluación

Mostrar ejecuciones de evaluación recientes:

azd ai agent eval list

Mostrar la ejecución más reciente:

azd ai agent eval show

Sin indicadores, eval show usa por defecto la evaluación más reciente y muestra sus ejecuciones.

Para mostrar los detalles de una ejecución específica, pase el ID de evaluación como argumento y el ID de ejecución con --eval-run-id. Copie el Id. de eval. de la salida de azd ai agent eval list y el ID de ejecución de la salida de azd ai agent eval show <eval-id>:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Use la salida de ejecución para responder:

• ¿Qué versión del agente se ha evaluado?
• Qué versiones del conjunto de datos y del evaluador se ha resuelto.
• Indica si la ejecución se completó, produjo un error o se completó parcialmente.
• Qué métricas o puntuaciones del evaluador se generaron.
• Si el uso de tokens o los registros del evaluador requieren revisión.

Volver a ejecutar después de cambiar el agente

Después de actualizar y volver a implementar un agente hospedado, vuelva a ejecutar la misma receta de evaluación:

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

Para los agentes basados en indicaciones, actualice el agente en Foundry y, a continuación, vuelva a ejecutar la misma fórmula de evaluación.

Volver a ejecutar el mismo eval.yaml ayuda a mantener estables las referencias al conjunto de datos, al evaluador y al umbral a través de los cambios de agente.

Actualizar, restablecer o reparar recursos de evaluación

El flujo de evaluación del agente usa eval.yaml como receta de evaluación local. Use azd ai agent eval update al editar archivos de conjunto de datos locales o rubrices del evaluador y quiera registrar esas modificaciones como nuevas versiones de servicio.

Para actualizar lo que usa una ejecución de evaluación, elija la ruta de acceso que coincida con el tipo de cambio:

Por ejemplo, después de editar una rúbrica de evaluador generada debajo de evaluators/ en la carpeta del agente, ejecute:

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

El comando update crea nuevas versiones del conjunto de datos o evaluador registrados. Las ejecuciones de evaluación existentes permanecen vinculadas a las versiones que usaron originalmente.

Cuando eval.yaml ya existe, eval generate la detecta e imprime la configuración 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 generate --reset-defaults

Para sobrescribir la configuración local y volver a generar los recursos de evaluación predeterminados, ejecute:

azd ai agent eval generate --reset-defaults

--reset-defaults sobrescribe la eval.yaml local y vuelve a generar los recursos de evaluación predeterminados. No se eliminan las versiones existentes del conjunto de datos y evaluador registrados por el servicio; solo se reemplaza la receta local.

No confíe en versiones remotas más recientes que cambien la receta local de forma silenciosa. El eval.yaml local registra las versiones del conjunto de datos, del evaluador o de la suite utilizadas por la receta para garantizar la reproducibilidad.

Opcional: iniciar la optimización desde la señal de evaluación

Después de que al menos una ejecución de evaluación se realice correctamente, puede usar eval.yaml como entrada para la optimización del agente si el agente y la receta cumplen los requisitos previos de optimización.

Antes de iniciar la optimización, confirme que:

• El destino de agente está listo para optimización. En el caso de los agentes alojados, el agente se despliega y se puede invocar.
• eval.yaml hace referencia al agente, el conjunto de datos, las versiones del evaluador y los umbrales previstos.
• Al menos una ejecución de evaluación se completó correctamente.
• La preparación del agente requerida por el optimizador está completa. Para conocer los requisitos previos del optimizador y los requisitos de preparación del agente, consulte Optimización de avisos del agente con el optimizador de mensajes.

A continuación, ejecute:

azd ai agent optimize --config eval.yaml

El comando optimize lee el objetivo del agente, el conjunto de datos, los evaluadores y los umbrales desde eval.yaml. Envía una tarea de optimización, pero no aplica de manera silenciosa los cambios en el código fuente ni vuelve a desplegar el agente candidato. Revise cualquier salida del optimizador antes de aplicar los cambios.

procedimientos recomendados

• Ejecute azd ai agent eval generate solo después de que el agente esté disponible como destino de evaluación. Para los agentes alojados, el agente debe estar desplegado y ser invocable.
• Comience con un pequeño conjunto de datos generado o un pequeño subconjunto del conjunto de datos dorado.
• Compruebe el conjunto de datos generado y los resultados de la revisión del evaluador antes de confiar en las puntuaciones.
• Después de editar los archivos de conjunto de datos o evaluadores generados, ejecute azd ai agent eval update para registrar los recursos editados antes de volver a ejecutar la evaluación.
• Controle el código fuente de eval.yaml si su equipo desea una fórmula de evaluación revisable y reproducible.
• Considere la posibilidad de controlar el código fuente de los conjuntos de datos generados y las rubrices del evaluador en datasets/ y evaluators/ en la carpeta del agente si el equipo las revisa y las edita como parte de la receta de evaluación.
• Vuelva a ejecutar lo mismo eval.yaml después de que el agente cambie para que las comparaciones usen la misma receta de prueba.
• Use azd ai agent optimize --config eval.yaml solo después de tener un resultado de evaluación de línea base útil y el agente esté preparado para la optimización.

Limitaciones

• El flujo de comandos principal está optimizado para agentes hospedados y el bucle de evaluación posterior a la implementación.
• azd provision no crea recursos de evaluación.
• eval run no genera nuevos conjuntos de datos ni evaluadores, excepto para reanudar las operaciones pendientes desde eval generate --no-wait.
• El ciclo de vida completo del conjunto de aplicaciones, la evaluación programada, la evaluación continua, las alertas y los flujos de trabajo de comparación no son necesarios para la primera ruta de evaluación.

Contenido relacionado

• Evaluación de los agentes de IA
• Evaluación humana de agentes de Microsoft Foundry
• Análisis de clústeres de evaluación
• Optimización de avisos del agente con prompt Optimizer
• Configurar el seguimiento para agentes de IA en Microsoft Foundry
• Supervisión de agentes con el panel de supervisión del agente
• Agentes hospedados en Foundry Agent Service
• Ciclo de vida de desarrollo del agente