Inicio rápido: Optimización de un agente hospedado (versión preliminar)

Importante

El optimizador de agentes está actualmente en versión preliminar. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

En este inicio rápido, debe implementar el agente de ejemplo de optimización, ejecutar el optimizador de agentes para mejorar sus instrucciones e implementar el candidato ganador.

Para conocer los conceptos que hay detrás de cada paso y la ruta de acceso completa de un extremo a otro, consulte el flujo de trabajo de optimización.

Prerrequisitos

Antes de comenzar, necesita lo siguiente:

  • azd CLI (AZURE CLI para desarrolladores).

  • CLI de Azure para la autenticación.

  • La extensión microsoft.foundry para azd (versión 0.1.40-preview o posterior de la dependencia azure.ai.agents):

    azd ext install microsoft.foundry

    Si ya está instalado, actualice:

    azd ext upgrade microsoft.foundry

  • CLI de Azure para la autenticación.

  • Python 3.10 o posterior.

  • Los paquetes de Python usados en esta ruta de acceso:

    pip install "azure-ai-projects>=2.4.0" azure-ai-agentserver-optimization azure-identity python-dotenv

  • Un proyecto foundry existente que ya contiene el agente hospedado, el conjunto de datos registrado y el evaluador que desea usar para la optimización.

Tip

Si no tiene Foundry Toolkit, instálelo desde Visual Studio Code Marketplace. Foundry Toolkit incluye los recursos de Foundry, el catálogo de modelos, la implementación de agentes hospedados y los juegos de juegos, y la optimización del agente en Visual Studio Code. Vuelva a cargar Visual Studio Code si se le solicita e inicie sesión en Azure. Para obtener un paseo por la extensión, consulte Trabajar con el kit de herramientas de Microsoft Foundry para Visual Studio Code extensión.

  • La suscripción de Azure debe estar en la lista de permitidos del optimizador de agentes. Póngase en contacto con su representante de Microsoft para solicitar acceso.

Note

El optimizador de agentes está actualmente en versión preliminar.

Paso 1: Crear el proyecto

Inicialice un nuevo proyecto a partir de la plantilla de ejemplo de optimización:

mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .

Esta plantilla importa el ejemplo de soporte al cliente de optimización, un agente hospedado listo Python para la optimización que usa el enfoque bring-your-own y el protocolo De respuestas. Representa un agente de soporte técnico de electrónica de consumidor que controla las consultas de pedidos, devoluciones, reclamaciones de garantía, solución de problemas, quejas, recomendaciones y escalación. La instrucción de línea base mínima deliberadamente hace que las mejoras de la optimización de instrucciones y la detección de aptitudes sea fácil de comparar.

El ejemplo llama load_config() a para cargar la configuración de línea base o candidata e incluye .agent_configs/baseline/los eval.yamlconjuntos de datos de evaluación completa y rápida, la configuración del contenedor y el manifiesto de implementación de Foundry. El flujo interactivo importa estos archivos y solicita la suscripción, la región y la configuración de implementación del modelo de Azure.

Tip

Si ya tiene un proyecto de agente existente, consulte Preparar su agente para el optimizador para agregar compatibilidad con la optimización.

Si ya tiene un proyecto de Foundry, agregue -p <project-resource-id> para dirigirse a los recursos existentes.

Paso 2: Aprovisionamiento e implementación

Autentíquese y aprovisione los recursos de Azure:

az login
azd auth login
azd provision

El aprovisionamiento tarda aproximadamente dos minutos y crea una cuenta, proyecto, Azure Container Registry y implementaciones de modelos de Foundry.

Despliegue el agente:

azd deploy

Pruebe la implementación:

azd ai agent invoke "What is 2+2?"

Paso 3: Generación de conjuntos de evaluación y optimización

Genere un conjunto de datos de evaluación y evaluadores para el agente:

azd ai agent eval generate

Este paso crea eval.yaml, un conjunto de datos de prueba y evaluadores de puntuación basados en las instrucciones de su agente. El optimizador usa estos archivos para medir la mejora.

Ejecute el optimizador:

azd ai agent optimize --max-candidates 2

La CLI le pide que seleccione un modelo de optimización. Para omitir el mensaje, páselo directamente:

