Prepara il tuo agente per l'ottimizzatore (anteprima)

Importante

Agent Optimizer è attualmente in anteprima limitata ed è disponibile solo tramite un processo di iscrizione. Per accedere al servizio, completare il modulo di assunzione. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Aggiungere il supporto per l'ottimizzatore dell'agente al tuo agente richiede solo poche righe di codice. Non sono necessarie modifiche al framework o logica condizionale. Installare il pacchetto di ottimizzazione, configurare una directory di configurazione e chiamare load_config() all'avvio.

Prerequisiti

Installare il pacchetto di ottimizzazione

Installare il pacchetto azure-ai-agentserver-optimization:

pip install azure-ai-agentserver-optimization

Configura la directory di configurazione

Creare la .agent_configs/baseline/ directory nella radice del progetto. Questa directory definisce la configurazione di base dell'agente, ovvero il punto iniziale su cui l'ottimizzatore legge e migliora.

my-agent/
├── main.py
├── agent.yaml
├── 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/)

metadata.yaml

Il file di metadati indica al caricatore di ottimizzazione dove trovare i file di configurazione e il modello da usare:

model: gpt-4.1-mini
instruction_file: instructions.md
tools_file: tools.json
skill_dir: skills
Campo Obbligatorio Description
model Sì Nome della distribuzione del modello (ad esempio, gpt-4.1-mini, gpt-5.1)
instruction_file Sì Percorso relativo al file del prompt di sistema
tools_file No Percorso relativo del file JSON delle definizioni degli strumenti
skill_dir No Percorso relativo alla directory delle competenze
temperature No Temperatura del modello per la generazione

instructions.md

Il prompt di sistema del tuo agente. Scrivilo come testo semplice 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.

L'ottimizzatore migliora questo prompt durante i cicli di ottimizzazione. Dopo aver applicato un candidato ottimizzato, questo file contiene la versione migliorata.

tools.json

Dichiarare gli strumenti che l'agente può chiamare usando il formato di chiamata alle funzioni 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’ottimizzatore può migliorare le descrizioni degli strumenti per aiutare il modello a invocarli con maggiore precisione. Dopo l'ottimizzazione, applichi nuovamente le descrizioni migliorate in questo file.

