Optimización de instrucciones, aptitudes, herramientas y modelos del agente (versión preliminar)

El optimizador de agentes mejora cuatro aspectos del agente hospedado: instrucciones, aptitudes, herramientas y selección de modelos. Detecta automáticamente cuáles de estos objetivos optimizar a partir de la configuración base del agente.

En este artículo se muestra cómo ejecutar una optimización, configurar y supervisar la ejecución e implementar los resultados. Para conocer lo que hace cada destino y cuándo se activa, consulte Objetivos de optimización. Para configurar las entradas de referencia, consulte Prepare su agente para el optimizador. Para obtener una referencia rápida sobre los cambios del optimizador, consulte ¿Qué cambia cada destino?

Prerrequisitos

• Un proyecto de Foundry con un agente hospedado implementado
• La extensión de la CLI azure.ai.agents instalada (consulte Inicio rápido: Optimizar un agente alojado)
• Un modelo implementado para la evaluación (por ejemplo, gpt-4.1-mini) y un modelo de optimización de la lista admitida (por ejemplo, gpt-5.1)
• El agente está listo para optimizador (llama a load_config())

Ejecución de una optimización

Inicie una ejecución de optimización con un solo comando:

azd ai agent optimize

El optimizador evalúa la línea base, genera candidatos, los evalúa y clasifica los resultados. Para obtener el ciclo completo de evaluación y mejora, consulte Funcionamiento del optimizador de agentes. Los objetivos que se ejecutan dependen de tu configuración base: el ajuste de instrucciones, la mejora de capacidades y la optimización de herramientas se activan automáticamente cuando están presentes los archivos de base correspondientes. Consulte Objetivos de optimización.

Para controlar la ejecución con un archivo de configuración, pase un eval.yaml que haga referencia al conjunto de datos, evaluadores y opciones:

azd ai agent optimize --config eval.yaml

Para obtener el esquema completo eval.yaml , consulte Configuración de la ejecución de optimización.

Dirigir a un agente específico

La forma en que la CLI resuelve el agente depende de si ejecuta el comando desde un azd proyecto:

El nombre del agente implementado debe coincidir con un agente hospedado en el proyecto foundry de destino.

Optimización de un agente existente sin archivos de proyecto de AZD

Puede optimizar un agente hospedado existente sin ejecutar azd ai agent init ni crear azure.yaml ni un .azure directorio de entorno. En este flujo independiente, proporcione explícitamente el punto de conexión del proyecto Foundry y el nombre del agente implementado.

1. Asegúrese de que el agente implementado está listo para optimizar. En un directorio de trabajo local, cree el archivo de instrucciones, el conjunto de datos, los evaluadores y eval.yaml, descritos en Configurar la ejecución de optimización.

   Ejecute el comando desde este directorio de trabajo. Sin un proyecto azd, las rutas relativas en eval.yaml se resuelven desde el directorio de trabajo actual.

   Para este flujo independiente, omita agent.config. La CLI solicita la instrucción de línea base al ejecutar el comando:

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. Autenticación:

   az login
   azd auth login
   

3. Copie el punto de conexión del proyecto desde la página Información general del proyecto Foundry. Use la dirección URL del punto de conexión del proyecto, no el identificador de recurso de Azure.

4. Guarde el punto de conexión en la configuración de nivel azd de usuario para que los comandos posteriores puedan resolver el mismo proyecto desde cualquier directorio:

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   Este paso escribe el punto de conexión predeterminado en ~/.azd/config.json. Para conocer el orden de resolución completo y los comandos para inspeccionar o borrar el contexto guardado, consulte Establecer el contexto del proyecto de Foundry para los comandos azd.

5. Ejecute la optimización con el nombre del agente implementado:

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   Cuando se le solicite la instrucción del agente, introdúzcala directamente o seleccione un archivo como .agent_configs/baseline/instructions.md.

   Note

   En la vista previa actual, una ejecución independiente no expande agent.config a partir de eval.yaml. Ejecute el comando de forma interactiva para que pueda proporcionar la instrucción de línea base. No use --no-prompt para este flujo. La carga de líneas de base de habilidades y herramientas basadas en archivos también requiere un proyecto azd.

   Para un comando de un solo uso que no debe cambiar la configuración de nivel de usuario, pase --project-endpoint:

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   También puede establecer el punto de conexión para el shell actual:

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. Guarde el ID de la operación de la salida del comando. Dado que este flujo no tiene ningún azd entorno, la CLI no conserva el último identificador de operación localmente. Pase el identificador de la operación a los comandos de seguimiento:

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   Estos comandos usan el punto de conexión guardado por azd ai project set. Si ha usado el formulario de un solo uso --project-endpoint en su lugar, vuelva a pasar la marca a cada comando de seguimiento.

Configuración de la ejecución de optimización

La configuración de la optimización se ejecuta a través de un eval.yaml archivo que vincula el conjunto de datos, los evaluadores y las opciones de ejecución. El comando azd ai agent eval generate escribe este archivo automáticamente o puede crearlo a mano. El optimizador detecta eval.yaml automáticamente en la raíz del proyecto o puede pasarlo explícitamente con --config eval.yaml.

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

Cree el conjunto de datos y evaluadores por separado; consulte Creación de un conjunto de datos de evaluación y evaluadores. En las secciones siguientes se describen las opciones de ejecución.

Elección de los modelos de evaluación y optimización

