エージェントオプティマイザーを準備する (プレビュー)

エージェント オプティマイザーのサポートをエージェントに追加するには、数行のコードが必要です。 フレームワークの変更や条件付きロジックは必要ありません。 最適化パッケージをインストールし、構成ディレクトリを設定し、起動時に load_config() を呼び出します。

この手順は、 最適化ワークフローの最初の手順です。 作成するベースライン構成によって、オプティマイザーによって改善される入力 (命令、ツール、スキル、モデル) が定義されます。 最適化がアクティブかどうかに関係なく、エージェントは同じように動作します。

エージェント オプティマイザーを準備するには、次の 3 つの手順を実行します。

1. 最適化パッケージをインストールします。
2. 手順と、必要に応じてツールとスキルを使用して、ベースライン構成ディレクトリを設定します。
3. 起動時にを使用してload_config()、返される値を使用します。

この記事の残りの部分では、完全な例を示し、構成の解決のしくみについて説明します。 最適化の実行が完了したら、優勝候補を適用してデプロイします。「 勝者のデプロイ」を参照してください。

Prerequisites

• デプロイ済みのホステッド エージェントを備えた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

エージェントのシステム プロンプト。 プレーン テキストまたはマークダウンとして記述します。

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 frontmatter (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. 最適化中: オプティマイザーは、候補の構成をインライン JSON として OPTIMIZATION_CONFIG 設定します。 エージェントは、評価中に候補の指示とツールの説明を使用します。

   Note

   評価中、オプティマイザーはデータセット内のすべてのタスクに対してエージェントを呼び出します。そのため、外部ツール呼び出しはすべて実際に実行されます。 意図しない副作用を回避するためのガイダンスについては、「 エージェント オプティマイザーのしくみ」を参照してください。

3. 勝者を適用した後: azd ai agent optimize apply --candidate <id> を実行して、最適化された構成ファイルをプロジェクトの .agent_configs/<candidate_id>/ に書き込みます。 次 azd deploy 、構成が改善されたエージェントをデプロイします。 適用とデプロイの完全な手順については、「 勝者をデプロイする」を参照してください。

これらの状態間でコードが変更されることはありません。 設定の決定は完全に自動で行われます。

設定の解決順序

load_config()関数は、優先順位チェーンを使用して構成を解決します (最初の一致が優先されます)。

確かめる

パッケージがインポート可能であり、構成が正しく読み込まれることを確認します。

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

関連するコンテンツ

• エージェント オプティマイザーの概要
• 評価データセットとエバリュエーターを作成する
• エージェントの指示、スキル、ツール、モデルを最適化する
• クイック スタート: ホストされるエージェントを最適化する
• エージェントスキルフォーマット — ポータブルエージェントスキルのためのオープンスタンダード