クイック スタート: ホストされたエージェントを最適化する (プレビュー)

• azd CLI (Azure Developer CLI)。

• 認証用のAzure CLI。

• azd の microsoft.foundry 拡張機能 ( azure.ai.agents 依存関係の 0.1.40-preview 以降):

  azd ext install microsoft.foundry
  

  既にインストールされている場合は、アップグレードします。

  azd ext upgrade microsoft.foundry
  

• 認証用のAzure CLI。

• Python 3.10 以降。

• このパスで使用されるPython パッケージ:

  pip install "azure-ai-projects>=2.4.0" azure-ai-agentserver-optimization azure-identity python-dotenv
  

• 最適化に使用するホステッド エージェント、登録済みデータセット、エバリュエーターが既に含まれている既存の Foundry プロジェクト。

• Visual Studio Code。

• Microsoft Foundry Toolkit for Visual Studio Code バージョン 1.6.4 以降。Azure にサインインしています。 Foundry Toolkit は、このワークフローで使用Microsoft Foundry スキルをインストールして更新します。

• エージェント モードにアクセス可能なVisual Studio Code の GitHub Copilot Foundry Toolkit は、エージェント ワークスペースを選択した後、エージェント オプティマイザー要求をGitHub Copilotに送信します。

• Azure CLIおよび Azure Developer CLI (AZD) がインストールされ、認証されました。

  az login
  azd auth login
  

• Microsoft Foundry Skill がインストールされているコーディング エージェント ホスト。

• Azure CLIおよび Azure Developer CLI (AZD) がインストールされ、認証されました。

  az login
  azd auth login
  

• AZD の microsoft.foundry 拡張機能。 ワークフローを開始する前にインストールします。

  azd ext install microsoft.foundry
  

  既にインストールされている場合は、アップグレードします。

  azd ext upgrade microsoft.foundry
  

手順 1: プロジェクトを作成する

最適化サンプル テンプレートから新しいプロジェクトを初期化します。

mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .

このテンプレートは、最適化カスタマー サポート サンプルをインポートします。これは、独自のアプローチと応答プロトコルを使用する、最適化対応のPythonホストされたエージェントです。 これは、注文の問い合わせ、返品、保証請求、トラブルシューティング、苦情、推奨事項、エスカレーションを処理するコンシューマー エレクトロニクス サポート エージェントを表します。 意図的に最小限のベースライン命令を使用すると、命令の最適化とスキル検出の改善を簡単に比較できます。

このサンプルでは、ベースラインまたは候補の構成を読み込む load_config() が呼び出され、 .agent_configs/baseline/、 eval.yaml、完全かつ迅速な評価データセット、コンテナー構成、Foundry 配置マニフェストが含まれます。 対話型フローでは、これらのファイルがインポートされ、Azure サブスクリプション、リージョン、モデルのデプロイ設定が求められます。

手順 2: プロビジョニングとデプロイ

Azure リソースを認証してプロビジョニングします。

az login
azd auth login
azd provision

プロビジョニングには約 2 分かかり、Foundry アカウント、プロジェクト、Azure Container Registry、モデルのデプロイが作成されます。

エージェントをデプロイします。

azd deploy

デプロイをテストします。

azd ai agent invoke "What is 2+2?"

手順 3: 評価スイートを生成して最適化する

エージェントの評価データセットとエバリュエーターを生成します。

azd ai agent eval generate

この手順では、エージェントの指示に基づいて、 eval.yaml、テスト データセット、スコア付けエバリュエーターを作成します。 オプティマイザーは、これらのファイルを使用して改善を測定します。

オプティマイザーを実行します。

azd ai agent optimize --max-candidates 2

CLI によって、最適化モデルの選択が求められます。 プロンプトをスキップするには、直接渡します。

azd ai agent optimize --max-candidates 2 --optimize-model gpt-5

