Gör din agent optimeringsklar (förhandsversion)

För att lägga till stöd för agentoptimeraren till din agent krävs några rader kod. Inga ramverksändringar eller villkorsstyrd logik behövs. Du installerar optimeringspaketet, konfigurerar en konfigurationskatalog och anropar load_config() vid start.

Det här steget är det första steget i optimeringsarbetsflödet. Baslinjekonfigurationen som du skapar definierar indata som optimeraren förbättrar: instruktioner, verktyg, färdigheter och modellen. Din agent fungerar på samma sätt oavsett om optimeringen är aktiv eller inte.

Gör din agent redo för optimeraren i tre steg:

1. Installera optimeringspaketet.
2. Konfigurera en baslinjekonfigurationskatalog med dina instruktioner och, om du vill, verktyg och färdigheter.
3. Läs in konfigurationen vid start med load_config() och använd de värden som returneras.

Resten av den här artikeln ger ett komplett exempel och förklarar hur konfigurationslösningen fungerar. När en optimeringskörning har slutförts tillämpar du den vinnande kandidaten och distribuerar – se Distribuera vinnaren.

Förutsättningar

• Ett Foundry-projekt med en distribuerad värdbaserad agent
• Kännedom om värdagenter
• Python 3.10 eller senare

Installera optimeringspaketet

Installera azure-ai-agentserver-optimization-paketet:

pip install azure-ai-agentserver-optimization

Konfigurera konfigurationskatalogen

Skapa katalogen .agent_configs/baseline/ i projektroten. Den här katalogen definierar agentens baslinjekonfiguration – startpunkten som optimeraren läser och förbättrar.

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

Baslinjen kräver metadata.yaml och instructions.md. Filen tools.json och skills/ katalogen är valfria – inkludera dem endast om din agent använder verktyg eller färdigheter. Optimeraren aktiverar varje mål baserat på vilka av dessa filer som finns.

metadata.yaml

Metadatafilen talar om för optimeringsinläsaren var konfigurationsfilerna ska hittas och vilken modell som ska användas:

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

instructions.md

Systemprompten för din agent. Skriv den som oformaterad text eller 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.

Optimeraren förbättrar den här uppmaningen under optimeringskörningar. När du har tillämpat en optimerad kandidat innehåller den här filen den förbättrade versionen.

tools.json

Deklarera de verktyg som agenten kan anropa med hjälp av openAI-funktionsanropsformatet:

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

Optimeraren kan förbättra verktygsbeskrivningarna för att hjälpa modellen att anropa verktyg mer exakt. Efter optimeringen använder du förbättrade beskrivningar i den här filen igen.

skills/ (Agent Skills-format)

Kunskaper använder det öppna agentkunskapsformatet . Varje färdighet är en mapp som innehåller en SKILL.md fil:

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

En SKILL.md fil har YAML-frontmatter för metadata och markdown-brödtext för instruktioner:

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

YAML-frontmattern (name och description) möjliggör progressivt avslöjande – agenten läser bara in metadata vid start och aktiverar sedan de fullständiga kunskapsinstruktionerna när en matchande uppgift identifieras.

Optimeraren kan identifiera och skapa nya kunskaper under optimeringen. Dessa kunskaper skrivs till katalogen skills/ när du använder en optimerad kandidat.

Läs mer om agentkunskapsformatet på agentskills.io.

Läs in och använd konfigurationen

Lägg till konfigurationsinläsaren överst på agentens startpunkt:

from azure.ai.agentserver.optimization import load_config

config = load_config()

Funktionen load_config() läser från .agent_configs/ och returnerar ett OptimizationConfig objekt. När ingen optimeringskandidat är aktiv returneras baslinjekonfigurationen. Om ingen konfigurationskälla hittas returneras None.

Parameters:

OptimizationConfig Fält:

Använda konfigurationsvärdena

Använd modellen och sammansatta instruktioner när du anropar modellen:

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

Metoden compose_instructions() returnerar systemprompten med alla identifierade färdigheter som läggs till som en kunskapskatalog.

Använda optimerade verktygsbeskrivningar

Om din agent använder verktyg (funktioner) använder du optimerade beskrivningar för dem:

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

Metoden apply_tool_descriptions() korrigerar varje verktygsfunktions metadata med de förbättrade beskrivningarna från optimeringskonfigurationen. Detta förbättrar modellens noggrannhet när du bestämmer vilket verktyg som ska anropas.

Om dina verktyg inte är kompatibla med apply_tool_descriptions()läser du de optimerade definitionerna från config.tool_definitions och tillämpar dem på dina egna verktygsobjekt. Varje definition innehåller både den optimerade funktionsbeskrivningen och parameterbeskrivningarna, så mappa både till dina verktyg efter funktions- och parameternamn.

Läs in kunskaper från en katalog

Om din optimeringskonfiguration inte innehåller kunskaper kan du läsa in dem från en lokal katalog:

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

Logga konfigurationskällan (rekommenderas)

Lägg till en loggrad för att bekräfta var konfigurationen kom ifrå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),
)

Fullständigt exempel

I följande exempel visas en agent för resegodkännande som använder optimeringskonfigurationen för instruktioner, verktyg och färdigheter:

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

Så här fungerar det

1. Normal åtgärd: Inga miljövariabler för optimering har angetts. Konfigurationsinläsaren läser .agent_configs/baseline/ och returnerar baslinjekonfigurationen. Agenten fungerar med dina ursprungliga instruktioner.

2. Under optimeringen: Optimeraren ställer in OPTIMIZATION_CONFIG med kandidatens konfiguration som infogad JSON. Din agent använder kandidatens instruktioner och verktygsbeskrivningar under utvärderingen.

   Note

   Under utvärderingen anropar optimeringsverktyget din agent mot varje uppgift i datauppsättningen, så alla externa verktygsanrop körs på riktigt. Vägledning om hur du undviker oavsiktliga biverkningar finns i Så här fungerar agentoptimeraren.

3. När du har använt en vinnare: Du kör azd ai agent optimize apply --candidate <id> för att skriva de optimerade konfigurationsfilerna till .agent_configs/<candidate_id>/ i projektet. Distribuerar sedan azd deploy agenten med den förbättrade konfigurationen. De fullständiga stegen för att tillämpa och distribuera finns i Distribuera vinnaren.

Koden ändras aldrig mellan dessa tillstånd. Konfigurationslösningen är helt automatisk.

Ordning för konfigurationsupplösning

Funktionen load_config() löser konfigurationen med hjälp av en prioritetskedja (första matchningen vinner):

Kontrollera

Kontrollera att paketet kan importeras och att konfigurationen läses in korrekt:

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

Relaterat innehåll

• Översikt över agentoptimerare
• Skapa en utvärderingsdatauppsättning och utvärderare
• Optimera agentinstruktioner, färdigheter, verktyg och modeller
• Snabbstart: Optimera en värdbaserad agent
• Agent skills format – öppen standard för bärbara agentkunskaper