エージェントの指示、スキル、ツール、モデルを最適化する (プレビュー)

エージェント オプティマイザーは、ホストされるエージェントの 4 つの側面 ( 命令、 スキル、 ツール、 モデルの選択) を改善します。 エージェントのベースライン構成に基づいて、これらのターゲットのうちどれを最適化すべきかを自動的に検出します。

この記事では、最適化を実行し、実行を構成して監視し、結果をデプロイする方法について説明します。 各ターゲットの動作とアクティブ化のタイミングについては、「 最適化ターゲット」を参照してください。 ベースライン入力を設定するには、「 エージェント オプティマイザーの準備完了」を参照してください。 オプティマイザーの変更点のクイック リファレンスについては、 各ターゲットの変更を参照してください。

Prerequisites

• デプロイ済みのホステッド エージェントを備えたFoundry プロジェクト
• azure.ai.agents CLI 拡張機能がインストールされている (「クイック スタート: ホストされるエージェントを最適化する」を参照)
• 評価用にデプロイされたモデル (たとえば、 gpt-4.1-mini) と 、サポートされている一覧 の最適化モデル ( gpt-5.1 など)
• エージェントが オプティマイザー対応 (呼び出し load_config())

最適化を実行する

1 つのコマンドで最適化の実行を開始します。

azd ai agent optimize

オプティマイザーはベースラインを評価し、候補を生成して評価し、結果をランク付けします。 完全な評価と改善のサイクルについては、「 エージェント オプティマイザーのしくみ」を参照してください。 どのターゲットを実行するかは、ベースラインの構成 (一致するベースライン ファイルが存在する場合に、命令のチューニング、スキルの向上、ツールの最適化が自動的にアクティブ化される) によって異なります。 最適化ターゲットを参照してください。

構成ファイルを使用して実行を制御するには、データセット、エバリュエーター、およびオプションを参照する eval.yaml を渡します。

azd ai agent optimize --config eval.yaml

完全な eval.yaml スキーマについては、「 最適化の実行を構成する」を参照してください。

特定のエージェントをターゲットとする

CLI でエージェントを解決する方法は、 azd プロジェクトからコマンドを実行するかどうかによって異なります。

デプロイされたエージェント名は、ターゲット Foundry プロジェクトのホストされているエージェントと一致している必要があります。

AZD プロジェクト ファイルを使用せずに既存のエージェントを最適化する

azd ai agent initを実行せずに、azure.yamlまたは.azure環境ディレクトリを作成せずに、既存のホステッド エージェントを最適化できます。 このスタンドアロン フローでは、Foundry プロジェクト エンドポイントとデプロイされたエージェント名を明示的に指定します。

1. デプロイされたエージェントが オプティマイザー対応であることを確認します。 ローカル作業ディレクトリで、「最適化実行の構成」で説明されている命令ファイル、データセット、エバリュエーター、およびeval.yamlを作成します。

   この作業ディレクトリからコマンドを実行します。 azd プロジェクトがない場合、eval.yamlの相対パスは現在の作業ディレクトリから解決されます。

   このスタンドアロン フローでは、 agent.configを省略します。 CLI は、コマンドの実行時にベースライン命令を要求します。

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. 認証：

   az login
   azd auth login
   

3. Foundry プロジェクトの [概要 ] ページからプロジェクト エンドポイントをコピーします。 Azure リソース ID ではなく、プロジェクト エンドポイント URL を使用します。

4. 後続のコマンドが任意のディレクトリから同じプロジェクトを解決できるように、エンドポイントをユーザー レベルの azd 構成に保存します。

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   この手順では、既定のエンドポイントを ~/.azd/config.jsonに書き込みます。 保存されたコンテキストを検査またはクリアするための完全な解決順序とコマンドについては、 azd コマンドの Foundry プロジェクト コンテキストの設定を参照してください。

5. デプロイされたエージェント名で最適化を実行します。

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   エージェント命令の入力を求められたら、インラインで指定するか、 .agent_configs/baseline/instructions.mdなどのファイルを選択します。

   Note

   現在のプレビューでは、スタンドアロン実行では、eval.yamlからagent.configは展開されません。 ベースライン命令を指定できるように、コマンドを対話形式で実行します。 このフローには --no-prompt を使用しないでください。 ファイル ベースのスキルとツールのベースラインを読み込むには、 azd プロジェクトも必要です。

   ユーザー レベルの構成を変更すべきではない 1 回限りのコマンドの場合は、 --project-endpoint渡します。

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   現在のシェルのエンドポイントを設定することもできます。

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. コマンド出力から操作 ID を保存します。 このフローには azd 環境がないため、CLI は最後の操作 ID をローカルに保持しません。 操作 ID をフォローアップ コマンドに渡します。

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   これらのコマンドは、 azd ai project setによって保存されたエンドポイントを使用します。 代わりに 1 回限りの --project-endpoint フォームを使用した場合は、フラグを各フォローアップ コマンドに再度渡します。

最適化の実行を構成する

データセット、エバリュエーター、実行オプションを結び付けて eval.yaml ファイルを使用して最適化実行を構成します。 コマンド azd ai agent eval generate このファイルを書き込むか、手動で作成できます。 オプティマイザーは、プロジェクト ルート内の eval.yaml を自動検出するか、 --config eval.yamlを使用して明示的に渡すことができます。

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

