Maak je agent klaar voor optimalisatie (preview)

Voor het toevoegen van ondersteuning voor de agentoptimalisatie aan uw agent zijn enkele regels code vereist. Er zijn geen frameworkwijzigingen of voorwaardelijke logica nodig. U installeert het optimalisatiepakket, maakt een configuratiemap aan en roept load_config() bij het opstarten aan.

Deze stap is de eerste stap in de optimalisatiewerkstroom. De basislijnconfiguratie die u maakt definieert de invoer die de optimizer verbetert: instructies, hulpprogramma's, vaardigheden en het model. Uw agent werkt hetzelfde, ongeacht of optimalisatie al dan niet actief is.

Voer drie stappen uit om uw agent optimalisatieklaar te maken:

1. Installeer het optimalisatiepakket.
2. Stel een basislijnconfiguratiemap in met uw instructies en eventueel hulpprogramma's en vaardigheden.
3. Laad de configuratie bij het opstarten met load_config() en gebruik de waarden die worden geretourneerd.

De rest van dit artikel bevat een volledig voorbeeld en legt uit hoe configuratieomzetting werkt. Nadat een optimalisatieuitvoering is voltooid, past u de winnende kandidaat toe en implementeert u deze. Zie De winnaar implementeren.

Prerequisites

• Een Foundry-project met een geïmplementeerde gehoste agent
• Bekendheid met gehoste agents
• Python 3.10 of hoger

Het optimalisatiepakket installeren

Installeer het azure-ai-agentserver-optimization-pakket:

pip install azure-ai-agentserver-optimization

De configuratiemap instellen

Maak de map .agent_configs/baseline/ aan in de hoofdmap van uw project. Deze directory definieert de basislijnconfiguratie van uw agent: het beginpunt waarop de optimizer leest en verbetert.

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

De basislijn vereist metadata.yaml en instructions.md. Het tools.json bestand en de skills/ map zijn optioneel - neem ze alleen op als uw agent tools of vaardigheden gebruikt. De optimizer activeert elk doel op basis van welke van deze bestanden aanwezig is.

metadata.yaml

Het metagegevensbestand vertelt het optimalisatielaadprogramma waar configuratiebestanden moeten worden gevonden en welk model moet worden gebruikt:

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

instructions.md

De systeemprompt van uw agent. Schrijf deze als tekst zonder opmaak of 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.

De optimizer verbetert deze prompt tijdens optimalisatieuitvoeringen. Nadat u een geoptimaliseerde kandidaat hebt toegepast, bevat dit bestand de verbeterde versie.

tools.json

Declareer de hulpprogramma's die uw agent kan aanroepen met behulp van de openAI-functieoproepindeling:

[
  {
    "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"]
      }
    }
  }
]

De optimizer kan toolbeschrijvingen verbeteren zodat het model tools nauwkeuriger kan aanroepen. Na optimalisatie past u verbeterde beschrijvingen weer toe in dit bestand.

vaardigheden/ (indeling van agentvaardigheden)

Vaardigheden gebruiken de open indeling Agent Skills. Elke vaardigheid is een map met een SKILL.md bestand:

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

Een SKILL.md bestand heeft YAML-frontmatter voor metagegevens en markdown-hoofdtekst voor instructies:

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

De YAML-frontmatter (name en description) maakt progressieve openbaarmaking mogelijk: de agent laadt alleen metagegevens bij het opstarten en activeert vervolgens de volledige vaardigheidsinstructies wanneer een overeenkomende taak wordt gedetecteerd.

De optimizer kan tijdens optimalisatie nieuwe vaardigheden ontdekken en maken. Deze vaardigheden worden naar de skills/ directory geschreven wanneer u een geoptimaliseerde kandidaat toepast.

Meer informatie over de Agent Skills-indeling vindt u op agentskills.io.

De configuratie laden en gebruiken

Voeg het configuratielaadprogramma toe boven aan het ingangspunt van uw agent:

from azure.ai.agentserver.optimization import load_config

config = load_config()

