1. はじめに
こんにちは、2年目エンジニアの飯棲です。
最近は自宅で電子サックスを吹くことにハマっています。
前回の記事では Microsoft Foundry の Hosted Agent を使って、エージェントをデプロイしました。
今回は Hosted Agent を改善するための機能である Agent Optimizer を試してみます。
Agent Optimizer は質問とその正解を用意した評価データでエージェントを試して採点し、その結果をもとにプロンプトや Tool の説明などを書き換えて、エージェントを最適化する機能です。
ブログ執筆時点では preview です。
この記事では Tool でデータベースを照会するエージェントを Optimizer で最適化し、Tool の使い方が最適化の前後でどう変わるかを比べます。
- 1. はじめに
- 2. Agent Optimizer とは
- 3. 今回の検証内容
- 4. エージェントを Optimizer に対応させる
- 5. 評価データを用意する
- 6. 評価器を用意する
- 7. Optimizer を実行する
- 8. 結果を確認し、候補を選ぶ
- 9. まとめ
2. Agent Optimizer とは
Agent Optimizer は Microsoft Foundry Agent Service の機能です。
Hosted Agent では、評価のたびにエージェントが実際に Tool を実行するので、最終回答だけでなく Tool をどう呼び出し、どんな結果が返ったかまで評価できます。
Foundry のもう 1 つの種類である Prompt Agent(Foundry ポータルでプロンプトと Tool を設定して作るエージェント)では、Tool がクライアント側で実行されるため、Optimizer は Tool の実行を評価できません(公式ドキュメント)。
Hosted Agent で最適化の対象にできるのは、次の 4 つです。
| 対象 | 内容 |
|---|---|
| プロンプト(instructions) | エージェントのシステムプロンプトを改善する |
| Skill | SKILL.md の目的を保ちながら、本文を改善する |
| Tool の説明 | function calling の Tool の説明文を改善する(型や必須項目は変えない) |
| モデル | 指定した複数のモデルデプロイから選ぶ |
Optimizer は次の 5 つのステップで使います。

