Machen Sie Ihren Agenten für den Optimierer bereit (Vorschau)

Das Hinzufügen der Unterstützung für den Agent-Optimierer zu Ihrem Agent erfordert einige Codezeilen. Es sind keine Frameworkänderungen oder bedingte Logik erforderlich. Sie installieren das Optimierungspaket, richten ein Konfigurationsverzeichnis ein und rufen beim Start auf load_config() .

Dieser Schritt ist der erste Schritt im Optimierungsworkflow. Die von Ihnen erstellte Basiskonfiguration definiert die Eingaben, die der Optimierer verbessert: Anweisungen, Tools, Fähigkeiten und das Modell. Ihr Agent funktioniert gleich, ob die Optimierung aktiv ist oder nicht.

Führen Sie drei Schritte aus, um Ihren Agenten für die Optimierung fit zu machen:

1. Installieren Sie das Optimierungspaket.
2. Richten Sie ein Basiskonfigurationsverzeichnis mit Ihren Anweisungen und optional Tools und Fähigkeiten ein.
3. Laden Sie die Konfiguration beim Start mit load_config() und verwenden Sie die zurückgegebenen Werte.

Der Rest dieses Artikels enthält ein vollständiges Beispiel und erläutert die Funktionsweise der Konfigurationsauflösung. Nach Abschluss eines Optimierungslaufs wenden Sie den Gewinnerkandidaten an und stellen ihn bereit – siehe Bereitstellen des Gewinners.

Voraussetzungen

• Ein Foundry-Projekt mit einem bereitgestellten gehosteten Agent
• Vertrautheit mit gehosteten Agents
• Python 3.10 oder höher

Installieren des Optimierungspakets

Installieren Sie das Paket azure-ai-agentserver-optimization:

pip install azure-ai-agentserver-optimization

Einrichten des Konfigurationsverzeichnisses

Erstellen Sie das .agent_configs/baseline/ Verzeichnis im Projektstamm. Dieses Verzeichnis definiert die Basiskonfiguration Ihres Agents – den Ausgangspunkt, den der Optimierer liest und verbessert.

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

Die Baseline erfordert metadata.yaml und instructions.md. Die tools.json Datei und skills/ das Verzeichnis sind optional – fügen Sie sie nur hinzu, wenn Ihr Agent Tools oder Fähigkeiten verwendet. Der Optimierer aktiviert jedes Ziel basierend darauf, welche dieser Dateien vorhanden sind.

metadata.yaml

Die Metadatendatei teilt dem Optimierungsladeprogramm mit, wo Konfigurationsdateien gesucht werden sollen und welches Modell verwendet werden soll:

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

instructions.md

Systemaufforderung Ihres Agenten. Schreiben Sie es als Plain Text oder 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.

Der Optimierer verbessert diese Aufforderung während der Optimierungsläufe. Nachdem Sie einen optimierten Kandidaten angewendet haben, enthält diese Datei die verbesserte Version.

tools.json

Deklarieren Sie die Tools, die Ihr Agent mit dem OpenAI-Funktionsaufrufformat aufrufen kann:

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

Der Optimierer kann Toolbeschreibungen verbessern, damit das Modell Tools präziser aufrufen kann. Nach der Optimierung wenden Sie verbesserte Beschreibungen wieder auf diese Datei an.

skills/ (Format für Agentenfähigkeiten)

Fähigkeiten verwenden das offene Agent Skills-Format . Jede Fähigkeit ist ein Ordner mit einer SKILL.md Datei:

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

Eine SKILL.md Datei enthält YAML-Frontmatter für Metadaten und Markdowntext für Anweisungen:

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

Der YAML-Frontmatter (name und description) ermöglicht eine progressive Offenlegung – der Agent lädt nur Metadaten beim Start und aktiviert dann die vollständigen Qualifikationsanweisungen, wenn eine übereinstimmende Aufgabe erkannt wird.

Der Optimierer kann während der Optimierung neue Fähigkeiten entdecken und erstellen. Diese Fähigkeiten werden im Verzeichnis skills/ gespeichert, wenn Sie einen optimierten Kandidaten anwenden.

Weitere Informationen zum Format "Agent Skills" finden Sie unter agentskills.io.

Konfiguration laden und verwenden

Fügen Sie den Konfigurationslader am Anfang des Einstiegspunkts Ihres Agents hinzu:

from azure.ai.agentserver.optimization import load_config

config = load_config()