competenze/ (formato delle competenze dell'agente)

Le skill utilizzano il formato aperto Agent Skills. Ogni abilità è una cartella che contiene un file SKILL.md:

skills/
└── policy-reviewer/
    └── SKILL.md

Un file SKILL.md contiene un'intestazione YAML per i metadati e un corpo Markdown per le istruzioni:

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

Il frontmatter YAML (name e description) abilita la divulgazione progressiva: l'agente carica solo i metadati all'avvio, quindi attiva le istruzioni complete della competenza quando viene rilevata un'attività corrispondente.

L'ottimizzatore può individuare e creare nuove competenze durante l'ottimizzazione. Queste competenze vengono scritte nella skills/ directory quando si applica un candidato ottimizzato.

Per altre informazioni sul formato delle competenze dell'agente, vedere agentskills.io.

Caricare la configurazione di ottimizzazione

Aggiungi il loader di configurazione all'inizio del punto di ingresso dell'agente:

from azure.ai.agentserver.optimization import load_config

config = load_config()

La load_config() funzione legge da .agent_configs/ e restituisce un OptimizationConfig oggetto . Quando non è attivo alcun candidato per l'ottimizzazione, restituisce la configurazione di base.

Parametri:

Parametro Description
config_dir Percorso della directory di configurazione personalizzata (predefinito: .agent_configs/)
required Se False, restituisce None anziché sollevare un'eccezione quando non viene trovata alcuna configurazione (impostazione predefinita: True)

OptimizationConfig Campi:

Campo Type Description
instructions str Richiesta di sistema (ottimizzata o baseline)
model str Nome della distribuzione del modello
temperature float Temperatura di campionamento
skills list[Skill] Competenze individuate (vuote se non presenti)
skills_dir str Percorso della directory delle competenze
tool_definitions list Definizioni degli strumenti con descrizioni ottimizzate
source str Da dove proviene la configurazione (baseline, enve così via)

Usare i valori di configurazione

Usa il modello e le istruzioni composte quando chiami il modello:

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

Il metodo compose_instructions() restituisce il prompt di sistema con le eventuali competenze individuate aggiunte sotto forma di catalogo delle competenze.

Applicare descrizioni degli strumenti ottimizzate

Se l'agente usa strumenti (funzioni), applicare descrizioni ottimizzate a tali strumenti:

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

Il metodo apply_tool_descriptions() aggiorna i metadati di ogni funzione dello strumento con le descrizioni migliorate della configurazione di ottimizzazione. Questo migliora l'accuratezza del modello quando deve decidere quale strumento chiamare.

Caricare le competenze da una directory

Se la configurazione di ottimizzazione non include competenze, è possibile caricarle da una directory locale:

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

Aggiungere una riga di log per confermare la provenienza della configurazione:

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

Applicare la configurazione ottimizzata in locale

Dopo aver eseguito azd ai agent optimize e selezionato un candidato vincente, applicarlo al progetto locale prima di distribuirlo:

# 1. Run optimization
azd ai agent optimize

# 2. Review results
azd ai agent optimize status <job-id>

# 3. Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate_id>

# 4. Deploy with the optimized config
azd deploy

Il comando apply scarica le versioni ottimizzate instructions.md, tools.json e skills/ dalla build candidata e le scrive in .agent_configs/<candidate_id>/ nel progetto. All'avvio successivo rileva load_config() il candidato e usa la configurazione ottimizzata.

Avvertimento

Se si usa azd ai agent optimize deploy --candidate <id> invece di apply, la configurazione ottimizzata viene distribuita direttamente tramite l'API senza aggiornare i file locali. Usare il workflow apply → deploy in produzione per mantenere la riproducibilità.

Esempio completo

L'esempio seguente mostra un agente di approvazione viaggi che usa la configurazione di ottimizzazione per istruzioni, strumenti e competenze:

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

Come funziona

  1. Operazione normale: non vengono impostate variabili di ambiente di ottimizzazione. Il loader di configurazione legge .agent_configs/baseline/ e restituisce la configurazione di riferimento. L'agente lavora con le istruzioni originali.

  2. Durante l'ottimizzazione: l'ottimizzatore imposta OPTIMIZATION_CONFIG con la configurazione del candidato come JSON in linea. L'agente usa le istruzioni e le descrizioni degli strumenti del candidato durante la valutazione.

    Avvertimento

    Durante la valutazione, l'optimizer invoca il tuo agente per ogni attività nel tuo set di dati. Se l'agente chiama strumenti esterni (API, database, servizi di terze parti), tali chiamate vengono eseguite per il reale. Valutare la possibilità di simulare le implementazioni degli strumenti o puntare agli endpoint di test per evitare effetti collaterali imprevisti.

  3. Dopo aver selezionato un vincitore: esegui azd ai agent optimize apply --candidate <id> per scrivere i file di configurazione ottimizzati in .agent_configs/<candidate_id>/ nel progetto. Quindi azd deploy distribuisce l'agente con la configurazione ottimizzata.

Il codice non cambia mai tra questi stati. La risoluzione della configurazione è completamente automatica.

Ordine di risoluzione della configurazione

La load_config() funzione risolve la configurazione usando una catena di priorità (la prima corrispondenza vince):

Priorità origine Variabili di ambiente Description
1 Inline JSON OPTIMIZATION_CONFIG Configurazione completa come stringa JSON
2 Directory locale OPTIMIZATION_LOCAL_DIR (il valore predefinito è .agent_configs/) Legge baseline/ o una directory candidata specifica
3 Nessuna configurazione — Genera ValueError (o restituisce None se required=False)

Verificare

Verificare che il pacchetto sia importabile e che la configurazione venga caricata correttamente:

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

Contenuti correlati

  • Last updated on