azd ai agent optimize --max-candidates 2 --optimize-model gpt-5

La interfaz de línea de comandos detecta su agente a partir de azure.yaml y usa automáticamente el eval.yaml generado. Con dos candidatos, la optimización se completa normalmente en unos 8 minutos. Se muestra el progreso en tiempo real:

Optimizing agent "customer-support-py"...
  Config: eval.yaml
  Baseline saved to .agent_configs/baseline/metadata.yaml
  Job ID: opt_162bd0f09....
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

Use la dirección URL del portal para supervisar su tarea en el portal de Foundry.

El modelo eval puntúa cada respuesta (cualquier modelo de finalización de chat funciona). El modelo de optimización (--optimize-model) genera candidatos mejorados y debe ser de la lista admitida (familia gpt-5 o DeepSeek). También puede establecer optimization_model debajo de options: en eval.yaml para evitar tener que pasar el indicador cada vez.

Paso 4: Implementar la opción ganadora

La estrella (*) en la salida indica el mejor candidato. Aplique la configuración optimizada localmente y, a continuación, implemente:

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

El comando apply descarga la configuración optimizada en .agent_configs/<candidate_id>/ y actualiza tu azure.yaml para usar las nuevas instrucciones. El comando deploy pone en producción el agente optimizado mediante CodeDeploy.

Invoque al agente para comprobar la mejora:

azd ai agent invoke "What is your return policy?"

También puede ejecutar la evaluación para confirmar la mejora de la puntuación:

azd ai agent eval run

ruta de acceso del SDK de Python

Siga estos pasos si desea ejecutar el optimizador desde Python en lugar del flujo de trabajo de la CLI para desarrolladores de Azure descrito anteriormente.

Esta opción asume que ya dispone de los siguientes recursos en un proyecto de Foundry existente:

  • Un agente alojado para optimizar.
  • Un conjunto de datos de entrenamiento registrado.
  • Evaluador registrado.

A diferencia del flujo de la CLI para desarrolladores de Azure descrito anteriormente, la vía del SDK de Python no crea la estructura de un proyecto ni genera eval.yaml, un conjunto de datos ni evaluadores por usted. Si desea que el ejemplo cree esos recursos automáticamente, use azd ai agent eval generate primero.

1. Crear un .env archivo

Cree una carpeta de trabajo y agregue un .env archivo con estos valores:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>

Ejecute el script desde esta misma carpeta de trabajo para load_dotenv() que pueda cargar el .env archivo automáticamente. Si prefiere ejecutarlo desde otro directorio, establezca primero los mismos valores en el entorno de shell.

Use el punto de conexión exacto de la página Información general de su proyecto de Foundry. El script Python envía inmediatamente su primera solicitud. Si FOUNDRY_PROJECT_ENDPOINT solo es un marcador de posición o apunta al proyecto incorrecto, se produce un error en la ejecución con ResourceNotFound: The project does not exist.

Configure EVAL_MODEL y OPTIMIZATION_MODEL con nombres de implementación que ya existan en su proyecto de Foundry, no solo con nombres de familias de modelos. Por ejemplo, si la implementación del proyecto se denomina gpt-4.1-mini o DeepSeek-V3.2, use ese nombre exacto de implementación en .env.

2. Ejecutar el trabajo de optimización

Cree un archivo denominado optimize_hosted_agent.py en la misma carpeta que .env:

import os
import time

from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  OptimizationAgentIdentifier,
  OptimizationEvaluatorRef,
  OptimizationJob,
  OptimizationJobInputs,
  OptimizationOptions,
  OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))

optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = OptimizationJob(
    inputs=OptimizationJobInputs(
      agent=OptimizationAgentIdentifier(agent_name=agent_name),
      train_dataset=OptimizationReferenceDatasetInput(
        name=dataset_name,
        version=dataset_version,
      ),
      evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
      options=OptimizationOptions(
        max_candidates=2,
        eval_model=eval_model,
        optimization_model=optimization_model,
        optimization_config={
          "system_prompt": optimization_config.instructions,
          **({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
          **({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
        }
      ),
    )
  )
  poller = project_client.beta.agents.begin_create_optimization_job(job=job)

  print(f"Optimization job started, waiting for completion...")
  while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

  result = poller.result()

  if result:
    print(f"Baseline candidate: {result.baseline}")
    print(f"Best candidate: {result.best}")

    for candidate in result.candidates or []:
      print(
        f"{candidate.name}: candidate_id={candidate.candidate_id}, "
        f"avg_score={candidate.avg_score:.4f}, "
        f"avg_tokens={candidate.avg_tokens:.0f}"
      )

Ejecute el script:

python optimize_hosted_agent.py

Cuando la tarea se completa correctamente, el script imprime el candidato ganador y su candidate_id.

A diferencia de azd ai agent optimize, el flujo del SDK de Python no crea el archivo local .agent_configs/baseline/metadata.yaml. Los metadatos del trabajo de optimización permanecen en el objeto devuelto job y en la respuesta del servicio Foundry, incluido el candidato de línea base, el mejor candidato y la lista de candidatos puntuados.

3. Aplicar el candidato ganador

Si también estás trabajando desde el proyecto local azd utilizado en el flujo de la CLI anterior, aplica el candidato ganador usando el candidate_id devuelto por el script de Python:

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

Si solo necesita inspeccionar el resultado, use las puntuaciones de candidatos y los identificadores de evaluación impresos por el script para revisar la configuración ganadora en Foundry antes de promocionarlo.

Ejecución de la optimización en VS Code

Foundry Toolkit incluye una experiencia nativa de optimización del agente para agentes hospedados implementados. Desde el área de juegos del agente, puede iniciar una ejecución de optimización, comparar candidatos con la línea base, inspeccionar los cambios de configuración e implementar el mejor candidato.

Paso 1: Seleccionar un agente hospedado implementado

  1. Seleccione Foundry Toolkit en la barra de actividades.
  2. En Mis recursos, seleccione Agentes.
  3. Si tiene un agente hospedado implementado, selecciónelo para abrir el área de juegos del agente hospedado.
  4. Si no tiene un agente hospedado implementado, complete la ruta de acceso de VS Code en Inicio rápido: Implementación del primer agente hospedado. Una vez finalizada la implementación, vuelva a Agentes y seleccione el nuevo agente hospedado.

Paso 2: Iniciar una ejecución de optimización

  1. Seleccione la pestaña Optimizar , que está marcada como Vista previa.

Captura de pantalla de un agente hospedado en Foundry Toolkit con la pestaña Optimizar vista previa seleccionada y el botón Nueva optimización disponible.

  1. Seleccione Nueva optimización.

  2. En Seleccionar área de trabajo, elija el área de trabajo que contiene el código del agente hospedado seleccionado:

    • Seleccione Área de trabajo actual si el área de trabajo actual contiene el código del agente y su azure.yaml archivo.
    • Seleccione Examinar... para abrir el área de trabajo que contiene el código del agente.

    Foundry Toolkit usa los archivos del área de trabajo para preparar la optimización y aplicar un candidato al servicio coincidente azure.ai.agent .

Captura de pantalla del símbolo del sistema Seleccionar área de trabajo en Foundry Toolkit en la que se muestran las opciones Área de trabajo actual y Examinar para buscar el código del agente hospedado.

  1. Foundry Toolkit abre gitHub Copilot Chat y envía una solicitud del optimizador de agentes rellenada con el tipo, el nombre y el punto de conexión del proyecto foundry del agente seleccionado.

  2. Responda a las cuatro preguntas de optimización de Copilot Chat:

    Entrada Qué proporcionar
    Métricas de evaluación Escriba las métricas o evaluadores que se van a usar. Si no los tiene, elija si desea ejecutar azd ai agent eval generate o usar los valores predeterminados integrados del optimizador.
    Dataset Seleccione el conjunto de datos de optimización. Si no tiene una, elija si desea ejecutar azd ai agent eval generate o usar los valores predeterminados integrados del optimizador.
    Número máximo de candidatos Escriba el número máximo de candidatos que se van a generar, como 2.
    Modelo de optimización Seleccione una implementación existente en los modelos de optimización admitidos.

GitHub Copilot espera estas entradas antes de iniciar la optimización. La solicitud generada dirige Copilot para usar exclusivamente el flujo de trabajo del optimizador de agentes de Microsoft Foundry Skill y Azure comandos de la CLI para desarrolladores. No usa herramientas de MCP de Foundry. Copilot:

  • Inspecciona el código del agente en el área de trabajo seleccionada.
  • Inicializa un entorno de AZD a partir de los valores existentes azure.yaml y .env si el proyecto aún no tiene uno.
  • Conecte el agente para la optimización e implemente el agente hospedado actualizado.
  • Crea eval.yaml en la carpeta del servicio del agente.
  • Inicia la optimización después de revisar y aprobar los cambios y comandos de archivo propuestos.

Después de Copilot envía el trabajo, vuelva a la pestaña Optimizar. La ejecución aparece en Ejecuciones de optimización. En la tabla se muestra su identificador de ejecución, el estado, el recuento de candidatos, la puntuación de línea de base, la mejor puntuación y el tiempo de creación.

Paso 3: Comparar e implementar el mejor candidato

  1. Cuando la ejecución se realice correctamente, selecciónela en Ejecuciones de optimización.
  2. Compare las puntuaciones De línea base y Mejor . Revise Los detalles de puntuación de cada candidato y seleccione Ver cambios para inspeccionar sus cambios de configuración.
  3. Si el mejor candidato mejora en la línea base, seleccione Implementar mejor candidato para actualizar el agente actual. Para implementarlo como agente nuevo o cambiar la configuración de implementación, seleccione Implementación personalizada en su lugar.

Note

Si cada candidato puntúa por debajo de la línea base, no implemente un candidato. Mantenga el agente actual y revise el conjunto de datos o la configuración de optimización antes de volver a ejecutar el optimizador.

Captura de pantalla de una ejecución de optimización completada en Foundry Toolkit que compara la línea base y los candidatos generados, con puntuaciones, cambios de configuración y opciones de implementación.

Ejecución de la optimización con la aptitud Microsoft Foundry

Use esta ruta de acceso en cualquier host de agente de codificación que admita la aptitud de Microsoft Foundry, como GitHub Copilot en Visual Studio Code, Copilot CLI o Claude Code. La aptitud resuelve el contexto del agente desde azure.yaml, carga su flujo de trabajo del optimizador de agentes y mantiene la aplicación candidata y la implementación detrás de las puertas de revisión.

Paso 1: Abrir el área de trabajo del agente

Abra una carpeta vacía en el host del agente de codificación. Confirme que la microsoft-foundry aptitud está disponible. Si la habilidad no está disponible, consulte Uso de la habilidad de Microsoft Foundry en agentes de programación.

Paso 2: Preguntar a la aptitud para ejecutar el optimizador del agente

Envíe este mensaje al agente de codificación:

Use the Microsoft Foundry Skill to run the Agent Optimizer workflow for a
Python hosted agent. If this workspace doesn't contain an agent, initialize the
customer support optimization sample from this template:
https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml
Resolve the AZD environment and hosted-agent service, verify that the agent is
optimizer-ready, and deploy and invoke the baseline. Generate and show me the
evaluation dataset, evaluators, and eval.yaml before running optimization.
Verify that the project has a supported optimization model deployment, then run
Agent Optimizer with two candidates. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.

El agente de codificación puede pedirle que seleccione una suscripción, región, proyecto Foundry, servicio de agente, modelo de evaluación o modelo de optimización cuando no pueda resolver esos valores desde el área de trabajo. Revise los archivos generados y los recursos de costo antes de aprobar los cambios o comandos.

Paso 3: Aplicar e implementar un candidato aprobado

Después de revisar los resultados de optimización, envíe este mensaje de seguimiento:

Recommend the best optimization candidate and explain the score improvement.
Summarize the candidate changes before applying anything. After I approve the
candidate, apply it locally, show the source diff, and stop again before
deployment. After I approve deployment, run azd deploy, invoke the agent with
"What is your return policy?", and rerun the evaluation to confirm the
improvement.

La aptitud usa azd ai agent optimize apply --candidate <candidate-id> para poder revisar la configuración optimizada localmente. Solo se implementa después de la aprobación y, a continuación, invoca y evalúa el agente hospedado actualizado.

Limpieza de recursos

Si el flujo de trabajo creó recursos a través del proyecto de AZD, elimine los recursos aprovisionados cuando termine de experimentar:

azd down --force --purge

Tip

¿Por qué --purge? Las cuentas de Foundry utilizan el borrado lógico de forma predeterminada. Sin --purge, el nombre del recurso permanece reservado durante 48 horas y se produce un error en el reaprovisionamiento con el mismo nombre.

Solución de problemas

Problema Causa Corregir
Comando azd ai agent optimize no encontrado Extensión demasiado antigua Ejecute azd ext upgrade microsoft.foundry para obtener la versión preliminar 0.1.40 o posterior.
optimization_model is required Ejecución en modo no interactivo sin un modelo configurado Agregue --optimize-model gpt-5 al comando o establezca optimization_model: gpt-5 en options: dentro de eval.yaml. En modo interactivo, la CLI solicita la selección del modelo.
Python script produce un error con KeyError: 'DATASET_NAME' u otra variable que falta. El script no cargó .env el archivo o falta la variable Ejecute el script desde la misma carpeta que .envo exporte los valores necesarios en el shell antes de ejecutar python optimize_hosted_agent.py.
El script de Python falla con ResourceNotFound: The project does not exist FOUNDRY_PROJECT_ENDPOINT no apunta a un proyecto de Foundry existente Copie el punto de conexión del proyecto desde la página Información general del proyecto Foundry y actualice FOUNDRY_PROJECT_ENDPOINT en .env.
El script de Python falla con Optimization model deployment '<name>' not found OPTIMIZATION_MODEL no es el nombre de un modelo implementado en tu proyecto de Foundry. Usa el nombre exacto de la implementación de Build>Implementaciones, como una familia gpt-5 existente o una implementación de DeepSeek en tu proyecto.
La sección Optimizar no aparece para un agente hospedado. Foundry Toolkit es anterior a la versión 1.6.4 o el agente seleccionado no es un agente hospedado implementado. Actualice Foundry Toolkit, vuelva a cargar Visual Studio Code y vuelva a abrir el agente implementado desde la pestaña Agentes.
GitHub Copilot Chat no se abre después de seleccionar el área de trabajo GitHub Copilot no está instalado, no está disponible para la cuenta o el modo de agente está deshabilitado. Configure GitHub Copilot en Visual Studio Code, habilite el modo de agente y, a continuación, vuelva a seleccionar Nueva optimización.
Foundry Toolkit no puede aplicar el mejor candidato al área de trabajo actual El área de trabajo no contiene un azure.yaml servicio cuyo nombre coincide con el agente hospedado implementado Abra el área de trabajo que contiene el código del agente seleccionado y el servicio coincidente azure.ai.agent y vuelva a intentarlo.
El agente de codificación no encuentra el agente hospedado La carpeta incorrecta está abierta o azure.yaml no define un azure.ai.agent servicio Abra la carpeta del proyecto AZD que contiene azure.yamly, a continuación, pida al agente de codificación que resuelva de nuevo el servicio hosted-agent.
El agente de codificación se detiene antes de aplicar o implementar un candidato La aptitud Del optimizador de agentes requiere revisión antes de los cambios de origen y la implementación. Revise las puntuaciones de candidatos y la diferencia local y, a continuación, apruebe explícitamente el paso de aplicación o implementación.
La puntuación de optimización es 0 o muy baja La evaluación tiene muchas filas con errores Abra el vínculo Eval en los resultados. Corrija los errores de generación de respuestas o del evaluador y vuelva a ejecutar.
azd provision falla con un error de cuota La suscripción carece de capacidad Pruebe otra región o solicite un aumento de cuota.

Lo que ha aprendido

En esta guía de inicio rápido:

  • Implementó el agente de ejemplo de optimización mediante la plantilla de soporte técnico al cliente.
  • Ejecutó el optimizador de agentes mediante la CLI para desarrolladores de Azure, Python SDK, Visual Studio Code o la aptitud Microsoft Foundry.
  • Implementó el candidato ganador y comprobó la mejora.

Pasos siguientes

  • Last updated on