2026年5月5日に確認された Azure SDK documentation update: Add GenAI main-agent attribution processor は、Azure SDK for Python の Azure Monitor OpenTelemetry 関連パッケージで、マルチエージェント型の生成AIアプリを追跡しやすくするための更新です。結論から言うと、対応が必要なのは Azure Monitor OpenTelemetry Exporter / Distro を使って、AI Agent や複数エージェントの処理を Application Insights などへ送っている開発・運用チーム です。
今回の変更は、アプリの業務ロジックを変えるものではありません。ただし、テレメトリに microsoft.gen_ai.main_agent.* 属性が付与・伝播されるため、監視クエリ、ダッシュボード、ログ分析、サンプリング後の検証方法には影響する可能性があります。2026年5月6日時点で PR #46700 は Open、関連する Distro 側 PR #46703 は Draft として確認でき、該当 CHANGELOG も Unreleased 扱いです。正式リリース前の情報として、導入前にパッケージの実リリース状況を必ず確認してください。(GitHub)
Azure SDKのGenAI main-agent attribution processorで何が変わるのか
今回の更新の中心は、マルチエージェントシステムで「どのメインエージェントが処理全体を起点にしているか」を、スパンとログへ伝播する processor の追加です。PR #46700 の説明では、microsoft.gen_ai.main_agent.* 属性を multi-agent systems の spans と log records に伝播する processor を追加するとされています。(GitHub)
従来のAIエージェント監視では、サブエージェント、ツール呼び出し、モデル呼び出し、外部API呼び出しがそれぞれ別のスパンとして記録されても、「この一連の処理は、どのメインエージェントの仕事なのか」が追いにくいケースがありました。
今回の processor が狙っているのは、この追跡性の改善です。たとえば次のようなワークフローで効果が出ます。
- 受付エージェントが問い合わせを分類する
- 調査エージェントが社内ナレッジを検索する
- 要約エージェントが回答案を作る
- 承認エージェントが最終応答を制御する
このような構成では、個々のエージェント名だけでは処理全体の責任範囲が分かりにくくなります。microsoft.gen_ai.main_agent.name や microsoft.gen_ai.main_agent.id が伝播されると、サブエージェントやログを横断して「メインエージェント単位」で分析しやすくなります。
追加される主な属性
PR ブランチの constants では、main-agent attribution 用に次の属性マッピングが定義されています。親スパン側に microsoft.gen_ai.main_agent.* があればそれを使い、なければ gen_ai.agent.* や gen_ai.conversation.id から補完する形です。(GitHub)
| 追加・伝播される属性 | 主な意味 | 確認すべきポイント |
|---|---|---|
microsoft.gen_ai.main_agent.name | メインエージェントの表示名 | 名前変更で集計がぶれないよう、IDと併用する |
microsoft.gen_ai.main_agent.id | メインエージェントの識別子 | ダッシュボードやKQL集計では優先的に使う |
microsoft.gen_ai.main_agent.version | エージェントのバージョン | リリース前後の品質比較に使える |
microsoft.gen_ai.main_agent.conversation_id | 会話・対話の識別子 | セッション分析や問い合わせ単位の追跡に役立つ |
OpenTelemetry の GenAI semantic conventions でも、gen_ai.agent.id、gen_ai.agent.name、gen_ai.agent.version などの属性が定義されています。ただし、これらの属性は発展中の領域として扱われているため、監視ルールを作るときは属性名の変更や拡張に備えておくのが安全です。(OpenTelemetry)
Span processorとLog record processorの役割
今回追加される processor は、大きく分けて2種類です。
| processor | 役割 | 実務での効果 |
|---|---|---|
| Span processor | 親スパンから子スパンへ main-agent 属性をコピーする | サブエージェントやツール呼び出しを、メインエージェント単位で追跡しやすくなる |
| Log record processor | 現在のスパンにある main-agent 属性をログレコードへコピーする | ログ検索でも、どのメインエージェントに関係するログか分かりやすくなる |
実装上は、gen_ai.operation.name が invoke_agent のスパンに対して、main-agent 属性がまだ存在しない場合に、スパン自身の gen_ai.agent.* 属性から self-attribution を行う処理も含まれています。ログ側では、現在のスパンにある microsoft.gen_ai.main_agent.* 属性をログレコードへコピーし、既存のログ属性は上書きしないように処理されています。(GitHub)
この「上書きしない」という挙動は重要です。アプリ側で明示的にログ属性を付けている場合、その値を processor が勝手に置き換える設計ではありません。既存の監視設計を壊しにくい一方で、誤った属性をアプリ側で先に設定していると、その誤りが残る可能性があります。
影響範囲：対応が必要な人、様子見でよい人
今回の Azure SDK documentation update は、Azure SDK 全体というより、Azure SDK for Python リポジトリ内の Azure Monitor OpenTelemetry Exporter / Distro に関する変更として見るのが現実的です。
| 利用状況 | 影響度 | 対応方針 |
|---|---|---|
| Azure Monitor OpenTelemetry DistroでAI Agentを監視している | 高 | リリース後、ステージングで属性伝播を確認する |
azure-monitor-opentelemetry-exporter を直接使っている | 中 | processor が自動適用されるか、Distro経由が必要かを確認する |
| Application InsightsでGenAIログ・トレースを分析している | 中 | KQL、ブック、アラート条件に新属性を追加できるか確認する |
| 単一エージェントのみで、サブエージェントやツール連携がない | 低 | すぐに変更しなくてもよいが、将来の拡張に備えて属性設計を見直す |
| Azure Monitor OpenTelemetryを使っていない | 低 | 直接の対応は不要 |
関連する Distro 側 PR #46703 では、Azure Monitor Distro の tracing と logging のセットアップ時に、新しい GenAI main-agent attribution processor を最初に登録する変更が示されています。つまり、Distro 側の変更がリリースされると、configure_azure_monitor() を使う構成では自動的に有効化される可能性があります。(GitHub)
一方で、PR #46700 には「exporter needs to be released first」とあるため、Distro 側だけを見て判断しないことが重要です。Exporter と Distro の両方のバージョンが対応しているかを確認してください。(GitHub)
移行前に確認すべきチェックポイント
まず確認すべきなのは、現在使っているパッケージとPythonバージョンです。該当ブランチの exporter CHANGELOG では、1.0.0b52 (Unreleased) に GenAI main-agent attribution processor の追加が記載されています。同じ CHANGELOG には、Python 3.9 サポート終了と Python 3.10+ 対応も Breaking Changes として記載されています。(GitHub)
本番環境でアップデートする前に、次を確認してください。
python --version
pip show azure-monitor-opentelemetry
pip show azure-monitor-opentelemetry-exporter確認観点は次のとおりです。
| 確認項目 | 見るべき内容 | 判断基準 |
|---|---|---|
| Pythonバージョン | Python 3.9以下を使っていないか | exporter更新時にPython 3.10+が必要になる可能性がある |
| Distroのバージョン | azure-monitor-opentelemetry のリリース番号 | Distro側PR #46703 の反映有無を見る |
| Exporterのバージョン | azure-monitor-opentelemetry-exporter のリリース番号 | processor実装が含まれるかを見る |
| 監視クエリ | agent名やoperation名だけで絞っていないか | main-agent属性を使った集計へ拡張する |
| ログ設計 | カスタム属性を上書き前提にしていないか | processorは既存ログ属性を上書きしない点に注意する |
設定確認：Distro利用時はconfigure_azure_monitorの周辺を見る
Azure Monitor OpenTelemetry Distro for Python では、configure_azure_monitor() を使って Azure Monitor へのテレメトリ送信を構成できます。Microsoft Learn の設定ガイドでも、Python では接続文字列を環境変数または configure_azure_monitor() で指定する方法が示されています。(Microsoft Learn)
基本形は次のようになります。
from azure.monitor.opentelemetry import configure_azure_monitor
configure_azure_monitor(
connection_string="<YOUR-CONNECTION-STRING>",
)今回の更新が正式にリリースされた後は、この初期化処理そのものを大きく変えるというより、次の確認が重要です。
disable_tracing=Trueにしていないかdisable_logging=Trueにしていないか- AI Agent側で
gen_ai.agent.idやgen_ai.agent.nameが正しく設定されているか - サブエージェントの処理が同一トレース上でつながっているか
- Application Insights 側で新しい属性が検索・集計できるか
特に、アプリ側に gen_ai.agent.* が入っていなければ、processor が main-agent 情報を補完する材料が不足します。「processorを入れれば自動で全エージェントが識別される」と考えるのは危険です。エージェント名、ID、バージョン、会話IDをどの層で付けるかを、アプリ設計として決めておきましょう。
Application Insightsで確認する例
リリース後に属性が送信されているか確認する場合は、Application Insights のトランザクション検索やログ検索で microsoft.gen_ai.main_agent を探します。KQLを使う場合は、テレメトリの種類に応じて traces、requests、dependencies などを見ることになります。
例として、ログ側に属性が入っているかを確認するクエリは次のように考えられます。
traces
| where tostring(customDimensions["microsoft.gen_ai.main_agent.name"]) != ""
| project
timestamp,
message,
mainAgentName = customDimensions["microsoft.gen_ai.main_agent.name"],
mainAgentId = customDimensions["microsoft.gen_ai.main_agent.id"],
operation_Id
| order by timestamp desc依存関係やリクエストも見る場合は、対象テーブルを変えて同じ属性を確認します。
dependencies
| where tostring(customDimensions["microsoft.gen_ai.main_agent.id"]) != ""
| summarize count() by tostring(customDimensions["microsoft.gen_ai.main_agent.id"])この段階で見るべきなのは、単に属性が存在するかどうかではありません。次の3点を確認すると、実運用で使える監視に近づきます。
| 確認内容 | よくある問題 | 対処 |
|---|---|---|
| mainAgentId が空でないか | agent nameだけ設定され、idがない | エージェント作成時に安定したIDを付ける |
| サブエージェントのログにも属性があるか | トレースコンテキストが切れている | 非同期処理、キュー、外部呼び出しのコンテキスト伝播を確認する |
| version別に集計できるか | バージョン未設定でリリース比較できない | デプロイ時のエージェントバージョンを属性に含める |
失敗しやすいポイント
main_agent.nameだけで監視ルールを作る
name は人間が読みやすい一方で、変更されやすい値です。「Customer Support Agent」を「Support Agent v2」に変えただけで、ダッシュボードの集計が分断される可能性があります。
本番監視では、可能な限り microsoft.gen_ai.main_agent.id を主キーにし、表示用に name を併用してください。
正式リリース前に本番前提で実装を固定する
2026年5月6日時点では、PR #46700 は Open、Distro 側 PR #46703 は Draft です。CHANGELOG上の対象バージョンも Unreleased のため、内部クラス名や登録方法を本番コードへ直接固定するのは避けるべきです。(GitHub)
特に _GenAIMainAgentSpanProcessor のようにアンダースコアで始まるクラスは、Pythonでは内部実装として扱われるのが一般的です。正式な公開APIとして案内されるまでは、Distroのリリースノートやドキュメントに沿って利用するのが安全です。
ログだけを見て「反映されていない」と判断する
Span processor と Log record processor は役割が異なります。ログに属性が見えない場合でも、スパン側には入っている可能性があります。
確認時は、ログ、リクエスト、依存関係、トレースを分けて見てください。特に disable_logging や logger の設定によっては、ログパイプライン自体が期待通りに動いていない場合があります。
サンプリングの影響を見落とす
Azure Monitor OpenTelemetry Distro では、バージョンによって既定のサンプリング挙動が変わることがあります。過去の CHANGELOG では、Distro 1.8.6 で既定のサンプリングが RateLimitedSampler に変わったことが記載されています。属性の伝播確認をするときは、サンプリングにより対象スパンが送信されていない可能性も考慮してください。(GitHub)
実務での対応手順
今回の更新に対しては、いきなり本番に入れるのではなく、次の順序で確認すると安全です。
| 手順 | 作業 | 成功条件 |
|---|---|---|
| 1 | 現行のPython、Distro、Exporterのバージョンを確認する | アップデート時の互換性リスクが分かる |
| 2 | リリースノートで #46700 / #46703 の反映を確認する | Unreleasedではなく、実際のパッケージに含まれている |
| 3 | ステージング環境でAI Agent処理を実行する | main-agent属性がスパンに付く |
| 4 | ログにも同じ属性が付くか確認する | 障害調査時にログからメインエージェントを追える |
| 5 | KQL、Workbook、アラートを更新する | agent id、version、conversation_idで分析できる |
| 6 | 本番リリース後に属性欠落を監視する | コンテキスト切れや設定漏れを早期に検出できる |
実務上は、まず main_agent.id と main_agent.version を使った集計を追加するのがおすすめです。これにより、「特定のエージェントの新バージョンだけ失敗率が高い」「ある会話IDに関連するサブエージェント呼び出しだけ遅い」といった分析がしやすくなります。
まとめ：まずはバージョン確認と属性設計から始める
Azure SDK documentation update: Add GenAI main-agent attribution processor は、マルチエージェント型GenAIアプリの監視を実用的にするための重要な更新です。ポイントは、microsoft.gen_ai.main_agent.* 属性によって、スパンとログをメインエージェント単位で追跡しやすくなることです。
ただし、2026年5月6日時点では関連PRとCHANGELOGに Unreleased / Draft の要素が残っています。まずは使用中の azure-monitor-opentelemetry と azure-monitor-opentelemetry-exporter のバージョン、Pythonバージョン、AI Agent側の gen_ai.agent.* 属性設計を確認してください。
次に取るべき行動は明確です。ステージング環境でパッケージのリリース反映を確認し、microsoft.gen_ai.main_agent.id、name、version、conversation_id がスパンとログに出ているかを検証しましょう。その結果をもとに、Application Insights のKQL、Workbook、アラート条件をメインエージェント単位で見直すと、マルチエージェント運用時の調査スピードと品質改善につながります。
コメント