Haz que tu agente esté listo para el optimizador (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.

Añadir compatibilidad con el optimizador de agentes a su agente solo requiere unas pocas líneas de código. No se necesitan cambios en el marco ni lógica condicional. Instale el paquete de optimización, configure un directorio de configuración y llame load_config() al inicio.

Este paso es el primer paso del flujo de trabajo de optimización. La configuración de línea base que cree define las entradas que mejora el optimizador: instrucciones, herramientas, aptitudes y el modelo. El agente funciona igual si la optimización está activa o no.

Para que su agente esté listo para el optimizador, complete estos tres pasos:

  1. Instale el paquete de optimización.
  2. Configure un directorio de configuración de línea base con sus instrucciones y, opcionalmente, herramientas y aptitudes.
  3. Cargue la configuración en el inicio con load_config() y use los valores que devuelve.

En el resto de este artículo se proporciona un ejemplo completo y se explica cómo funciona la resolución de configuración. Una vez finalizada una ejecución de optimización, aplique el candidato ganador y despliéguelo; consulte Desplegar el ganador.

Prerrequisitos

Instalación del paquete de optimización

Instala el paquete azure-ai-agentserver-optimization:

pip install azure-ai-agentserver-optimization

Configuración del directorio de configuración

Crea el directorio .agent_configs/baseline/ en la raíz de tu proyecto. Este directorio define la configuración de línea base del agente: el punto de partida en el que el optimizador lee y mejora.

my-agent/
|- main.py
|- azure.yaml
|- requirements.txt
\- .agent_configs/
   |- baseline/              <- your starting config
   |  |- metadata.yaml
   |  |- instructions.md
   |  |- tools.json
   |  \- skills/
   |     \- (initially empty)
   \- <candidate_id>/        <- created by 'azd ai agent optimize apply'
      \- (same layout as baseline/)

La línea base requiere metadata.yaml y instructions.md. El archivo tools.json y el directorio skills/ son opcionales; inclúyalos solo si el agente usa herramientas o habilidades. El optimizador activa cada destino en función de cuáles de estos archivos están presentes.

metadata.yaml

El archivo de metadatos indica al cargador de optimización dónde buscar archivos de configuración y qué modelo usar:

model: gpt-4.1-mini
instruction_file: instructions.md
tools_file: tools.json
skill_dir: skills
Campo Obligatorio Description
model Sí Nombre de implementación del modelo (por ejemplo, gpt-4.1-mini, gpt-5.1)
instruction_file Sí Ruta relativa al archivo del prompt del sistema
tools_file No Ruta de acceso relativa al archivo JSON de definiciones de herramientas
skill_dir No Ruta de acceso relativa al directorio de aptitudes
temperature No Temperatura del modelo de generación

instructions.md

Indicación del sistema del agente. Escríbelo como texto sin formato o Markdown:

You are a travel approval agent for Contoso Ltd. You review travel
requests and enforce company travel policy. Check travel policy limits,
department budget, and suggest cheaper alternatives when appropriate.
Enforce policy rules strictly — do not auto-approve everything.

El optimizador mejora este mensaje durante las ejecuciones de optimización. Después de aplicar un candidato optimizado, este archivo contiene la versión mejorada.

tools.json

Declare las herramientas a las que puede llamar el agente mediante el formato de llamada a funciones de OpenAI:

[
  {
    "type": "function",
    "function": {
      "name": "lookup_travel_policy",
      "description": "Look up the company travel policy rules and limits.",
      "parameters": {
        "type": "object",
        "properties": {}
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "get_flight_alternatives",
      "description": "Find cheaper flight alternatives for the given destination.",
      "parameters": {
        "type": "object",
        "properties": {
          "destination": {
            "type": "string",
            "description": "The travel destination city"
          }
        },
        "required": ["destination"]
      }
    }
  }
]

El optimizador puede mejorar las descripciones de herramientas para ayudar al modelo a invocar herramientas con mayor precisión. Después de la optimización, se vuelven a aplicar descripciones mejoradas en este archivo.

skills/ (formato de habilidades del agente)

Las habilidades usan el formato abierto Agent Skills. Cada aptitud es una carpeta que contiene un SKILL.md archivo:

skills/
\-- policy-reviewer/
    \-- SKILL.md

Un archivo SKILL.md tiene una cabecera YAML con metadatos y un cuerpo en Markdown con instrucciones:

---
name: policy-reviewer
description: Reviews travel requests. Use when someone submits a travel request.
---

# Policy Reviewer Skill

When reviewing a travel request:
1. Check destination against restricted countries list
2. Verify trip cost is within department budget
3. Confirm travel dates don't conflict with blackout periods
4. Suggest alternatives if the request exceeds policy limits

La frontmatter (name y description) de YAML habilita la divulgación progresiva: el agente solo carga metadatos al inicio y, a continuación, activa las instrucciones completas de aptitud cuando se detecta una tarea coincidente.

El optimizador puede detectar y crear nuevas aptitudes durante la optimización. Estas habilidades se escriben en el directorio skills/ al aplicar un candidato optimizado.

Más información sobre el formato Agent Skills en agentskills.io.

Carga y uso de la configuración

Agregue el cargador de configuración en la parte superior del punto de entrada de su agente:

from azure.ai.agentserver.optimization import load_config

config = load_config()

La función load_config() lee de .agent_configs/ y devuelve un objeto OptimizationConfig. Cuando no hay ningún candidato de optimización activo, devuelve la configuración de línea base. Si no se encuentra ningún origen de configuración, devuelve None.

Parámetros:

Parámetro Description
config_dir Ruta de acceso del directorio de configuración personalizada (el valor predeterminado es .agent_configs/)

OptimizationConfig campos:

Campo Tipo Description
instructions str Indicación del sistema (optimizado o línea base)
model str Nombre de implementación del modelo
temperature float Temperatura de muestreo
skills list[Skill] Aptitudes detectadas (vacías si ninguna)
skills_dir str Ruta de acceso al directorio de aptitudes
tool_definitions list Definiciones de herramientas con descripciones optimizadas
source str Dónde procede la configuración (baseline, env, etc.)

Uso de los valores de configuración

Use el modelo y las instrucciones compuestas al llamar al modelo:

model = config.model or "gpt-4.1-mini"
instructions = config.compose_instructions()

El método compose_instructions() devuelve la indicación del sistema con las aptitudes detectadas añadidas como catálogo de aptitudes.

Aplicar descripciones de herramientas optimizadas

Si el agente usa herramientas (funciones), aplique descripciones optimizadas a ellas:

tools = [lookup_travel_policy, check_department_budget, get_flight_alternatives]
config.apply_tool_descriptions(tools)

El método apply_tool_descriptions() actualiza los metadatos de la función de cada herramienta con las descripciones mejoradas incluidas en la configuración de optimización. Esto mejora la precisión del modelo al decidir qué herramienta invocar.

Si las herramientas no son compatibles con apply_tool_descriptions(), lea las definiciones optimizadas de config.tool_definitions y aplíquelas a sus propios objetos de herramienta. Cada definición incluye tanto la descripción de la función optimizada como las descripciones de los parámetros, así que asígnalas en tus herramientas según la función y el nombre del parámetro.

Cargar habilidades desde un directorio

Si la configuración de optimización no incluye aptitudes, puede cargarlas desde un directorio local:

from azure.ai.agentserver.optimization import load_skills_from_dir
from pathlib import Path

if not config.skills and config.skills_dir:
    config.skills.extend(load_skills_from_dir(Path(config.skills_dir)))

Agregue una línea de registro para confirmar de dónde procede la configuración:

import logging

logger = logging.getLogger("my-agent")
logger.info(
    "Config source=%s | model=%s | prompt_len=%d | skills=%d",
    config.source, model, len(instructions), len(config.skills),
)

Ejemplo completo

En el ejemplo siguiente se muestra un agente de aprobación de viajes que usa la configuración de optimización para instrucciones, herramientas y aptitudes:

import json
import logging
import os
from pathlib import Path
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from pydantic import Field
from azure.ai.agentserver.optimization import load_config, load_skills_from_dir

logger = logging.getLogger(__name__)


@tool(approval_mode="never_require")
def lookup_travel_policy() -> str:
    """Look up the company travel policy rules and limits."""
    return json.dumps({
        "company": "Contoso Ltd.",
        "approval_thresholds": {
            "auto": 1500, "manager": 3000,
            "director": 7500, "vp": "above 7500"
        },
        "lodging_per_night": {"domestic": 250, "international": 400},
        "airfare": "economy only; business class if flight > 6 hours",
        "advance_booking_days": 14,
    })


@tool(approval_mode="never_require")
def check_department_budget() -> str:
    """Check the remaining travel budget for the employee's department."""
    return json.dumps({
        "department": "Engineering",
        "total_budget": 50000, "remaining": 14800,
    })


@tool(approval_mode="never_require")
def get_flight_alternatives(
    destination: Annotated[str, Field(description="The travel destination city")],
) -> str:
    """Find cheaper flight alternatives for the given destination."""
    return json.dumps({
        "alternatives": [
            {"option": "Flexible dates (+/-2 days)", "savings": "$200-800"},
            {"option": "Nearby alternate airport", "savings": "$100-400"},
        ],
    })


def main():
    # Load optimization config from .agent_configs/
    config = load_config()

    # Load skills from local directory if not provided by optimization
    if not config.skills and config.skills_dir:
        config.skills.extend(load_skills_from_dir(Path(config.skills_dir)))

    model = config.model or os.environ.get(
        "FOUNDRY_MODEL_NAME", "gpt-4.1-mini"
    )
    instructions = config.compose_instructions()

    # Apply optimized tool descriptions
    tools = [lookup_travel_policy, check_department_budget, get_flight_alternatives]
    config.apply_tool_descriptions(tools)

    logger.info(
        "Config source=%s | model=%s | prompt_len=%d | skills=%d",
        config.source, model, len(instructions), len(config.skills),
    )

    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=model,
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions=instructions,
        tools=tools,
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Cómo funciona

  1. Operación normal: no se establecen variables de entorno de optimización. El cargador de configuración lee .agent_configs/baseline/ y devuelve la configuración de línea base. El agente funciona con las instrucciones originales.

  2. Durante la optimización: el optimizador establece OPTIMIZATION_CONFIG con la configuración del candidato como JSON en línea. El agente usa las instrucciones y descripciones de herramientas del candidato durante la evaluación.

    Note

    Durante la evaluación, el optimizador invoca al agente en todas las tareas del conjunto de datos, por lo que las llamadas a herramientas externas se ejecutan de forma real. Para obtener instrucciones sobre cómo evitar efectos secundarios no deseados, consulte Funcionamiento del optimizador de agentes.

  3. Después de aplicar una opción ganadora: ejecuta azd ai agent optimize apply --candidate <id> para escribir los archivos de configuración optimizados en .agent_configs/<candidate_id>/ de tu proyecto. A continuación, azd deploy implementa el agente con la configuración mejorada. Para obtener los pasos completos de aplicación e implementación, consulte Implementación del ganador.

El código nunca cambia entre estos estados. La resolución de la configuración es totalmente automática.

Orden de resolución de la configuración

La load_config() función resuelve la configuración mediante una cadena de prioridad (la primera coincidencia gana):

Prioridad Source Variables de entorno Description
1 JSON insertado OPTIMIZATION_CONFIG Configuración completa como una cadena JSON
2 API del resolvedor OPTIMIZATION_CANDIDATE_ID, OPTIMIZATION_RESOLVE_ENDPOINT Captura la configuración candidata del servicio de optimización y la conserva en el directorio local.
3 Directorio local OPTIMIZATION_LOCAL_DIR (el valor predeterminado es .agent_configs/) Lee baseline/ o un directorio de candidatos específico
4 Sin configuración — Devuelve None

Verificar

Confirme que el paquete se puede importar y que la configuración se carga correctamente:

# Verify the package is importable
python -c "from azure.ai.agentserver.optimization import load_config; print('OK')"

# Run locally and check the log output
azd ai agent run
# Expected log: "Config source=baseline | model=gpt-4.1-mini | ..."

Contenido relacionado

  • Last updated on