Die load_config() Funktion liest aus .agent_configs/ und gibt ein OptimizationConfig Objekt zurück. Wenn kein Optimierungskandidat aktiv ist, wird ihre Basisplankonfiguration zurückgegeben. Wenn keine Konfigurationsquelle gefunden wird, wird None zurückgegeben.

Parameter:

OptimizationConfig Felder:

Verwenden Sie die Konfigurationswerte

Verwenden Sie das Modell und zusammengesetzte Anweisungen beim Aufrufen des Modells:

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

Die compose_instructions() Methode gibt die Systemaufforderung mit allen entdeckten Fähigkeiten zurück, die als Qualifikationskatalog angefügt werden.

Anwenden optimierter Toolbeschreibungen

Wenn Ihr Agent Tools (Funktionen) verwendet, wenden Sie ihnen optimierte Beschreibungen an:

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

Mit apply_tool_descriptions() der Methode werden die Metadaten der einzelnen Toolfunktionen mit den verbesserten Beschreibungen aus der Optimierungskonfiguration gepatcht. Dies verbessert die Genauigkeit des Modells bei der Entscheidung, welches Tool aufgerufen werden soll.

Wenn Ihre Tools nicht mit apply_tool_descriptions() kompatibel sind, lesen Sie die optimierten Definitionen aus config.tool_definitions und wenden Sie sie auf Ihre eigenen Tool-Objekte an. Jede Definition enthält sowohl die optimierte Funktionsbeschreibung als auch die Parameterbeschreibungen, sodass sie sowohl den Tools nach Funktions- als auch dem Parameternamen zugeordnet werden.

Laden von Fähigkeiten aus einem Verzeichnis

Wenn Ihre Optimierungskonfiguration keine Fähigkeiten enthält, können Sie sie aus einem lokalen Verzeichnis laden:

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

Protokollieren der Konfigurationsquelle (empfohlen)

Fügen Sie eine Protokollzeile hinzu, um zu bestätigen, wo die Konfiguration stammt:

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

Vollständiges Beispiel

Das folgende Beispiel zeigt einen Reisegenehmigungs-Agenten, der die Optimierungskonfiguration für Anweisungen, Tools und Fähigkeiten verwendet:

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

So funktioniert es

1. Normaler Vorgang: Es werden keine Optimierungsumgebungsvariablen festgelegt. Der Konfigurations-Loader liest .agent_configs/baseline/ und gibt Ihre Baseline-Konfiguration zurück. Der Agent arbeitet mit Ihren ursprünglichen Anweisungen.

2. Während der Optimierung: Der Optimierer legt OPTIMIZATION_CONFIG die Konfiguration des Kandidaten als Inline-JSON fest. Ihr Agent verwendet die Anweisungen und Toolbeschreibungen des Kandidaten während der Auswertung.

   Note

   Während der Auswertung ruft der Optimierer Ihren Agent für jede Aufgabe in Ihrem Dataset auf, sodass alle externen Toolaufrufe real ausgeführt werden. Anleitungen zum Vermeiden unbeabsichtigter Nebenwirkungen finden Sie unter "Funktionsweise des Agentenoptimierrs".

3. Nach dem Anwenden eines Siegers: Sie führen azd ai agent optimize apply --candidate <id> aus, um die optimierten Konfigurationsdateien unter .agent_configs/<candidate_id>/ in Ihr Projekt zu schreiben. Stellt dann azd deploy den Agent mit der verbesserten Konfiguration bereit. Die vollständigen Schritte zum Anwenden und Bereitstellen finden Sie unter Bereitstellen des Gewinners.

Ihr Code ändert sich niemals zwischen diesen Zuständen. Die Konfigurationsauflösung erfolgt vollständig automatisch.

Reihenfolge der Konfigurationsauflösung

Die load_config()-Funktion löst die Konfiguration mithilfe einer Prioritätskette auf (der erste Treffer gewinnt):

Überprüfen

Vergewissern Sie sich, dass das Paket importiert werden kann und die Konfiguration ordnungsgemäß geladen wird:

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

Verwandte Inhalte

• Übersicht über den Agent-Optimierer
• Erstellen eines Evaluierungsdatensatzes und von Evaluatoren
• Optimieren von Agentenanweisungen, Fähigkeiten, Tools und Modellen
• Schnellstart: Optimieren eines gehosteten Agents
• Agent Skills Format – offener Standard für portable Agent-Fähigkeiten