Przygotuj agenta do optymalizacji (wersja zapoznawcza)

Dodanie obsługi optymalizatora agenta do agenta wymaga kilku wierszy kodu. Nie są potrzebne żadne zmiany struktury ani logika warunkowa. Instalujesz pakiet optymalizacyjny, tworzysz katalog konfiguracyjny i wywołujesz load_config() podczas uruchamiania.

Ten krok jest pierwszym krokiem w procesie optymalizacji. Utworzona konfiguracja punktu odniesienia definiuje dane wejściowe, które optymalizator ulepsza: instrukcje, narzędzia, umiejętności i model. Twój agent działa tak samo niezależnie od tego, czy optymalizacja jest aktywna, czy nie.

Aby przygotować agenta do optymalizacji, wykonaj trzy kroki:

1. Zainstaluj pakiet optymalizacji.
2. Skonfiguruj katalog konfiguracji bazowej z instrukcjami oraz opcjonalnie narzędziami i umiejętnościami.
3. Załaduj konfigurację podczas uruchamiania za pomocą load_config() polecenia i użyj zwracanych wartości.

W pozostałej części tego artykułu przedstawiono kompletny przykład i wyjaśniono, jak działa rozwiązanie konfiguracji. Po zakończeniu przebiegu optymalizacji zastosujesz zwycięskiego kandydata i wdrożysz — zobacz Wdrażanie zwycięzcy.

Wymagania wstępne

• Projekt Foundry z wdrożonym hostowanym agentem
• Znajomość hostowanych agentów
• Python 3.10 lub nowszy

Instalowanie pakietu optymalizacji

azure-ai-agentserver-optimization Zainstaluj pakiet:

pip install azure-ai-agentserver-optimization

Skonfiguruj katalog konfiguracji

Utwórz .agent_configs/baseline/ katalog w katalogu głównym projektu. Ten katalog definiuje podstawową konfigurację agenta — punkt wyjścia, który optymalizator odczytuje i następnie ulepsza.

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

Punkt odniesienia wymaga metadata.yaml i instructions.md. Plik tools.json i skills/ katalog są opcjonalne — dołącz je tylko wtedy, gdy agent korzysta z narzędzi lub umiejętności. Optymalizator aktywuje każdy element docelowy na podstawie tego, które z tych plików są obecne.

metadata.yaml

Plik metadanych informuje moduł ładujący optymalizatora, gdzie znaleźć pliki konfiguracyjne i którego modelu użyć:

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

instructions.md

Prompt systemowy agenta. Zapisz go jako zwykły tekst lub znacznik 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.

Optymalizator ulepsza to polecenie podczas procesów optymalizacji. Po zastosowaniu zoptymalizowanego wariantu ten plik zawiera ulepszoną wersję.

tools.json

Zadeklaruj narzędzia, które agent może wywołać przy użyciu formatu wywoływania funkcji 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"]
      }
    }
  }
]

Optymalizator może ulepszyć opisy narzędzi, aby ułatwić dokładniejsze wywoływanie narzędzi modelu. Po optymalizacji zastosujesz ulepszone opisy z powrotem do tego pliku.

skills/ (Format umiejętności agenta)

Umiejętności wykorzystują otwarty format Agent Skills. Każda umiejętność to folder zawierający SKILL.md plik:

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

Plik SKILL.md zawiera blok metadanych YAML oraz treść w formacie Markdown zawierającą instrukcje:

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

Frontmatter YAML (name i description) umożliwia stopniowe ujawnienie — agent ładuje tylko metadane podczas uruchamiania, a następnie aktywuje pełne instrukcje dotyczące umiejętności po wykryciu pasującego zadania.

Optymalizator może odnajdywać i tworzyć nowe umiejętności podczas optymalizacji. Te umiejętności są zapisywane w katalogu skills/ po zastosowaniu zoptymalizowanego kandydata.

Dowiedz się więcej o formacie umiejętności agenta na agentskills.io.

Załaduj i użyj konfiguracji

Dodaj moduł ładujący konfigurację na początku punktu wejścia agenta:

from azure.ai.agentserver.optimization import load_config