El optimizador usa dos modelos: un modelo de evaluación que puntúa las respuestas del agente con criterios y un modelo de optimización que genera configuraciones candidatas. Configúrelos en eval.yaml o use opciones de la CLI.

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

Cualquier modelo de autocompletado de chat implementado en tu proyecto funciona como modelo de evaluación. El modelo de optimización debe figurar en la lista de modelos compatibles. Para ver los roles y los modelos admitidos, consulte Modelos.

Establecer el número de candidatos

La max_candidates opción establece el número esperado de configuraciones candidatas para la ejecución. El optimizador normalmente devuelve después de alcanzar ese recuento, a menos que la ejecución se detenga antes debido a un error u otra condición de detención.

Los valores más altos exploran más variaciones, pero tardan más tiempo. El optimizador aprende de candidatos anteriores, por lo que los candidatos posteriores tienden a puntuar más alto.

Evaluación de varios modelos

Para comparar los despliegues de modelos en una sola ejecución, enumérelos bajo optimization_config.model_search_space. El optimizador evalúa tu agente con cada uno de los modelos usando el mismo conjunto de datos y clasifica los resultados por puntuación y coste de tokens.

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

Cada modelo enumerado en model_search_space debe desplegarse en su proyecto de Foundry.

La selección de modelos se ejecuta en paralelo con los objetivos que se activan automáticamente a partir de tu línea base. Una sola ejecución puede generar candidatos que combinan instrucciones, habilidades y descripciones de herramientas mejoradas con distintas opciones del modelo; no tiene que configurar usted mismo la combinación.

Supervisión de un trabajo en ejecución

Una ejecución de optimización es asincrónica. Use estos comandos cuando un trabajo sea de ejecución prolongada o desee comprobar su progreso:

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <operation-id>

Recopile el identificador de la operación, la dirección URL del portal, las puntuaciones y los identificadores de los candidatos del resultado de la ejecución. También puede supervisar el trabajo en el portal de Foundry mediante la dirección URL que se muestra cuando se inicia la ejecución.

Si inició el trabajo sin archivos de proyecto de AZD, pase siempre el identificador de operación a status y cancel. Los comandos usan el punto de conexión de nivel de usuario almacenado con azd ai project set; de lo contrario, incluya --project-endpoint.

Interpretación de los resultados

Una vez completada la optimización, revise la tabla de resultados. Un asterisco (*) marca el mejor candidato. Para ver las columnas de la tabla de resultados, los detalles de puntuación, los umbrales de mejora de puntuación y la vista del portal, consulte Descripción de los resultados de la optimización.

Implementar al ganador

El flujo de trabajo recomendado es aplicar la configuración optimizada localmente y, a continuación, implementar:

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

Esto descarga la configuración optimizada en .agent_configs/<candidate_id>/ dentro de tu proyecto. En la siguiente implementación, el agente usa las instrucciones mejoradas y las descripciones de herramientas.

Como alternativa, puede implementar directamente a través de la API (útil para pruebas rápidas de A/B):

azd ai agent optimize deploy --candidate <candidate-id>

Si todos los candidatos puntúan por debajo de la línea base, no implemente ningún candidato. La configuración de línea base permanece activa.

Qué cambia en cada destino

El optimizador activa automáticamente los objetivos que se aplican a su referencia. Esta sección es una referencia para lo que cambia una ejecución. Use la tabla siguiente para anticipar lo que hace la optimización para el agente:

El código permanece igual en todos los destinos porque load_config() devuelve automáticamente los valores optimizados. Solo la configuración que ve el modelo cambia.

Instrucciones

El optimizador reescribe el prompt del sistema. Entre las mejoras comunes se incluyen las siguientes:

• Agregar restricciones explícitas que la indicación original daba a entender, pero no establecía con claridad
• Instrucciones de reestructuración para mayor claridad
• Adición de especificaciones de formato de salida
• Fortalecimiento de los límites de seguridad y ámbito

Por ejemplo, una instrucción base mínima como You are a helpful assistant. podría convertirse en:

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Habilidades

El optimizador refina la descripción, el cuerpo y los criterios de activación de cada aptitud, a la vez que mantiene intacto el propósito de la aptitud. El agente carga habilidades mejoradas a través de load_config(), que las añade al conjunto de instrucciones. Las habilidades usan el formato abierto Agent Skills. Para saber cómo carga tu agente las habilidades, consulta Prepara tu agente para el optimizador.

Herramientas

El optimizador refina las tools.json definiciones. Entre las mejoras comunes se incluyen las siguientes:

• Descripciones de funciones más claras que ayudan al modelo a saber cuándo llamar a una herramienta
• Descripciones de parámetros más específicas que reducen argumentos inexactos
• Restricciones agregadas (enumeraciones, campos obligatorios) que impiden entradas no válidas

El código de implementación de la herramienta sigue siendo el mismo. Solo las definiciones que ve el modelo cambian.

Models

El optimizador clasifica cada modelo candidato por puntuación compuesta y costo de token, por lo que puede elegir el mejor equilibrio de calidad a costo. Para configurar los candidatos, consulte Evaluación de varios modelos.

Solución de problemas

Contenido relacionado

• Introducción al optimizador de agentes
• Haz que tu agente esté listo para el optimizador
• Crear un conjunto de datos de evaluación y evaluadores
• Inicio rápido: Optimización de un agente hospedado