De load_config() functie leest van .agent_configs/ en retourneert een OptimizationConfig object. Wanneer er geen optimalisatiekandidaat actief is, wordt uw basislijnconfiguratie geretourneerd. Als er geen configuratiebron wordt gevonden, wordt deze geretourneerd None.

Parameters:

OptimizationConfig Velden:

De configuratiewaarden gebruiken

Gebruik het model en samengestelde instructies bij het aanroepen van het model:

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

De compose_instructions() methode retourneert de systeemprompt met alle gedetecteerde vaardigheden die zijn toegevoegd als een vaardigheidscatalogus.

Geoptimaliseerde toolbeschrijvingen toepassen

Als uw agent hulpprogramma's (functies) gebruikt, past u erop geoptimaliseerde beschrijvingen toe:

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

Met apply_tool_descriptions() de methode worden de metagegevens van elke hulpprogrammafunctie gepatcht met de verbeterde beschrijvingen van de optimalisatieconfiguratie. Dit verbetert de nauwkeurigheid van het model bij het bepalen welk hulpprogramma moet worden aangeroepen.

Als uw hulpprogramma's niet compatibel zijn met apply_tool_descriptions(), leest u de geoptimaliseerde definities uit config.tool_definitions en past u deze toe op uw eigen hulpprogrammaobjecten. Elke definitie bevat zowel de beschrijving van de geoptimaliseerde functie als de parameterbeschrijvingen, dus wijs beide toe aan uw hulpprogramma's op functie en parameternaam.

Vaardigheden laden vanuit een map

Als uw optimalisatieconfiguratie geen vaardigheden bevat, kunt u deze laden vanuit een lokale map:

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

De configuratiebron registreren (aanbevolen)

Voeg een logboekregel toe om te bevestigen waar de configuratie vandaan komt:

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

Volledig voorbeeld

In het volgende voorbeeld ziet u een reisgoedkeuringsagent die gebruikmaakt van de optimalisatieconfiguratie voor instructies, hulpprogramma's en vaardigheden:

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

Hoe werkt het?

1. Normale werking: er worden geen omgevingsvariabelen voor optimalisatie ingesteld. Het configuratielaadprogramma leest .agent_configs/baseline/ en retourneert de basislijnconfiguratie. De agent werkt met uw oorspronkelijke instructies.

2. Tijdens de optimalisatie: de optimizer stelt OPTIMIZATION_CONFIG in met de configuratie van de kandidaat als inline JSON. Uw agent gebruikt de instructies en beschrijvingen van de hulpprogramma's van de kandidaat tijdens de evaluatie.

   Note

   Tijdens de evaluatie roept de optimizer uw agent aan voor iedere taak in uw dataset, zodat alle aanroepen naar externe tools daadwerkelijk worden uitgevoerd. Zie Hoe de optimalisatie van de agent werkt voor hulp bij het voorkomen van onbedoelde bijwerkingen.

3. Na het toepassen van een winnaar: U voert azd ai agent optimize apply --candidate <id> uit om de geoptimaliseerde configuratiebestanden weg te schrijven naar .agent_configs/<candidate_id>/ in uw project. Vervolgens implementeert azd deploy de agent met de verbeterde configuratie. Zie De winnaar implementeren voor de volledige stappen voor toepassen en implementeren.

Uw code verandert nooit tussen deze statussen. De configuratieomzetting is volledig automatisch.

Volgorde van configuratiebepaling

De load_config() functie lost de configuratie op met behulp van een prioriteitsketen (eerste overeenkomst wint):

Verifiëren

Controleer of het pakket kan worden geïmporteerd en de configuratie correct wordt geladen:

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

Verwante inhoud

• Overzicht van de agent-optimalisator
• Een evaluatiedataset en evaluatoren maken
• Agentinstructies, vaardigheden, hulpprogramma's en modellen optimaliseren
• Quickstart: Een gehoste agent optimaliseren
• Indeling van agentvaardigheden - open standaard voor draagbare agentvaardigheden