Prepara il tuo agente per l'ottimizzazione (anteprima)

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.

Questo passaggio è il primo passaggio del flusso di lavoro di ottimizzazione. La configurazione di base creata definisce gli input che l'ottimizzatore migliora: istruzioni, strumenti, competenze e modello. L'agente funziona allo stesso modo se l'ottimizzazione è attiva o meno.

Per rendere il tuo agente pronto per l'ottimizzazione, completa tre passaggi:

1. Installare il pacchetto di ottimizzazione.
2. Configurare una directory di configurazione di base con le istruzioni e, facoltativamente, strumenti e competenze.
3. Caricare la configurazione all'avvio con load_config() e usare i valori restituiti.

Nel resto di questo articolo viene fornito un esempio completo e viene spiegato come funziona la risoluzione della configurazione. Al termine di un'esecuzione di ottimizzazione, si applica il candidato vincitore e si distribuisce; vedere Distribuire il vincitore.

Prerequisiti

• Un progetto Foundry con un agente ospitato già implementato
• Familiarità con gli agenti ospitati
• Python 3.10 o versione successiva

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
|- 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 baseline richiede metadata.yaml e instructions.md. Il file tools.json e la directory skills/ sono facoltativi: includili solo se l'agente utilizza strumenti o abilità. L'utilità di ottimizzazione attiva ogni destinazione in base alla quale sono presenti questi file.

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

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 e usare la configurazione

Aggiungi il caricatore di configurazione all'inizio del punto di ingresso del tuo 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. Se non viene trovata alcuna origine di configurazione, restituisce None.

Parametri:

OptimizationConfig Campi:

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.

Se gli strumenti non sono compatibili con apply_tool_descriptions(), leggere le definizioni ottimizzate da config.tool_definitions e applicarle ai propri oggetti strumento. Ogni definizione include sia la descrizione della funzione ottimizzata sia le descrizioni dei parametri, quindi associa entrambe ai tuoi strumenti in base al nome della funzione e del parametro.

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

Registrare l'origine di configurazione (scelta consigliata)

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

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

Come funziona

1. Operazione normale: non vengono impostate variabili di ambiente di ottimizzazione. Il caricatore di configurazione legge .agent_configs/baseline/ e restituisce la configurazione di base. L'agente opera in base alle vostre istruzioni iniziali.

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.

   Note

   Durante la valutazione, l'ottimizzatore richiama il tuo agente per ogni attività del tuo set di dati, quindi tutte le chiamate a strumenti esterni vengono eseguite realmente. Per informazioni su come evitare effetti collaterali involontari, consulta Come funziona l'ottimizzatore dell'agente.

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. Per la procedura completa di applicazione e distribuzione, vedere Distribuire il vincitore.

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

Ordine di risoluzione della configurazione

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

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

• Panoramica di Agent Optimizer
• Creare un set di dati di valutazione e analizzatori
• Ottimizzare le istruzioni, le competenze, gli strumenti e i modelli dell'agente
• Guida introduttiva: Ottimizzare un agente ospitato
• Formato delle competenze dell'agente : standard aperto per le competenze dell'agente portatile