2026年5月2日更新として確認したAzure SDKの「Agent target traces samples」で最初に押さえるべき結論は、Azure AI Projectsの評価サンプルが、Application Insightsに蓄積されたエージェントトレースをより実務向けに評価できる形へ整理されたという点です。特に、sample_evaluations_builtin_with_traces.pyをコピーして検証・CI/CD・品質評価に使っているチームは、実行モード、環境変数、data_mapping、data_sourceの指定を見直すべきです。
今回の変更は、アプリケーション本体の全利用者に一律で影響するアップデートではありません。影響が大きいのは、Azure SDK for PythonのAzure AI Projects評価サンプルを使い、Agentの応答品質やタスク遵守性をApplication Insightsのトレースから評価している開発者・MLOps担当者・QA担当者です。Pull Request #46670はGitHub上では2026年5月1日にfeature/azure-ai-projects/2.2.0ブランチへマージされており、主に評価サンプル配下のPythonファイルが変更されています。(GitHub)
Azure SDKのAgent target traces samples更新で何が変わったのか
今回の中心は、sdk/ai/azure-ai-projects/samples/evaluations/sample_evaluations_builtin_with_traces.pyです。このサンプルは、Azure AI Evaluationsを使って、Azure Application Insightsに保存されたAgent tracesを評価するためのものです。PRの差分では、このファイルだけで226行規模の変更があり、さらに音声・画像関連の評価サンプルにも小規模な整理が入っています。(GitHub)
実務上の変更点は、次の4つに分けると理解しやすくなります。
| 変更点 | これまでの利用者が見るべきポイント | 対応の優先度 |
|---|---|---|
| トレース評価の実行モードが3種類に整理 | 既存の「Application Insightsからtrace IDを取って評価する」流れに加え、--agent-idと--trace-idsで評価対象を指定できる | 高 |
data_mappingが{{sample.*}}形式に変更 | 旧サンプルをコピーしたコードで{{query}}や{{response}}を使っている場合、評価入力が合わない可能性がある | 高 |
data_sourceの指定がazure_ai_traces中心に整理 | 旧来のazure_ai_traces_preview相当の書き方を使っている場合は確認が必要 | 中 |
--lookback-hours、--max-traces、--no-cleanupが追加 | CI/CDや検証時に評価範囲・後片付けを制御しやすくなった | 中 |
新しいサンプルの説明では、トレース評価は「デフォルトモード」「Agent IDモード」「Trace IDモード」の3種類をサポートしています。デフォルトモードはApplication Insightsをクライアント側で検索し、--agent-idはAgent IDを評価サービスへ渡し、--trace-idsは明示したトレースIDを評価対象にします。(GitHub)
影響を受ける人、受けにくい人
このAzure SDK documentation updateは、Azure SDK全体の利用者に対する破壊的変更として見るより、Azure AI Projectsの評価サンプルを実務に取り込んでいるチーム向けの更新として捉えるのが適切です。
対応すべき人
次のいずれかに当てはまる場合は、今回の変更を確認してください。
sample_evaluations_builtin_with_traces.pyをローカルにコピーして使っている- Application InsightsのAgent tracesをもとに、エージェントの品質評価を行っている
- Azure AI Projectsの評価をCI/CDやリリース前検証に組み込んでいる
builtin.intent_resolutionやbuiltin.task_adherenceなど、Agent向けの組み込み評価器を使っている- 以前のサンプルにあった
azure_ai_traces_previewや古いdata_mappingを参照している
Azure AI Projectsの評価サンプルフォルダーでは、sample_evaluations_builtin_with_traces.pyは「Application Insights tracesに対する評価」を行うサンプルとして位置づけられており、接続済みのApplication Insightsが要件として示されています。(GitHub)
対応の優先度が低い人
一方で、次のような利用者は急いで対応する必要は低いでしょう。
- Azure Storage、Azure Key Vault、Azure Functionsなど、Azure AI Projects以外のSDKだけを使っている
- Agent tracesやApplication Insightsを使った評価を行っていない
- Azure AI Projectsのサンプルコードを参照していない
- 評価は独自のJSONL/CSVデータセットだけで行っている
ただし、Azure AI Projectsを今後使う予定がある場合は、旧サンプルを参考にせず、今回の新しい実行モードを前提に設計したほうが後戻りを減らせます。
3つの実行モードをどう使い分けるか
今回の更新で最も重要なのは、トレース評価の入り口が複数用意されたことです。どのモードを選ぶかで、必要な権限、再現性、CI/CDへの組み込みやすさが変わります。
| モード | 実行例 | 向いている場面 | 注意点 |
|---|---|---|---|
| デフォルトモード | python sample_evaluations_builtin_with_traces.py | Application Insightsから対象Agentのtrace IDを検索し、そのまま評価したい | Application InsightsのリソースIDとログ参照権限が必要 |
| Agent IDモード | python sample_evaluations_builtin_with_traces.py --agent-id "my-agent:1" | Agent IDを渡して、評価サービス側でトレース解決したい | 評価対象の範囲を--lookback-hoursと--max-tracesで制御する |
| Trace IDモード | python sample_evaluations_builtin_with_traces.py --trace-ids abc123 def456 | 特定のトレースを再評価し、結果を比較したい | あらかじめtrace IDを収集しておく必要がある |
デフォルトモードは、調査や初期検証に向いています。Application Insightsに入っているトレースを検索し、見つかったtrace IDを評価に渡す流れなので、どのトレースが評価されたかを把握しやすいからです。
Agent IDモードは、運用寄りの自動化に向いています。たとえば「直近24時間の特定Agentの応答を最大20件だけ評価する」といった使い方ができます。
python sample_evaluations_builtin_with_traces.py \
--agent-id "my-agent:1" \
--lookback-hours 24 \
--max-traces 20Trace IDモードは、再現性を重視する検証に向いています。リリース前後で同じトレースを評価し、評価結果の変化を比較したい場合に便利です。
python sample_evaluations_builtin_with_traces.py \
--trace-ids abc123 def456サンプルには--no-cleanupも追加されています。通常は評価オブジェクトを削除しますが、失敗時の調査やレポート確認をしたい場合は--no-cleanupを付けて残せます。(GitHub)
設定で確認すべき環境変数
今回のサンプルでは、少なくとも次の値を確認する必要があります。
| 項目 | 用途 | 確認ポイント |
|---|---|---|
FOUNDRY_PROJECT_ENDPOINT | Azure AI Projectのエンドポイント | FoundryプロジェクトのOverviewにあるプロジェクトURLを使う |
FOUNDRY_MODEL_NAME | 組み込み評価器で使うモデルデプロイ名 | 評価器が利用できるAzure OpenAIデプロイ名を指定する |
APPINSIGHTS_RESOURCE_ID | Application InsightsのリソースID | デフォルトモードでトレース検索に使う |
AGENT_ID | Application Insights内のAgent識別子 | gen_ai.agent.idとして記録された値と一致させる |
TRACE_LOOKBACK_HOURS | 検索対象期間 | 未指定時はサンプル上1時間が既定値 |
サンプルの説明では、APPINSIGHTS_RESOURCE_IDはデフォルトモードで必要であり、--agent-idまたは--trace-ids利用時は不要とされています。一方、掲載されているコードではAPPINSIGHTS_RESOURCE_IDとAGENT_IDをトップレベルでos.environ[...]として読み込んでいるため、ローカル実行時にはモードにかかわらず未設定でKeyErrorになる可能性があります。実務でそのまま使う場合は、いったん両方を設定するか、ローカルコピー側で必要なモードだけ読み込むように調整してから使うのが安全です。(GitHub)
data_mapping変更は見落としやすい
既存コードをコピーして使っている場合、最も見落としやすいのがdata_mappingです。
今回の差分では、評価器に渡す値が次のように変わっています。
data_mapping={
"query": "{{sample.query}}",
"response": "{{sample.response}}",
"tool_definitions": "{{sample.tool_definitions}}",
}以前のサンプルに近い実装を使っていて、{{query}}、{{response}}、{{tool_definitions}}のように書いている場合、評価サービス側が期待する入力とずれる可能性があります。PR差分でも、これらのプレースホルダーが{{sample.*}}形式へ変更されています。(GitHub)
特にtask_adherenceのようなAgent向け評価では、単なるテキスト応答だけでなく、ツール定義や構造化された実行情報が重要になります。Microsoft LearnのAgent target evaluationでも、Agentが実行時に生成する出力を{{sample.output_text}}や{{sample.output_items}}として参照する考え方が説明されています。(Microsoft Learn)
azure_ai_tracesへの整理で確認したいこと
今回のサンプルでは、Eval Run作成時のdata_sourceがモードに応じて組み立てられます。Agent IDモードでは次のような形です。
data_source = {
"type": "azure_ai_traces",
"agent_id": agent_id_for_server,
"lookback_hours": lookback_hours,
"max_traces": args.max_traces,
}Trace IDモードやデフォルトモードでは、明示的なtrace_idsを渡します。
data_source = {
"type": "azure_ai_traces",
"trace_ids": trace_ids,
"lookback_hours": lookback_hours,
}旧サンプル由来のコードでTracesPreviewEvalRunDataSourceやazure_ai_traces_previewに近い指定を使っている場合は、新しいサンプルに合わせて見直してください。PR差分では、古いTracesPreviewEvalRunDataSource(type="azure_ai_traces_preview", ...)相当の流れから、辞書ベースのtype: "azure_ai_traces"へ組み立てる流れに変更されています。(GitHub)
Azure AI Projects評価の全体像との関係
この更新は単独のサンプル修正ではなく、Azure AI Projectsにおける評価機能の流れに沿ったものです。Microsoft Learnでは、クラウド評価はテストデータセットを使った事前検証、CI/CDへの統合、大規模な自動テストに向くと説明されています。また、評価結果はFoundryプロジェクトに保存され、ポータルやSDKから確認でき、Application Insightsへ接続している場合は関連する観測データとも組み合わせられます。(Microsoft Learn)
Agent target evaluationでは、Foundry Agentへクエリを送信し、その応答をazure_ai_target_completionsとazure_ai_agentターゲットで評価する流れが示されています。今回のAgent tracesサンプルは、実行済みのAgentのトレースを評価対象にするため、事前検証だけでなく、運用後の品質確認や障害調査にも使いやすい位置づけです。(Microsoft Learn)
移行・設定確認の手順
既存の評価スクリプトやCI/CDに影響があるか確認するなら、次の順番で進めると失敗しにくくなります。
現在使っているサンプル由来コードを洗い出す
まず、リポジトリ内で次の文字列を検索します。
grep -R "sample_evaluations_builtin_with_traces" .
grep -R "azure_ai_traces_preview" .
grep -R "TracesPreviewEvalRunDataSource" .
grep -R "{{tool_definitions}}" .ヒットした場合は、今回の新しいサンプルとの差分確認が必要です。特に評価スクリプトをCI/CDで実行している場合は、サンプル更新を反映しないままSDKだけを更新すると、評価入力の形式だけが古く残ることがあります。
依存パッケージを確認する
サンプルでは、実行前に次のパッケージを入れる形になっています。
pip install "azure-ai-projects>=2.0.0" python-dotenv azure-monitor-query評価サンプルのREADMEでも、Azure AI Projects評価サンプルの前提としてazure-ai-projects>=2.0.0とpython-dotenvが示されています。トレース評価ではApplication Insightsを照会するため、azure-monitor-queryも忘れずに確認してください。(GitHub)
Application Insightsの接続を確認する
トレース評価では、Application InsightsにAgentのトレースが入っていることが前提です。Microsoft Learnでは、Foundryでトレースを表示するには、FoundryプロジェクトにApplication Insightsリソースを接続する手順が示されています。(Microsoft Learn)
実務では、次の3点を確認してください。
| 確認項目 | よくある失敗 |
|---|---|
| FoundryプロジェクトにApplication Insightsが接続されているか | トレースがFoundry側に表示されない |
| Agent実行時にトレースが送信されているか | Application Insightsに対象ログが存在しない |
gen_ai.agent.idが期待どおり記録されているか | AGENT_IDで検索してもtrace IDが見つからない |
トレースの中にはユーザー入力や応答内容が含まれる可能性があります。Microsoft Learnでも、生成AIコンテンツの記録を有効にする場合は個人データが含まれる可能性があると注意されています。評価用にトレースを扱う場合は、個人情報・機密情報・プロンプト内の秘密情報を保存しない設計にしてください。(Microsoft Learn)
小さなTrace IDモードから試す
移行確認では、最初から--agent-idで大量のトレースを評価するより、既知のtrace IDを2〜3件だけ指定するほうが安全です。
python sample_evaluations_builtin_with_traces.py \
--trace-ids <trace-id-1> <trace-id-2> \
--no-cleanup--no-cleanupを付けておけば、評価オブジェクトを残して結果を確認できます。結果確認後に手動で削除する運用にすれば、初回検証で「評価は走ったが、どの入力がどう評価されたか分からない」という状態を避けられます。
CI/CDでは評価範囲を必ず絞る
CI/CDに組み込む場合は、--agent-idと--lookback-hours、--max-tracesを組み合わせて評価対象を制限してください。
python sample_evaluations_builtin_with_traces.py \
--agent-id "customer-support-agent:1" \
--lookback-hours 6 \
--max-traces 10評価対象が多すぎると、実行時間やコスト、評価結果のばらつきが大きくなります。リリース前のスモーク評価なら、まずは「直近数時間・最大10〜20件」程度から始め、品質ゲートとして使う評価器としきい値を段階的に整えるのが現実的です。
よくある失敗と対策
trace IDが見つからない
デフォルトモードで「No trace IDs found」と出る場合は、AGENT_ID、検索期間、Application InsightsのリソースIDを順に確認します。サンプルではApplication Insightsのdependenciesテーブルから、customDimensions["gen_ai.agent.id"]を使って対象Agentを絞り込み、operation_Idをtrace IDとして取得する流れになっています。(GitHub)
検索期間が短すぎる場合は、次のように広げます。
python sample_evaluations_builtin_with_traces.py \
--lookback-hours 24ただし、期間を広げると対象トレースが増えます。Agent IDモードでは--max-tracesも併用してください。
環境変数名を混同する
Azure AI Projectsのドキュメントでは、一般的な例としてAZURE_AI_PROJECT_ENDPOINTやAZURE_AI_MODEL_DEPLOYMENT_NAMEが使われる場面があります。一方、今回のサンプルではFOUNDRY_PROJECT_ENDPOINTとFOUNDRY_MODEL_NAMEが使われています。Microsoft Learnのクラウド評価の導入例ではAZURE_AI_PROJECT_ENDPOINTとAZURE_AI_MODEL_DEPLOYMENT_NAMEが示され、今回のサンプル側ではFOUNDRY_PROJECT_ENDPOINTとFOUNDRY_MODEL_NAMEが使われています。(Microsoft Learn)
複数のサンプルを混ぜると、正しい値を設定しているのにスクリプト側が別名を読みに行くことがあります。.envを使う場合は、実行するサンプルに合わせて変数名を統一してください。
task_adherenceの入力が合わない
task_adherenceは、Agentがタスクをどの程度守ったかを見る評価器です。単純な文字列応答だけでなく、ツール呼び出しや構造化出力が必要になるケースがあります。Microsoft LearnのAgent target evaluationでは、{{sample.output_items}}はツール呼び出しを含む構造化JSON出力として説明されています。(Microsoft Learn)
今回のトレース評価サンプルでは、tool_definitionsを{{sample.tool_definitions}}として渡す形になっています。独自コードで評価器を増やす場合は、評価器ごとに必要な入力を確認し、data_mappingを機械的に流用しないことが重要です。
--no-cleanupを付けたまま運用する
--no-cleanupは調査には便利ですが、常用すると評価オブジェクトが残り続けます。検証環境では便利でも、本番に近い環境やCIでは不要なリソース管理の手間が増えます。
運用では次のように分けるとよいでしょう。
| 場面 | --no-cleanupの扱い |
|---|---|
| 初回検証 | 付ける。結果やレポートを確認する |
| 不具合調査 | 付ける。評価IDをログに残す |
| 定期実行・CI/CD | 原則付けない。必要な結果だけ別途保存する |
今回の更新を実務でどう活かすべきか
今回のAzure SDK Agent target traces samples更新は、単にサンプルの引数が増えたというより、Agent評価を「手元の検証」から「運用後のトレース評価」へつなげやすくする変更です。
特に活用しやすいのは、次のような場面です。
| 活用シーン | おすすめの使い方 |
|---|---|
| リリース前の品質確認 | Trace IDモードで固定トレースを評価し、前回結果と比較する |
| 本番運用後のサンプル監視 | Agent IDモードで直近数時間のトレースを少数評価する |
| 障害調査 | 問題が起きたtrace IDを指定し、意図解決やタスク遵守性を見る |
| プロンプト変更の影響確認 | 同じAgent・同じ評価器で、変更前後の評価結果を比較する |
| 評価基盤の整備 | --max-tracesや--lookback-hoursをCI/CDのパラメータにする |
ただし、クラウド評価や一部のAgent関連機能はプレビューとして扱われる場合があります。Microsoft Learnでも、プレビュー項目はSLAなしで提供され、本番ワークロードには推奨されないと説明されています。実運用に組み込む場合は、まず検証環境で評価ロジック、権限、コスト、保存されるトレース内容を確認してから段階的に導入してください。(Microsoft Learn)
まず確認すべきチェックリスト
最後に、今回の更新を受けて確認すべき項目を整理します。
| チェック | 確認内容 |
|---|---|
| サンプルの利用有無 | sample_evaluations_builtin_with_traces.pyをコピーしていないか |
| 実行モード | デフォルト、--agent-id、--trace-idsのどれを使うか |
| 環境変数 | FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL_NAME、APPINSIGHTS_RESOURCE_ID、AGENT_IDを確認したか |
data_mapping | {{sample.*}}形式に更新されているか |
data_source | azure_ai_traces前提で組み立てているか |
| 権限 | FoundryプロジェクトとApplication Insightsの参照権限があるか |
| トレース内容 | 個人情報や秘密情報を保存していないか |
| CI/CD | --lookback-hoursと--max-tracesで評価範囲を制限しているか |
| 後片付け | --no-cleanupを常用していないか |
今回の更新で最初にやるべきことは、既存の評価スクリプトを検索し、古いdata_mappingやazure_ai_traces_preview相当の指定が残っていないかを確認することです。そのうえで、まずはTrace IDモードで少数のトレースを評価し、問題がなければAgent IDモードをCI/CDや定期評価に組み込む流れが現実的です。
コメント