データセットとエバリュエーターを個別に作成します。 評価データセットとエバリュエーターの作成を参照してください。 次のセクションでは、実行オプションについて説明します。

評価モデルと最適化モデルを選択する

オプティマイザーでは、条件に対してエージェントの応答をスコア付けする 評価モデル と、候補の構成を生成する 最適化モデル の 2 つのモデルが使用されます。 eval.yamlで設定するか、CLI フラグを使用します。

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

プロジェクトにデプロイされたすべてのチャット完了モデルは、評価モデルとして機能します。 最適化モデルは、サポートされている一覧に含まれている必要があります。 ロールとサポートされているモデルについては、「 モデル」を参照してください。

候補の数を設定する

max_candidates オプションは、実行に必要な構成の数を設定します。 オプティマイザーは通常、エラーまたは別の停止状態のために実行が早期に停止しない限り、そのカウントに達した後に戻ります。

値が大きいほど、より多くのバリエーションが探索されますが、時間がかかります。 オプティマイザーは以前の候補から学習するため、後の候補のスコアが高くなる傾向があります。

複数のモデルを評価する

1 回の実行でモデルのデプロイを比較するには、それらを optimization_config.model_search_space の下に一覧表示します。 オプティマイザーは、同じデータセットに対して各モデルでエージェントを評価し、スコアとトークン コストによって結果をランク付けします。

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

model_search_spaceの下に一覧表示されている各モデルは、Foundry プロジェクトに配置する必要があります。

モデルの選択は、ベースラインから自動的にアクティブ化されるターゲットと共に実行されます。 1 回の実行で、改善された命令、スキル、およびツールの説明をさまざまなモデル オプションと組み合わせた候補を生成できます。組み合わせを自分で構成することはできません。

実行中のジョブを監視する

最適化の実行は非同期です。 ジョブの実行時間が長い場合、またはジョブの進行状況を確認する場合は、次のコマンドを使用します。

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <operation-id>

実行出力から、操作 ID、ポータル URL、スコア、候補 ID をキャプチャします。 実行の開始時に表示される URL を使用して 、Foundry ポータル でジョブを監視することもできます。

AZD プロジェクト ファイルなしでジョブを開始した場合は、常に操作 ID を status に渡し、cancelします。 コマンドは、 azd ai project setによって保存されたユーザー レベルのエンドポイントを使用します。それ以外の場合は、 --project-endpointを含めます。

結果を解釈する

最適化が完了したら、結果テーブルを確認します。 アスタリスク (*) が最適な候補としてマークされます。 結果テーブルの列、スコア付けの詳細、スコア改善のしきい値、ポータル ビューについては、「 最適化の結果について」を参照してください。

勝者をデプロイする

推奨されるワークフローは、最適化された構成をローカルに適用してからデプロイすることです。

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

これにより、最適化された構成がプロジェクトの .agent_configs/<candidate_id>/ にダウンロードされます。 次のデプロイでは、エージェントは改善された手順とツールの説明を使用します。

または、API を使用して直接デプロイすることもできます (迅速な A/B テストに役立ちます)。

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

すべての候補のスコアがベースラインより低い場合は、候補をデプロイしないでください。 ベースライン構成はアクティブなままです。

各ターゲットが変更する内容

オプティマイザーは、ベースラインに適用されるターゲットを自動的にアクティブ化します。 このセクションは、実行によって何が変更されるかについてのリファレンスです。 次の表を使用して、エージェントの最適化が何を行うかを予測します。

load_config()は最適化された値を自動的に返すので、コードはすべてのターゲットで同じままです。 変更が表示されるのは、モデルの構成のみです。

手順

オプティマイザーは、システム プロンプトを書き換えます。 一般的な機能強化は次のとおりです。

• 元のプロンプトが暗黙的に示したが、示していない明示的な制約を追加する
• 明確にするために手順を再構築する
• 出力形式仕様の追加
• 安全とスコープの境界の強化

たとえば、 You are a helpful assistant. のような最小限のベースライン プロンプトは次のようになります。

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Skills

オプティマイザーは、スキルの目的をそのまま維持しながら、各スキルの説明、本文、アクティブ化の条件を調整します。 エージェントは、 load_config()を通じて改善されたスキルを読み込み、それらを命令セットに追加します。 スキルは、オープンな エージェント スキル 形式を使用します。 エージェントがスキルを読み込む方法については、 エージェントオプティマイザーの準備を参照してください。

Tools

オプティマイザーは、 tools.json 定義を調整します。 一般的な機能強化は次のとおりです。

• ツールを呼び出すタイミングをモデルが把握するのに役立つ、より明確な関数の説明
• 不正確な引数を減らすより具体的なパラメーターの説明
• 無効な入力を防ぐ制約 (列挙型、必須フィールド) を追加しました

ツール実装コードは同じままです。 モデルに変更が表示されるのは定義だけです。

Models

オプティマイザーでは、複合スコアとトークン コストによって各候補モデルがランク付けされるため、最適な品質とコストのトレードオフを選択できます。 候補を構成するには、「複数の モデルを評価する」を参照してください。

Troubleshooting

関連するコンテンツ

• エージェント オプティマイザーの概要
• エージェントオプティマイザーの準備を整える
• 評価データセットとエバリュエーターを作成する
• クイック スタート: ホストされるエージェントを最適化する