Rendre votre agent prêt pour l’optimisation (préversion)

L’ajout de la prise en charge de l’optimiseur d’agent à votre agent nécessite quelques lignes de code. Aucune modification d’infrastructure ou logique conditionnelle n’est nécessaire. Vous installez le package d’optimisation, configurez un répertoire de configuration et appelez load_config() au démarrage.

Cette étape est la première étape du flux de travail d’optimisation. La configuration de base que vous créez définit les entrées que l’optimiseur améliore : instructions, outils, compétences et modèle. Votre agent fonctionne de la même façon si l’optimisation est active ou non.

Pour rendre votre agent prêt pour l’optimiseur, suivez ces trois étapes :

1. Installez le package d’optimisation.
2. Configurez un répertoire de configuration de référence avec vos instructions et, éventuellement, outils et compétences.
3. Chargez la configuration au démarrage avec load_config() et utilisez les valeurs qu’elle renvoie.

Le reste de cet article donne un exemple complet et explique comment fonctionne la résolution de configuration. Une fois l’exécution d’optimisation terminée, vous appliquez le candidat gagnant et déployez : consultez Déployer le gagnant.

Prerequisites

• Un projet Foundry avec un agent hébergé déployé
• Connaissance des agents hébergés
• Python 3.10 ou version ultérieure

Installer le package d’optimisation

Installez le package azure-ai-agentserver-optimization :

pip install azure-ai-agentserver-optimization

Configurer le répertoire de configuration

Créez le répertoire .agent_configs/baseline/ à la racine de votre projet. Ce répertoire définit la configuration de base de votre agent , le point de départ sur lequel l’optimiseur lit et s’améliore.

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 base de référence nécessite metadata.yaml et instructions.md. Le fichier tools.json et le répertoire skills/ sont facultatifs — incluez-les uniquement si votre agent utilise des outils ou des capacités. L’optimiseur active chaque cible en fonction de laquelle ces fichiers sont présents.

metadata.yaml

Le fichier de métadonnées indique au chargeur d’optimisation où rechercher des fichiers de configuration et quel modèle utiliser :

model: gpt-4.1-mini
instruction_file: instructions.md
tools_file: tools.json
skill_dir: skills

instructions.md

Le prompt système de votre agent. Écrivez-le sous forme de texte brut ou 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.

L’optimiseur améliore ce prompt lors des cycles d’optimisation. Une fois que vous avez appliqué un candidat optimisé, ce fichier contient la version améliorée.

tools.json

Déclarez les outils que votre agent peut appeler à l’aide du format d’appel de fonction 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"]
      }
    }
  }
]

L’optimiseur peut améliorer les descriptions des outils afin d’aider le modèle à invoquer les outils avec plus de précision. Après l’optimisation, vous appliquez des descriptions améliorées dans ce fichier.

skills/ (format Agent Skills)

Les compétences utilisent le format ouvert Agent Skills. Chaque compétence est un dossier contenant un SKILL.md fichier :

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

Un fichier SKILL.md contient un frontmatter YAML pour les métadonnées et un corps en Markdown pour les instructions :

---
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

Le frontmatter YAML (name et description) active la divulgation progressive : l’agent charge uniquement les métadonnées au démarrage, puis active les instructions complètes de compétence lorsqu’une tâche correspondante est détectée.

L’optimiseur peut découvrir et créer de nouvelles compétences pendant l’optimisation. Ces compétences sont enregistrées dans le répertoire skills/ quand vous appliquez un candidat optimisé.

En savoir plus sur le format Compétences de l’agent à agentskills.io.

Charger et utiliser la configuration

Ajoutez le chargeur de configuration en haut du point d’entrée de votre agent :

from azure.ai.agentserver.optimization import load_config

config = load_config()

La load_config() fonction lit .agent_configs/ et retourne un OptimizationConfig objet. Lorsqu’aucun candidat d’optimisation n’est actif, il retourne votre configuration de base de référence. Si aucune source de configuration n’est trouvée, elle retourne None.

Paramètres :

OptimizationConfig Champs:

Utiliser les valeurs de configuration

Utilisez le modèle et les instructions composées lors de l’appel du modèle :

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

La méthode compose_instructions() renvoie le prompt système auquel sont ajoutées les compétences détectées sous la forme d’un catalogue de compétences.

Appliquer des descriptions d’outils optimisées

Si votre agent utilise des outils (fonctions), appliquez des descriptions optimisées à celles-ci :

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

La apply_tool_descriptions() méthode corrige les métadonnées de chaque fonction outil avec les descriptions améliorées de la configuration d’optimisation. Cela améliore la précision du modèle lors du choix de l’outil à appeler.

Si vos outils ne sont pas compatibles avec apply_tool_descriptions(), lisez les définitions optimisées à partir de config.tool_definitions et appliquez-les à vos propres objets d’outil. Chaque définition inclut à la fois la description de la fonction optimisée et les descriptions des paramètres. Par conséquent, mappez les deux à vos outils par fonction et par nom de paramètre.

Charger des compétences à partir d’un répertoire

Si votre configuration d’optimisation n’inclut pas de compétences, vous pouvez les charger à partir d’un répertoire 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)))

Journaliser la source de configuration (recommandé)

Ajoutez une entrée de journal pour confirmer d’où provient la configuration :

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),
)

Exemple complet

L’exemple suivant montre un agent d’approbation de voyage qui utilise la configuration d’optimisation pour les instructions, les outils et les compétences :

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()

Fonctionnement

1. Opération normale : aucune variable d’environnement d’optimisation n’est définie. Le chargeur de configuration lit .agent_configs/baseline/ et retourne votre configuration de base. L’agent fonctionne avec vos instructions d’origine.

2. Lors de l’optimisation : l’optimiseur définit OPTIMIZATION_CONFIG avec la configuration du candidat en tant que JSON inline. Votre agent utilise les instructions et les descriptions des outils du candidat pendant l’évaluation.

   Note

   Lors de l’évaluation, l’optimiseur exécute votre agent pour chaque tâche de votre ensemble de données, de sorte que tous les appels à des outils externes sont réellement exécutés. Pour obtenir des conseils sur l’évitement des effets secondaires inattendus, consultez le fonctionnement de l’optimiseur d’agent.

3. Après avoir sélectionné une configuration gagnante : vous exécutez azd ai agent optimize apply --candidate <id> pour écrire les fichiers de configuration optimisés dans .agent_configs/<candidate_id>/ dans votre projet. Déploie ensuite azd deploy l’agent avec la configuration améliorée. Pour connaître les étapes complètes d’application et de déploiement, consultez Déployer le gagnant.

Votre code ne change jamais entre ces états. La résolution de configuration est entièrement automatique.

Ordre de résolution des configurations

La load_config() fonction résout la configuration selon un ordre de priorité (la première correspondance l’emporte) :

Vérifier

Vérifiez que le package est importable et que la configuration se charge correctement :

# 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 | ..."

Contenu connexe

• Vue d’ensemble de l’optimiseur d’agent
• Créer un jeu de données d’évaluation et des évaluateurs
• Optimiser les instructions de l’agent, les compétences, les outils et les modèles
• Démarrage rapide : Optimiser un agent hébergé
• Format des compétences de l’agent : open standard pour les compétences d’agent portables