CLI は、 azure.yaml からエージェントを検出し、生成された eval.yaml を自動的に使用します。 2 つの候補がある場合、通常、最適化は約 8 分で完了します。 リアルタイムの進行状況が表示されます。

Optimizing agent "customer-support-py"...
  Config: eval.yaml
  Baseline saved to .agent_configs/baseline/metadata.yaml
  Job ID: opt_162bd0f09....
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

ポータル URL を使用して、Foundry ポータルでジョブを監視します。

評価モデルは、各応答にスコアを付けます (チャット完了モデルが機能します)。 最適化モデル (--optimize-model) は、改善された候補を生成し、サポートされている一覧 (gpt-5 ファミリまたは DeepSeek) から取得する必要があります。 optimization_modelのoptions:の下にeval.yamlを設定して、毎回フラグを渡さないようにすることもできます。

手順 4: 勝者をデプロイする

出力の星 (*) は、最適な候補を示します。 最適化された構成をローカルに適用し、デプロイします。

azd ai agent optimize apply --candidate <candidate-id>
azd deploy

apply コマンドは、最適化された構成を.agent_configs/<candidate_id>/にダウンロードし、新しい手順を使用するようにazure.yamlを更新します。 deploy コマンドは、コードデプロイを使用して最適化されたエージェントをライブでプッシュします。

エージェントを呼び出して改善点を確認します。

azd ai agent invoke "What is your return policy?"

評価を実行して、スコアの改善を確認することもできます。

azd ai agent eval run

Python SDK パス

前に説明したAzure開発者 CLI ワークフローではなく、Pythonからオプティマイザーを実行する場合は、次の手順を使用します。

このパスは、既存の Foundry プロジェクトに次のリソースが既に存在することを前提としています。

• 最適化するホステッド エージェント。
• 登録済みのトレーニング データセット。
• 登録済みのエバリュエーター。

前述の Azure Developer CLI フローとは異なり、Python SDK パスはプロジェクトをスキャフォールディングしたり、eval.yaml、データセット、エバリュエーターを生成したりすることはありません。 サンプルでこれらの資産を自動的に作成する場合は、最初に azd ai agent eval generate 使用します。

1. .env ファイルを作成する

作業フォルダーを作成し、次の値を持つ .env ファイルを追加します。

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>

この同じ作業フォルダーからスクリプトを実行 load_dotenv() 、 .env ファイルを自動的に読み込むことができます。 別のディレクトリから実行する場合は、最初にシェル環境で同じ値を設定します。

Foundry プロジェクトの [概要 ] ページにある正確なプロジェクト エンドポイントを使用します。 Python スクリプトは、最初の要求を直ちに送信します。 FOUNDRY_PROJECT_ENDPOINTがプレースホルダーのみであるか、間違ったプロジェクトを指している場合、実行はResourceNotFound: The project does not existで失敗します。

EVAL_MODELとOPTIMIZATION_MODELを、モデル ファミリ名だけでなく、Foundry プロジェクトに既に存在する配置名に設定します。 たとえば、プロジェクトの配置に gpt-4.1-mini または DeepSeek-V3.2という名前が付けられている場合は、 .envでその正確な配置名を使用します。

2. 最適化ジョブを実行する

optimize_hosted_agent.pyと同じフォルダーに .env という名前のファイルを作成します。

import os
import time

from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  OptimizationAgentIdentifier,
  OptimizationEvaluatorRef,
  OptimizationJob,
  OptimizationJobInputs,
  OptimizationOptions,
  OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))

optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = OptimizationJob(
    inputs=OptimizationJobInputs(
      agent=OptimizationAgentIdentifier(agent_name=agent_name),
      train_dataset=OptimizationReferenceDatasetInput(
        name=dataset_name,
        version=dataset_version,
      ),
      evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
      options=OptimizationOptions(
        max_candidates=2,
        eval_model=eval_model,
        optimization_model=optimization_model,
        optimization_config={
          "system_prompt": optimization_config.instructions,
          **({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
          **({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
        }
      ),
    )
  )
  poller = project_client.beta.agents.begin_create_optimization_job(job=job)

  print(f"Optimization job started, waiting for completion...")
  while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

  result = poller.result()

  if result:
    print(f"Baseline candidate: {result.baseline}")
    print(f"Best candidate: {result.best}")

    for candidate in result.candidates or []:
      print(
        f"{candidate.name}: candidate_id={candidate.candidate_id}, "
        f"avg_score={candidate.avg_score:.4f}, "
        f"avg_tokens={candidate.avg_tokens:.0f}"
      )

スクリプトを実行します。

python optimize_hosted_agent.py

ジョブが成功すると、スクリプトが選ばれた候補とその candidate_id を出力します。

azd ai agent optimizeとは異なり、Python SDK フローではローカル .agent_configs/baseline/metadata.yaml ファイルは作成されません。 最適化ジョブのメタデータは、返された job オブジェクトと Foundry サービス応答 (ベースライン候補、最適な候補、スコア付けされた候補リストを含む) にとどまります。

3. 当選者を応募する

上記の CLI フローで使用したローカルの azd プロジェクトでも作業している場合は、Python スクリプトから返された candidate_id を使用して、選ばれた候補を適用してください。

azd ai agent optimize apply --candidate <candidate-id>
azd deploy

結果のみを検査する必要がある場合は、スクリプトによって出力された候補スコアと評価識別子を使用して、Foundry の成功した構成を昇格する前に確認します。

VS Code で最適化を実行する

Foundry Toolkit には、デプロイされたホステッド エージェント用のネイティブ エージェント最適化エクスペリエンスが含まれています。 エージェントのプレイグラウンドから、最適化の実行を開始し、候補をベースラインと比較し、構成の変更を検査し、最適な候補をデプロイできます。

手順 1: デプロイされたホステッド エージェントを選択する

1. アクティビティ バーで Foundry Toolkit を選択します。
2. [ マイ リソース] で、[エージェント] を選択 します。
3. デプロイされたホステッド エージェントがある場合は、それを選択して、ホストされたエージェントのプレイグラウンドを開きます。
4. デプロイされたホスト型エージェントがない場合は、「 クイック スタート: 最初のホストされたエージェントをデプロイする」の VS Code パスを完了します。 デプロイが完了したら、 エージェント に戻り、新しいホステッド エージェントを選択します。

手順 2: 最適化の実行を開始する

1. プレビューとしてマークされている [最適化] タブを選択します。

1. [ 新しい最適化] を選択します。

2. [ ワークスペースの選択] で、選択したホステッド エージェントのコードを含むワークスペースを選択します。

   • 現在のワークスペースにエージェント コードとそのazure.yaml ファイルが含まれている場合は、[現在のワークスペース] を選択します。
   • [ 参照]... を選択して、エージェント コードを含むワークスペースを開きます。

   Foundry Toolkit は、ワークスペース ファイルを使用して最適化を準備し、一致する azure.ai.agent サービスに候補を適用します。

1. Foundry Toolkit によって GitHub Copilot Chatが開き、選択したエージェントの種類、名前、および Foundry プロジェクト エンドポイントが設定されたエージェント オプティマイザー要求が送信されます。

2. Copilot Chatの 4 つの最適化の質問に回答します。

   入力	提供する内容
   評価メトリック	使用するメトリックまたはエバリュエーターを入力します。 お持ちでない場合は、 azd ai agent eval generate 実行するか、オプティマイザーの組み込みの既定値を使用するかを選択します。
   Dataset	最適化データセットを選択します。 お持ちでない場合は、 azd ai agent eval generate 実行するか、オプティマイザーの組み込みの既定値を使用するかを選択します。
   最大候補数	生成する候補の最大数 ( 2など) を入力します。
   最適化モデル	サポートされている最適化モデルから既存のデプロイを選択します。

GitHub Copilotは、最適化を開始する前に、これらの入力を待機します。 生成されたリクエストは、Copilot に対して Microsoft Foundry Skill の Agent Optimizer ワークフローと Azure Developer CLI コマンドのみを使用するよう指示します。 Foundry MCP ツールは使用されません。 コパイロット:

• 選択したワークスペース内のエージェント コードを検査します。
• プロジェクトにまだ AZD 環境がない場合は、既存の azure.yaml と .env の値から AZD 環境を初期化します。
• 最適化のためにエージェントをワイヤ化し、更新されたホステッド エージェントをデプロイします。
• エージェント サービス フォルダーに eval.yaml を作成します。
• 提案されたファイルの変更とコマンドを確認して承認した後、最適化を開始します。

Copilot がジョブを送信した後、最適化 タブに戻ってください。実行結果が 最適化の実行 の下に表示されます。 テーブルには、実行 ID、状態、候補数、ベースライン スコア、ベスト スコア、作成時間が表示されます。

手順 3: 最適な候補を比較してデプロイする

1. 実行が成功したら、[ 最適化の実行] で選択します。
2. ベースラインとベスト スコアを比較します。 各候補の スコアの詳細 を確認し、[ 変更の表示 ] を選択して構成の変更を検査します。
3. ベースラインで最適な候補が改善された場合は、[ 最適な候補のデプロイ ] を選択して現在のエージェントを更新します。 新しいエージェントとしてデプロイするか、デプロイ設定を変更するには、代わりに [カスタム デプロイ ] を選択します。

Microsoft Foundry スキルを使用して最適化を実行する

このパスは、Visual Studio Code、Copilot CLI、Claude Code のGitHub Copilotなど、Microsoft Foundry スキルをサポートする任意のコーディング エージェント ホストで使用します。 スキルは、 azure.yamlからエージェント コンテキストを解決し、エージェント オプティマイザー ワークフローを読み込み、候補アプリケーションとデプロイをレビュー ゲートの背後に保持します。

手順 1: エージェント ワークスペースを開く

コーディング エージェント ホストで空のフォルダーを開きます。 microsoft-foundryスキルが使用可能であることを確認します。 スキルを利用できない場合は、コーディング エージェントで Microsoft Foundry スキルを使用するに従ってください。

手順 2: エージェント オプティマイザーを実行するようにスキルに依頼する

このプロンプトをコーディング エージェントに送信します。

Use the Microsoft Foundry Skill to run the Agent Optimizer workflow for a
Python hosted agent. If this workspace doesn't contain an agent, initialize the
customer support optimization sample from this template:
https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml
Resolve the AZD environment and hosted-agent service, verify that the agent is
optimizer-ready, and deploy and invoke the baseline. Generate and show me the
evaluation dataset, evaluators, and eval.yaml before running optimization.
Verify that the project has a supported optimization model deployment, then run
Agent Optimizer with two candidates. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.

ワークスペースからこれらの値を解決できない場合、コーディング エージェントからサブスクリプション、リージョン、Foundry プロジェクト、エージェント サービス、評価モデル、または最適化モデルを選択するように求められる場合があります。 変更やコマンドを承認する前に、生成されたファイルとコストの高いリソースを確認します。

手順 3: 承認済みの候補者を適用して展開する

最適化の結果を確認したら、次のフォローアップ プロンプトを送信します。

Recommend the best optimization candidate and explain the score improvement.
Summarize the candidate changes before applying anything. After I approve the
candidate, apply it locally, show the source diff, and stop again before
deployment. After I approve deployment, run azd deploy, invoke the agent with
"What is your return policy?", and rerun the evaluation to confirm the
improvement.

スキルでは azd ai agent optimize apply --candidate <candidate-id> を使用するため、最適化された構成をローカルで確認できます。 承認後にのみデプロイされ、更新されたホステッド エージェントが呼び出されて評価されます。