Подготовьте своего агента к оптимизации (предварительная версия)

Для добавления поддержки оптимизатора агента в агент требуется несколько строк кода. Никаких изменений платформы или условной логики не требуется. Вы устанавливаете пакет оптимизации, настраиваете каталог конфигурации и вызываете load_config() при запуске.

Этот шаг является первым шагом в рабочем процессе оптимизации. Созданная вами базовая конфигурация определяет, что именно оптимизатор улучшает: инструкции, инструменты, навыки и модель. Ваш агент работает одинаково независимо от того, включена оптимизация или нет.

Чтобы подготовить агента к оптимизации, выполните три шага.

1. Установите пакет оптимизации.
2. Настройте каталог базовой конфигурации с помощью инструкций и, при необходимости, инструментов и навыков.
3. Загрузите конфигурацию при запускеload_config() и используйте возвращаемые значения.

В остальной части статьи приводится полный пример и объясняется, как работает разрешение конфигурации. После завершения запуска оптимизации вы применяете победивший вариант и развертываете его — см. Развертывание победителя.

Необходимые условия

• Проект Foundry с развернутым размещенным агентом
• Общие сведения о размещённых агентах
• Python 3.10 или более поздней версии

Установка пакета оптимизации

Установите пакет azure-ai-agentserver-optimization.

pip install azure-ai-agentserver-optimization

Настройка каталога конфигурации

Создайте каталог .agent_configs/baseline/ в корневом каталоге проекта. Этот каталог определяет базовую конфигурацию агента — начальную точку, которую оптимизатор считывает и улучшает.

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

Для базового уровня требуются metadata.yaml и instructions.md. Файл tools.json и каталог skills/ необязательны — включайте их только в том случае, если ваш агент использует инструменты или навыки. Оптимизатор активирует каждый целевой объект в зависимости от того, какие из этих файлов присутствуют.

metadata.yaml

Файл метаданных сообщает загрузчику оптимизации, где найти файлы конфигурации и какую модель следует использовать:

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

instructions.md

Системная инструкция вашего агента. Напишите его как обычный текст или 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.

Оптимизатор улучшает этот запрос во время выполнения оптимизации. После применения оптимизированного варианта в этом файле содержится улучшенный вариант.

tools.json

Объявите средства, которые агент может вызывать с помощью формата вызова функций 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"]
      }
    }
  }
]

Оптимизатор может улучшить описания инструментов, чтобы модель могла более точно вызывать инструменты. После оптимизации вы применяете улучшенные описания обратно в этот файл.

skills/ (формат навыков агента)

Навыки используют открытый формат навыков агента . Каждый навык — это папка, SKILL.md содержащая файл:

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

Файл SKILL.md содержит YAML-блок метаданных и тело в формате Markdown для инструкций:

---
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 (name и description) обеспечивает постепенное раскрытие информации— агент загружает только метаданные при запуске, а затем активирует полные инструкции по навыку при обнаружении соответствующей задачи.

Оптимизатор может обнаруживать и создавать новые навыки во время оптимизации. Эти навыки записываются в каталог skills/ при применении оптимизированного кандидата.

Дополнительные сведения о формате навыков агента см. в agentskills.io.

Загрузка и использование конфигурации

Добавьте загрузчик конфигурации в верхней части точки входа агента:

from azure.ai.agentserver.optimization import load_config

config = load_config()

Функция load_config() считывает данные из .agent_configs/ и возвращает объект OptimizationConfig. Если кандидат оптимизации не активен, он возвращает базовую конфигурацию. Если источник конфигурации не найден, возвращается None.

Параметры:

OptimizationConfig Области:

Используйте значения конфигурации

Используйте модель и составленные инструкции при обращении к модели:

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

Метод compose_instructions() возвращает системный запрос с обнаруженными навыками, добавленными в качестве каталога навыков.

Применение оптимизированных описаний инструментов

Если агент использует средства (функции), примените к ним оптимизированные описания:

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

Метод apply_tool_descriptions() исправляет метаданные каждой функции средства с улучшенными описаниями из конфигурации оптимизации. Это повышает точность модели при выборе вызываемого средства.

Если ваши инструменты несовместимы apply_tool_descriptions() сconfig.tool_definitions, прочитайте оптимизированные определения и примените их к собственным объектам инструментов. Каждое определение включает как оптимизированное описание функции, так и описание параметров, поэтому сопоставляйте их с инструментами по имени функции и параметра.

Загрузка навыков из каталога

Если конфигурация оптимизации не включает навыки, их можно загрузить из локального каталога:

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

Записывать источник конфигурации в журнал (рекомендуется)

Добавьте строку журнала, чтобы подтвердить, откуда поступила конфигурация:

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

Полный пример

В следующем примере показан агент для утверждения командировок, который использует конфигурацию оптимизации для инструкций, инструментов и навыков:

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

Принцип работы

1. Обычная операция: переменные среды оптимизации не заданы. Загрузчик конфигурации считывает .agent_configs/baseline/ и возвращает базовую конфигурацию. Агент работает с исходными инструкциями.

2. Во время оптимизации: оптимизатор задает OPTIMIZATION_CONFIG конфигурацию кандидата в виде встроенного JSON. Агент использует инструкции кандидата и описания инструментов во время оценки.

   Note

   Во время оценки оптимизатор вызывает вашего агента для каждой задачи в вашем наборе данных, поэтому любые вызовы внешних инструментов выполняются в реальности. Рекомендации по предотвращению непреднамеренных побочных эффектов см. в статье о работе оптимизатора агента.

3. После применения победившей конфигурации: вы запускаете azd ai agent optimize apply --candidate <id>, чтобы записать оптимизированные файлы конфигурации в .agent_configs/<candidate_id>/ вашего проекта. Затем azd deploy развертывает агент с улучшенной конфигурацией. Полное описание шагов по применению и развертыванию см. в разделе Развернуть победивший вариант.

Ваш код никогда не изменяется между этими состояниями. Определение конфигурации выполняется полностью автоматически.

Порядок определения конфигурации

Функция load_config() определяет конфигурацию по цепочке приоритетов (используется первое совпадение):

Verify

Убедитесь, что пакет импортируется и конфигурация загружается правильно:

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

Связанный контент

• Обзор оптимизатора агента
• Создание набора данных оценки и оценщиков
• Оптимизация инструкций агента, навыков, инструментов и моделей
• Краткое руководство: оптимизация размещённого агента
• Формат навыков агента — открытый стандарт для навыков переносимого агента