Azure REST API documentation update: Add Evaluation Suite CRUD API TypeSpec は、Microsoft Foundry の評価機能を REST API 仕様として扱うための重要な更新です。結論から言うと、Foundry の評価を SDK・CI/CD・自動テストで扱うチームは、evaluation_suites のバージョン管理、実行レスポンスの配列化、生成ジョブのプレビュー扱い、フィールド名の変更を確認する必要があります。なお、2026年5月5日時点の差分では PR はまだ Open の状態であり、正式リリース済み機能として断定せず、仕様追跡と移行準備を進めるのが現実的です。(GitHub)
Azure REST API documentation update: Add Evaluation Suite CRUD API TypeSpecで何が変わったか
今回の更新は、Azure REST API の仕様リポジトリに、Evaluation Suite を CRUD 操作・バージョン管理・実行・生成ジョブとして定義する TypeSpec を追加するものです。Azure REST API 仕様リポジトリは Microsoft Azure の REST API 仕様の主要なソースであり、ここでの変更は将来の OpenAPI、SDK、API リファレンス生成に影響する可能性があります。(GitHub)
| 確認項目 | 変更内容 | 実務上の影響 |
|---|---|---|
| Evaluation Suite のリソース化 | evaluation_suites リソースとして EvaluationSuiteVersion を定義 | 評価条件を再利用可能な成果物として扱いやすくなる |
| バージョン作成 | POST /evaluation_suites/{name}/versions を追加 | 作成時にバージョンを自動採番する前提で実装する必要がある |
| 評価実行 | POST /evaluation_suites/{name}:run を追加 | Suite に紐づく評価条件とデータセットで実行できる |
| 生成ジョブ | evaluation_suite_generation_jobs を追加 | プロンプト、エージェント、トレース、データセット、ファイルから Suite 生成を扱う |
| レスポンス構造 | 実行結果が results[] 配列を持つ形に変更 | 旧形式の単一オブジェクト前提のパーサーは修正が必要 |
| 命名変更 | suite_version から evaluation_suite_version などへ変更 | API クライアント、テスト、ログ集計のフィールド名を見直す |
この変更は「評価を1回だけ実行する」ためのAPI追加というより、評価条件、データセット、ターゲット、エバリュエーター、実行結果をひとまとまりの運用単位として管理するための仕様追加と見ると理解しやすくなります。
Evaluation Suiteとは何か
Evaluation Suite は、評価用データセット、エバリュエーター設定、しきい値、初期化パラメーターなどをまとめた再利用可能な名前付きアーティファクトです。仕様上は、バッチ評価、スケジュール評価、継続的評価、CI/CD 評価ゲートで使える評価条件の束として説明されています。(GitHub)
Microsoft Foundry の評価機能では、生成AIモデルやエージェントをテストデータセットに対して実行し、組み込みエバリュエーターやカスタムエバリュエーターで品質・安全性・性能を測定します。特にクラウド評価は、大規模テスト、CI/CD パイプラインへの統合、デプロイ前テストで使う場面が想定されています。(Microsoft Learn)
つまり、今回の API 仕様更新で注目すべき点は「評価がポータル操作だけでなく、REST API や SDK からより体系的に扱われる方向に進んでいること」です。AI エージェントや生成AIアプリを本番運用するチームほど、評価条件をコード化し、変更前後の品質を自動チェックする重要性が高まります。
追加された主なモデルとフィールド
中心になるモデルは EvaluationSuiteVersion です。display_name、subtype、dataset、testing_criteria、target、input_messages、evaluation_level などが定義され、name と version は読み取り用のリソース識別情報として扱われます。description と tags は作成・更新時に扱えるフィールドです。(GitHub)
| フィールド | 意味 | 確認ポイント |
|---|---|---|
display_name | 画面やレポート向けの表示名 | 一意である必要はないため、内部識別には name を使う |
subtype | Suite の種別 | 最新差分では default と benchmark が見える。古い benchmark_spec 前提の実装は見直す |
dataset | 評価用データセット参照 | version 省略時は最新扱いになるため、再現性が必要なら明示する |
testing_criteria | 評価基準の配列 | 1件以上が必須。空配列や未設定は避ける |
target | 評価対象 | azure_ai_agent、azure_ai_model、azure_ai_assistant などの対象を想定する |
input_messages | データセット行をターゲットへ渡す方法 | テンプレート型か item reference 型のどちらで入力を組み立てるか確認する |
evaluation_level | 既定の評価レベル | 実行時に上書きできるため、Suite 既定値と実行時指定を分けて管理する |
注意したいのは、PR 説明には EvaluationSuiteKind や EvaluationSuiteEvaluator といった名称への言及がありますが、2026年5月5日の最新コミット差分では EvaluationSuiteSubtype、testing_criteria、DatasetReference、EvaluationSuiteGenerationJob などの形で整理されています。仕様レビュー中の名称は変わる可能性があるため、実装では PR 説明文だけでなく、最新の TypeSpec と生成 OpenAPI を基準に確認してください。(GitHub)
CRUD APIと実行APIで確認すべき変更点
routes.tsp では、EvaluationSuites インターフェイスが VersionedOperations を拡張し、バージョン付きアセットのパターンで CRUD を扱う構成になっています。さらに agent_name クエリによるフィルター、バージョン自動採番用の POST /evaluation_suites/{name}/versions、Suite 実行用の POST /evaluation_suites/{name}:run が定義されています。(GitHub)
特に移行時に重要なのは、作成時に version をクライアント側で固定して送るのではなく、POST による自動採番を前提にする点です。name はリソース名、version は返却されるバージョンとして扱い、次回実行や監査ログでは返却値を保存する設計にしておくと、後から評価結果を追跡しやすくなります。
実行APIのリクエストは evaluation_name、evaluation_suite_version、evaluation_level を持ちます。旧差分では suite_version という名前が見えますが、5月5日のコミットで evaluation_suite_version に変更されています。ログ、JSON Schema、テストコード、データ変換処理に古いフィールド名が残っていないか確認しましょう。(GitHub)
実行レスポンスは単一結果ではなくresults[]で受ける
実行レスポンスは evaluation_suite_name、evaluation_suite_version、results を持つ EvaluationSuiteRunResponse として定義されています。results は現時点では単一要素配列と説明されていますが、将来的に複数実行をサポートする余地がある構造です。(GitHub)
旧形式のように次のような受け方をしている場合は危険です。
{
"eval_id": "eval_xxx",
"run_id": "run_xxx",
"status": "queued"
}今後は概念的に、次のような構造を前提に処理する必要があります。
{
"evaluation_suite_name": "checkout-agent-suite",
"evaluation_suite_version": "3",
"results": [
{
"eval_id": "eval_xxx",
"run_id": "run_xxx",
"status": "queued",
"created_at": 1777890000
}
]
}実装では results[0] を安易に固定参照するのではなく、配列をループ処理し、将来複数結果が返っても壊れない形にしておくのが安全です。
Evaluation Suite生成ジョブの追加ポイント
今回の更新では、Evaluation Suite を直接作るだけでなく、生成ジョブとして作成・取得・一覧・キャンセル・削除する API も定義されています。ルートは evaluation_suite_generation_jobs で、create、get、list、cancel、delete が追加されています。これらは evaluations_v1_preview のプレビュー機能として扱われる設定が入っています。(GitHub)
生成ジョブの入力では、Suite 名、ソース素材、生成モデル、カテゴリ、初期化パラメーター、データ生成オプションを指定できます。ソース種別は prompt、agent、traces、dataset、file が定義され、data_generation_options.type は省略可能で、省略時は simple_qna が既定になる説明です。(GitHub)
| 生成ジョブの項目 | 実務での使いどころ |
|---|---|
prompt | 要件文や評価観点から Suite を作りたい場合 |
agent | 既存エージェントの指示やメタデータを元に評価条件を作る場合 |
traces | Application Insights などの会話トレースを元に評価を設計する場合 |
dataset | 既存データセットからテスト条件や評価データを生成する場合 |
file | Azure OpenAI のファイル入力を元に生成する場合 |
プレビュー扱いの機能は、SLA なしで提供され、運用環境ワークロードには推奨されない場合があります。Microsoft Learn でも、プレビュー項目は機能制限や未対応の可能性があると明記されています。したがって、生成ジョブを本番の品質ゲートに組み込む場合は、正式な可用性、利用条件、SDK の公開状態を確認してから段階的に導入するのが安全です。(Microsoft Learn)
誰が対応すべきか
この更新の影響は、Azure REST API を直接呼び出す開発者だけに限られません。TypeSpec は API のデータモデルや操作を定義し、コード、ドキュメント、OpenAPI などの成果物生成につながるため、SDK 利用者や自動テスト担当にも影響が及ぶ可能性があります。(Typespec)
| 対象者 | 対応優先度 | 確認すべきこと |
|---|---|---|
| Foundry 評価を REST API で自動化しているチーム | 高 | フィールド名、レスポンス構造、プレビュー機能ヘッダー |
| SDK 生成・SDK ラッパーを管理するチーム | 高 | TypeSpec から生成されるメソッド名、モデル名、サブクライアント配置 |
| CI/CD で AI 評価ゲートを作るチーム | 高 | Suite のバージョン固定、データセット固定、結果配列の扱い |
| ポータル中心で評価している利用者 | 中 | 将来のSDK化・自動化に備えた概念理解 |
| ドキュメント・運用手順の管理者 | 中 | 「評価定義」「評価実行」「生成ジョブ」の用語整理 |
| Evaluation Suite を使っていないチーム | 低 | すぐの移行は不要。ただし Foundry 評価の導入予定があれば把握しておく |
特に、エージェントの品質保証を CI/CD に組み込むチームは早めに確認すべきです。Microsoft Foundry の可観測性では、評価や監視、トレースを通じて品質・安全性・運用状態を測る考え方が示されており、継続的評価やスケジュール評価は本番後の品質維持にも関係します。(Microsoft Learn)
移行や設定確認で見るべきチェックリスト
まず、既存の評価関連コードで suite_version、suite_name、benchmark_spec、id を参照していないか確認します。5月5日の変更では suite_version は evaluation_suite_version に、レスポンス上の suite_name / suite_version は evaluation_suite_name / evaluation_suite_version に整理され、EvaluationSuiteVersion から id が削除された流れが見えます。(GitHub)
次に、評価結果の処理を results[] 前提に変更します。ダッシュボードやログ連携で eval_id と run_id をトップレベルから直接取り出している場合、今後のスキーマでは取りこぼしやエラーにつながります。
データセット参照では、version を省略すると最新バージョン解決になる説明があります。検証やCI/CDでは、昨日と今日で評価データが変わると比較が難しくなります。再現性を重視するテストでは、データセット名だけでなくバージョンも保存してください。(GitHub)
生成ジョブを使う場合は、generation_model、category、data_generation_options を明示的に管理します。type は省略可能で simple_qna が既定になる説明ですが、安全性評価、トレース由来評価、ツール利用評価などでは、既定値に任せるより目的に合った生成タイプを指定した方がレビューしやすくなります。(GitHub)
実装前に確認する順番
- PR の最新コミットと対象ブランチを確認する
- 生成された OpenAPI と SDK の公開状態を確認する
- 既存コードのフィールド名を検索する
results[]前提でレスポンス処理を書き換える- データセット名とバージョンの保存方針を決める
- プレビュー機能ヘッダーや SDK の
allow_preview相当の設定を確認する - CI/CD では Suite バージョン、評価レベル、しきい値を明示する
- 本番反映前に小さな評価 Suite で疎通テストを行う
よくある失敗と回避策
| 失敗しやすいポイント | 起きる問題 | 回避策 |
|---|---|---|
| PR 説明だけを見て実装する | 最新コミットで名称や構造が変わっている可能性がある | TypeSpec と生成 OpenAPI を基準にする |
suite_version を使い続ける | リクエストが通らない、または将来の SDK 型と合わない | evaluation_suite_version に更新する |
| 実行レスポンスを単一オブジェクトとして処理する | results[] 化でパースエラーになる | 配列処理に変更する |
| データセットバージョンを省略する | 評価の再現性が落ちる | CI/CD では明示的に固定する |
testing_criteria を空にする | Suite として成立しない | 最低1つの評価基準を入れる |
| プレビュー設定を確認しない | API 呼び出しや SDK 呼び出しが失敗する | evaluations_v1_preview 相当の opt-in を確認する |
id に依存した管理をする | EvaluationSuiteVersion から削除された差分と合わない | name、version、返却された実行IDで管理する |
この更新は、単に API エンドポイントが増えるだけではなく、評価を「継続的に運用するための単位」として整備する意味があります。AI エージェント評価では、タスク完了、タスク準拠、意図解決、ツール呼び出し精度など、用途ごとに入力やパラメーターが異なるため、Suite 化によって評価基準を統一しやすくなります。(Microsoft Learn)
実務での活用シーン
最も分かりやすい活用シーンは、AI エージェントのリリース前チェックです。たとえば問い合わせ対応エージェントを更新する場合、過去の代表的な問い合わせデータセットを Suite に紐づけ、回答品質、安全性、ツール呼び出し精度を実行します。合格ラインを下回った場合は、デプロイを止める品質ゲートにできます。
次に、継続的評価です。運用中のトレースやサンプリングされた会話を使い、定期的に Suite を実行します。これにより、モデル更新、プロンプト変更、ツール仕様変更による品質低下を早期に検知できます。
さらに、ベンチマーク評価にも使えます。subtype に benchmark が整理されているため、標準データセットや社内基準データに対してモデルやエージェントの性能比較を行う運用と相性が良いです。ただし、PR はまだレビュー中のため、最終的な名称や SDK での見え方は正式な仕様反映後に再確認してください。(GitHub)
次に取るべき行動
まず、自社のコードベースで評価関連の API 呼び出し、SDK ラッパー、JSON パーサー、CI/CD 設定を検索してください。suite_version、suite_name、benchmark_spec、eval_id のトップレベル参照、id 依存が見つかった場合は、今回の仕様変更に合わせた修正候補として洗い出します。
次に、小さな Evaluation Suite を想定したテスト設計を作ります。データセット名、データセットバージョン、評価基準、ターゲット、入力メッセージ、評価レベル、期待する結果構造を1枚の設計メモにまとめるだけでも、SDK や API が正式に使える段階で移行が速くなります。
最後に、PR #42424 の状態と生成 OpenAPI、SDK の公開状況を継続確認してください。現時点では Open の PR であり、仕様名やモデル構造が変わる可能性があります。今すぐ本番実装へ固定するのではなく、変更点を把握し、既存コードへの影響を先に潰しておくことが、Azure REST API の Evaluation Suite 対応で最も安全な進め方です。(GitHub)
コメント