config = load_config()

Funkcja load_config() odczytuje z .agent_configs/ i zwraca obiekt OptimizationConfig. Jeśli żaden kandydat do optymalizacji nie jest aktywny, zwraca konfigurację bazową. Jeśli nie znaleziono źródła konfiguracji, zwraca wartość None.

Parametry:

OptimizationConfig Pola:

Użyj wartości konfiguracji

Użyj modelu i złożonych instrukcji podczas wywoływania modelu:

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

Metoda compose_instructions() zwraca monit systemowy z wszelkimi odnalezionymi umiejętnościami dołączonymi jako wykaz umiejętności.

Stosowanie zoptymalizowanych opisów narzędzi

Jeśli agent używa narzędzi (funkcji), zastosuj do nich zoptymalizowane opisy:

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

Metoda apply_tool_descriptions() uzupełnia metadane każdej funkcji narzędziowej o ulepszone opisy z konfiguracji optymalizacji. Zwiększa to dokładność modelu przy podejmowaniu decyzji o wyborze narzędzia do wywołania.

Jeśli Twoje narzędzia nie są zgodne z apply_tool_descriptions(), odczytaj zoptymalizowane definicje z config.tool_definitions i zastosuj je do własnych obiektów narzędziowych. Każda definicja zawiera zarówno zoptymalizowany opis funkcji, jak i opisy parametrów, więc odwzoruj oba te elementy w swoich narzędziach na podstawie nazwy funkcji i nazwy parametru.

Załaduj umiejętności z katalogu

Jeśli konfiguracja optymalizacji nie obejmuje umiejętności, możesz załadować je z katalogu lokalnego:

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

Rejestrowanie źródła konfiguracji (zalecane)

Dodaj wiersz dziennika, aby potwierdzić, skąd pochodzi konfiguracja:

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

Kompletny przykład

Poniższy przykład przedstawia agenta do zatwierdzania podróży, który wykorzystuje konfigurację optymalizacji dla instrukcji, narzędzi i umiejętności:

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

Jak to działa

1. Normalna operacja: nie ustawiono zmiennych środowiskowych optymalizacji. Moduł ładujący konfigurację odczytuje .agent_configs/baseline/ i zwraca konfigurację bazową. Agent działa na podstawie oryginalnych instrukcji.

2. Podczas optymalizacji: optymalizator ustawia OPTIMIZATION_CONFIG na konfigurację kandydata w formacie inline JSON. Agent używa instrukcji i opisów narzędzi kandydata podczas oceny.

   Note

   Podczas oceny optymalizator uruchamia agenta dla każdego zadania w zbiorze danych, więc wszelkie wywołania narzędzi zewnętrznych są faktycznie wykonywane. Aby uzyskać wskazówki dotyczące unikania niezamierzonych skutków ubocznych, zobacz Jak działa optymalizator agenta.

3. Po wybraniu zwycięzcy: uruchom azd ai agent optimize apply --candidate <id>, aby zapisać zoptymalizowane pliki konfiguracji do .agent_configs/<candidate_id>/ w projekcie. Następnie azd deploy wdraża agenta z ulepszoną konfiguracją. Aby uzyskać pełny opis czynności związanych z zastosowaniem i wdrożeniem, zobacz Wdróż zwycięski wariant.

Twój kod nigdy nie zmienia się między tymi stanami. Rozwiązywanie konfiguracji odbywa się w pełni automatycznie.

Kolejność rozstrzygania konfiguracji

Funkcja load_config() rozwiązuje konfigurację przy użyciu łańcucha priorytetów (pierwsze dopasowanie wygrywa):

Zweryfikować

Upewnij się, że pakiet można zaimportować, a konfiguracja jest ładowana poprawnie:

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

Treści powiązane

• Omówienie optymalizatora agentów
• Tworzenie zestawu danych oceny i ewaluatorów
• Optymalizowanie instrukcji agenta, umiejętności, narzędzi i modeli
• Szybki start: optymalizowanie hostowanego agenta
• Format umiejętności agenta — otwarty standard dla umiejętności agenta przenośnego