- エージェントを Optimizer に対応させる(4 章)
- 評価データを用意する(5 章)
- 評価器を用意する(6 章)
- Optimizer を実行する(7 章):最適化前のエージェント(baseline)を評価し、その結果をもとにプロンプトや Tool の説明を書き換えた「候補」を作って評価します。これを、候補の数が上限に達するまでくり返します。
- 結果を確認し、候補を選ぶ(8 章):baseline と候補の score や書き換えられた内容を比べ、採用する候補を選んで適用します。
3. 今回の検証内容
3.1 最適化するエージェント
今回は在庫データを照会する Hosted Agent を最適化します。
ユーザーの質問を受けて Cosmos DB の在庫データを SQL で照会し、その結果をもとに回答するエージェントです。
エージェントが使う Tool は、query_cosmos_items の 1 つだけです。
この Tool は読み取り専用で、1 つの SELECT 文だけを実行できます。
このほかに、Skill(SKILL.md)を 1 つ持っています。
3.2 事前準備
今回の検証には、次のものが必要です。
- Microsoft Foundry プロジェクトと、モデルのデプロイ 3 つ(エージェント用
gpt-5.6-luna、評価モデルgpt-5.6-terra、最適化モデルgpt-5.4) - Azure Cosmos DB for NoSQL(エージェントが照会する在庫データ)
最適化モデルは公式ドキュメントの一覧にあるモデルから選ぶ必要があります。
4. エージェントを Optimizer に対応させる
最初に、Optimizer の作った候補を読み込めるように、エージェントのプロンプトなどをコードの外のファイルに分けて、そこから読み込むようにします。
プロジェクトは Microsoft のサンプルから azd ai agent init で作りました(フォルダ名は変更しています)。
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/hello-world/azure.yaml
このあと作るファイルも含めて、主なファイルは次のとおりです。
Optimizer が書き換える元になるファイルは、.agent_configs/baseline/ に置きます。
inventory-cosmos-query-agent/ ← コマンドを実行するフォルダ
├── azure.yaml
└── src/inventory-cosmos-query-agent/
├── main.py ← load_config() で設定を読む
├── .agent_configs/baseline/
│ ├── instructions.md ← プロンプト
│ ├── tools.json ← Tool の定義
│ ├── skills/cosmos-read-query/SKILL.md ← Skill
│ └── metadata.yaml ← Optimizer の実行時に自動で作られる
├── datasets/ ← 評価データ(5 章)
│ ├── eval.optimization.jsonl
│ └── eval.validation.jsonl
└── eval.yaml ← Optimizer の設定(7 章)
main.py では、azure-ai-agentserver-optimization パッケージの load_config() で設定を読み、プロンプト、Tool の定義、Skill を取り出します。
from pathlib import Path from azure.ai.agentserver.optimization import load_config, load_skills_from_dir config = load_config() MODEL = config.model if not config.skills and config.skills_dir: config.skills = load_skills_from_dir(Path(config.skills_dir)) INSTRUCTIONS = config.compose_instructions() # プロンプト TOOLS = config.tool_definitions # Tool の定義
load_config() が設定を読む順番などは、公式ドキュメントの「Make your hosted agent optimizer-ready」にあります。
5. 評価データを用意する
次に、Optimizer が baseline と候補を評価するときに使う評価データを用意します。
Optimizer には 2 種類の評価データを渡せます。
| データ | 目的 |
|---|---|
| 最適化用データ | 候補を作るために使う |
| validation 用データ | 候補作りとは別に取っておき、できた候補を評価する |
各行には質問(query)、参照回答(ground_truth)、その質問で見る観点(criteria)を書きます。
validation 用データの 1 行は、次のような形です。
{ "name": "heldout-nagoya-date", "query": "名古屋倉庫で 2026-09-21(UTC)以降に更新された商品は?", "ground_truth": "名古屋倉庫は warehouseId=nagoya-01。lastUpdatedAt が 2026-09-21T00:00:00Z 以降の商品はメカニカルキーボード(sku-1011)と Bluetooth スピーカー(sku-1013)の 2 件(どちらも 2026-09-22)。データなしや warehouseId の聞き返しは不正解。", "criteria": [ { "name": "warehouse_discovery", "instruction": "倉庫名をそのまま warehouseId として照会せず、先に倉庫 ID を調べる照会(warehouseId の一覧など)を行い、その後 nagoya-01 を条件にして照会する。" }, { "name": "date_filter", "instruction": "lastUpdatedAt >= 2026-09-21T00:00:00Z の条件で照会し、メカニカルキーボードと Bluetooth スピーカーの 2 件を答える。" } ] }
この例の質問は倉庫名で聞いていますが、在庫データでは倉庫を tokyo-01 のような倉庫 ID(warehouseId)で区別していて、倉庫名の項目はありません。
そのため、criteria の warehouse_discovery では Tool で倉庫 ID を調べてから照会することを求めています。
データは最適化用と validation 用にそれぞれ 15 件用意しました。
validation 用データには最適化用データに出てこない商品や倉庫の質問を入れています。
Tool の使い方が偏らないように、倉庫名で照会する質問のほかに、数値で絞り込む質問、集計する質問、曖昧なので聞き返すべき質問、Tool を使わずに断るべき質問などを、両方に入れています。
6. 評価器を用意する
続いて、エージェントの応答を採点する評価器を用意します。
Optimizer の公式ドキュメントでは、組み込みの評価器として、指示どおりに作業できたかを見る builtin.task_adherence が例に挙がっています。
ただし、Optimizer では Tool の呼び出しと結果が最終回答(response)とは別の tool_calls という入力で渡され、builtin.task_adherence はこれを読みません。
そのため、最終回答が Tool の結果と合っているかを採点できません。
そこで、tool_calls を受け取って、最終回答が Tool の結果と合っているかを 1〜5 点で採点する評価器を作りました。
評価器の定義(クリックで展開)
{ "name": "inventory-tool-results", "categories": ["quality"], "display_name": "inventory-tool-results", "description": "Checks whether the final answer is supported by the Tool results passed in tool_calls. Used to test whether a custom evaluator can read tool_calls under the Optimizer data mapping.", "definition": { "type": "prompt", "prompt_text": "You evaluate an inventory agent that answers questions by calling a read-only database Tool.\n\nYou receive the user query, the agent's final answer, the Tool calls with their results, the Tool definitions, and a reference answer.\n\n### Query\n{{query}}\n\n### Final answer\n{{response}}\n\n### Tool calls and Tool results\n{{tool_calls}}\n\n### Tool definitions\n{{tool_definitions}}\n\n### Reference answer\n{{ground_truth}}\n\n### Task\n1. List the concrete values that appear in the Tool results (items with type function_call_output, or messages with role tool). Examples: IDs, counts, quantities, errors, empty results. If no Tool results are present in the input, write NONE.\n2. Judge whether the final answer is consistent with those Tool results and with the reference answer. Do not penalize the answer for not repeating Tool results verbatim.\n\n### Scoring (1-5)\n5: The answer is correct and every factual claim is supported by the Tool results.\n4: Correct with minor unsupported details.\n3: Partly correct or partly supported.\n2: Mostly incorrect or unsupported.\n1: Incorrect, or contradicts the Tool results.\nIf the question needs no database access and the answer correctly declines or asks for clarification, score 5.\n\n### Output format (JSON)\n{\n \"result\": <integer from 1 to 5>,\n \"reason\": \"TOOL_RESULTS: <values from step 1, or NONE> | JUDGEMENT: <brief explanation>\"\n}\n", "init_parameters": { "type": "object", "properties": { "deployment_name": { "type": "string" }, "model": { "type": "string" }, "threshold": { "type": "number" } }, "required": ["deployment_name"] }, "data_schema": { "type": "object", "properties": { "query": { "type": "string" }, "response": { "type": "string" }, "tool_calls": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ] }, "tool_definitions": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ] }, "ground_truth": { "type": "string" } }, "required": ["query", "response"] }, "metrics": { "custom_prompt": { "type": "ordinal", "desirable_direction": "increase", "min_value": 1, "max_value": 5 } } } }
評価器は Python SDK(azure-ai-projects)で Foundry プロジェクトに登録します。
評価器を登録するコード(クリックで展開)
import json from pathlib import Path from azure.ai.projects import AIProjectClient from azure.identity import DefaultAzureCredential definition = json.loads(Path("prompt_evaluator.json").read_text(encoding="utf-8")) with AIProjectClient(endpoint="<プロジェクトのエンドポイント>", credential=DefaultAzureCredential()) as project: created = project.beta.evaluators.create_version( name=definition["name"], evaluator_version=definition, ) print(f"registered name={created.name} version={created.version}")
7. Optimizer を実行する
準備ができたので、Optimizer を実行して、baseline の評価から候補の作成・評価までを行います。
Optimizer の設定は eval.yaml に書きます。
ここで、5 章の評価データ、6 章の評価器、使うモデルを指定します。
name: inventory-cosmos-query-agent-v1-eval agent: name: inventory-cosmos-query-agent-v1 kind: hosted version: "1" model: gpt-5.6-luna config: .agent_configs/baseline/metadata.yaml instruction_file: .agent_configs/baseline/instructions.md dataset: # 最適化用データ local_uri: datasets/eval.optimization.jsonl validation_dataset: # validation 用データ local_uri: datasets/eval.validation.jsonl evaluators: # 6 章で登録した評価器 - name: inventory-tool-results version: "1" options: eval_model: gpt-5.6-terra # 採点に使うモデル optimization_model: gpt-5.4 # 候補を作るモデル max_candidates: 4 # 作る候補の数の上限
プロジェクトのフォルダ(azure.yaml があるフォルダ)で、次のコマンドを実行します。
azd ai agent optimize --config src/inventory-cosmos-query-agent/eval.yaml
使ったバージョンは azd 1.34.1、拡張機能 azure.ai.agents 1.0.0-beta.16 です。
2026 年 11 月時点の公式のクイックスタートでは、この eval.yaml は使えず、azd ai eval で作った evals/azure.eval.yaml を --eval-config で渡す方式に変わっています。
今回は完了まで 39 分 27 秒かかりました。
完了すると、次のように候補ごとの score が表示されます。
Results: Candidate Score Eval Strategy ──────────────────── ──────── ──── ──────── baseline 0.561 View - candidate_1 0.543 View system_prompt candidate_2 0.721 View tools candidate_3 ★ 0.800 View system_prompt, tools candidate_4 0.767 View system_prompt
score は validation 用データ 15 問の平均です。
Strategy はその候補で書き換えられた対象です(system_prompt はプロンプト、tools は Tool の説明)。
★ は score が最も高い候補です。
今回の実行にかかったモデルの料金は約 187 円(約 1.17 USD)で、このうち 8 割以上が評価モデルの料金でした。
このほかに Hosted Agent の実行環境の料金がかかり、請求額からの推定で、およそ 100〜110 円でした。
CLI の表示は候補ごとの score だけですが、Python SDK を使うと、質問ごとの点数や理由文、エージェントの応答(Tool の呼び出しと結果を含む)まで取り出せます。
次の章の比較はこの方法で取り出した結果をもとにしています。
結果を取り出すコード(クリックで展開)
import json import os from pathlib import Path from azure.ai.projects import AIProjectClient from azure.core.rest import HttpRequest from azure.identity import DefaultAzureCredential job_id = "<job-id>" out_dir = Path("results") out_dir.mkdir(exist_ok=True) with AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=DefaultAzureCredential()) as client: # ジョブ全体(状態、警告、候補ごとの score、トークンの使用量など) job = client.beta.agents.get_optimization_job(job_id) print("job status:", job["status"]) # 候補ごとの結果(質問ごとの score の内訳、理由文、応答) for candidate in job["result"]["candidates"]: candidate_id = candidate["candidate_id"] request = HttpRequest( "GET", f"/agent_optimization_jobs/{job_id}/candidates/{candidate_id}/results", params={"api-version": "v1"}, ) response = client.send_request(request) response.raise_for_status() results = response.json() (out_dir / f"{candidate_id}.json").write_text(json.dumps(results, ensure_ascii=False, indent=1)) print(f'{results["name"]:12s} avgScore={results["avgScore"]:.4f} tasks={len(results["taskScores"])}')
8. 結果を確認し、候補を選ぶ
baseline(最適化前)と、最も score の高かった candidate_3(最適化後)を比べ、良くなった点と書き換えられた内容を確認します。
8.1 質問ごとの変化
質問ごとの score は評価器の点数(1〜5 点を 0〜1 に換算)と、評価モデルが 0〜1 で採点した各 criteria の点数の平均です。
validation 用データの 15 問のうち、8 問で score が上がり、4 問は変わらず、3 問で下がりました。
Tool が必要な 12 問では、最適化後はすべて Tool を呼んでいました(最適化前は 2 問で呼んでいませんでした)。
変化が大きかった 2 問を紹介します。
上がった質問:「名古屋倉庫で 2026-09-21(UTC)以降に更新された商品は?」
| 最適化前 | 最適化後 | |
|---|---|---|
| Tool での照会 | なし | 1 回目: SELECT DISTINCT c.warehouseId FROM c で倉庫 ID の一覧を取得2 回目: nagoya-01 と日付を条件に照会 |
| 回答 | 「名古屋倉庫の warehouseId を教えてください」と聞き返した |
メカニカルキーボード、Bluetooth スピーカーの 2 件を回答した(正解) |
| score | 0.000 | 1.000 |
最適化前は倉庫名で質問されると、Tool を呼ばずに倉庫 ID を聞き返していましたが、最適化後は Tool で倉庫 ID の一覧を取ってから照会するようになりました。
最適化用データに出てこない名古屋倉庫でも、同じ手順で答えています。
下がった質問:「在庫が多い商品を教えて」
| 最適化前 | 最適化後 | |
|---|---|---|
| Tool での照会 | なし | 在庫数の多い順に、上位 10 件を照会 |
| 回答 | 「上位何件として調べますか?」と基準を聞き返した | 聞き返さずに、上位 10 件を一覧で回答した |
| score | 0.688(評価器 0.75、criteria 0.625) | 0.125(評価器 0.25、criteria 0.000) |
この質問では「多い」の基準も対象の倉庫も決まっていないため、参照回答では基準と倉庫を聞き返すことを正解にしています。
最適化前は基準だけを聞き返し、倉庫を聞き返さなかったため、満点になりませんでした。
最適化後は聞き返さずに、Tool で取得した一覧を答えるようになり、score が下がりました。
8.2 書き換えられた内容
candidate_3 では、プロンプトと Tool の説明が書き換えられていました(Skill は変更なし)。
8.1 の 2 問に関わる変更を紹介します。
Tool の説明の変更
query_cosmos_items の引数 query の説明に、倉庫名で指定されたときの照会の仕方が加わりました。
引数 query の説明(最適化後は抜粋) |
|
|---|---|
| 最適化前 | One SELECT statement. Select only needed fields and represent user-provided values with @parameters. (1 つの SELECT 文。必要な項目だけを選び、ユーザーが指定した値は @parameters で表す) |
| 最適化後 | When the user supplies a human-readable warehouse name, use a discovery query first if the stored identifier may differ from the display name. (ユーザーが倉庫名で指定したときは、保存されている ID と表示名が違う可能性があれば、先に倉庫を調べる照会をする) |
引数の型や必須項目は変わっていません。
プロンプトの変更
プロンプトは約 340 字から約 1,700 字に増え、次のような項目が加わりました(抜粋)。
【倉庫名・倉庫IDの扱い】 - ユーザーが「東京倉庫」のような人間向け名称を述べた場合、それをいきなり `warehouseId` とみなして照会してはいけません。 - まず、データ取得で倉庫の対応関係を特定してください。取得で特定できるなら、ユーザーに `warehouseId` を聞き返してはいけません。 - このタスクでは、重要な既知対応として「東京倉庫」は `warehouseId = tokyo-01` に対応します。したがって「東京倉庫で…」という質問では、必要に応じて `tokyo-01` を用いて在庫照会してください。 【回答ルール】 - 確認質問は本当に必要なときだけ 1 つに限定してください。倉庫名から取得で解決できる場合は質問せず処理を続けてください。
この変更から、次のことが読み取れます。
- 【倉庫名・倉庫IDの扱い】の 1 つ目と 2 つ目は、名古屋倉庫の質問で見た「倉庫 ID を調べてから照会する」動きにつながる、どの倉庫にも当てはまる変更です。
- 3 つ目の「東京倉庫は
tokyo-01」は、最適化用データの答えがそのまま書き込まれたもので、最適化用データへの過剰適合です。validation 用データの「2026-09-21(UTC)に更新された東京倉庫の商品を教えて」では、最適化後のエージェントは倉庫 ID を調べずに、最初からtokyo-01で照会していました。この質問では criteria のwarehouse_discoveryが 0 点になり、score は 0.500 でした(最適化前は 0.458)。倉庫 ID が変わると誤った照会になるので、この部分は適用する前に取り除く必要があります。 - 【回答ルール】の「確認質問は本当に必要なときだけ」は、「在庫が多い商品を教えて」で聞き返さなくなったことに影響した可能性があります。
8.3 候補を適用する
実行結果の最後には、候補を適用するためのコマンドが表示されます。
Apply the best candidate locally, then deploy:
azd ai agent optimize apply --candidate cand_…_0003
azd deploy
apply で候補の内容をローカルの設定に反映し、azd deploy でデプロイすると、Azure 上のエージェントに反映されます。
★ 以外の候補を使いたい場合は、--candidate に渡す ID を変えます。
候補を適用してデプロイするまで、稼働中のエージェントは変わりません。
9. まとめ
今回は Tool で Cosmos DB を照会する在庫エージェントを、Agent Optimizer で最適化しました。
- Tool の呼び出しと結果まで採点する評価器を使い、score は 0.561 から 0.800 に上がりました。
- 効いたのは、Tool の説明に加わった「倉庫名で指定されたら、先に倉庫 ID を調べる」という変更でした。
- 一方で、曖昧な質問で聞き返さなくなる、最適化用データの答えがプロンプトに書き込まれる、という副作用も出ました。候補は書き換えられた内容を読んでから適用する必要があります。
- 実行時間は約 40 分、費用はモデルの料金が約 187 円、実行環境を含めると推定で約 300 円でした。