Azure SDKの「Azure SDK documentation update: adding agent tracing」でまず押さえるべき点は、Azure SDK全体の破壊的変更ではなく、主にAzure SDK for JavaScriptの@azure/ai-projectsでエージェント実行をOpenTelemetryで追跡しやすくするための変更案だということです。対象になるのは、JavaScript/TypeScriptでAzure AI ProjectsやMicrosoft Foundry agentsを使い、Application InsightsやOTLP対応基盤にトレースを送っている開発・運用チームです。指定ソースのPR #38363はドラフト状態で、mainブランチへのマージ前の変更として確認できるため、実運用では「今すぐ移行」ではなく、マージ状況・リリースノート・利用中パッケージのバージョン確認から始めるのが安全です。(GitHub)
Azure SDKのagent tracing追加で何が変わるのか
今回のadding agent tracingは、Azure SDKでAIエージェントの実行をより細かく観測するための変更です。Microsoft Foundryのドキュメントでも、ポータル側のサーバー側トレースに加えて、アプリケーションコード側のクライアント側トレースをOpenTelemetryで取得し、Azure Monitor Application Insights、コンソール、OTLP対応バックエンドへ送れることが説明されています。(Microsoft Learn)
実務上のポイントは、単に「ログが増える」ことではありません。エージェント作成、エージェント呼び出し、Responses API、ストリーミング応答、トークン使用量、エラー情報などを、トレースのspanや属性として扱えるようにする方向の変更です。
| 観点 | 変更内容 | 確認すべきこと |
|---|---|---|
| 対象パッケージ | Azure SDK for JavaScriptの@azure/ai-projects周辺 | 自社アプリが@azure/ai-projectsを使っているか |
| 対象処理 | エージェント作成、バージョン作成、Responses API呼び出しなど | どの処理を監視対象にしたいか |
| 観測基盤 | OpenTelemetry、Azure Monitor Application Insights、OTLP対応基盤 | 既存の監視基盤と接続できるか |
| データの扱い | メッセージ内容の記録は環境変数で制御する設計 | プロンプトや出力を保存してよいか |
| 対応時期 | PRはドラフト段階 | マージ後のリリース確認が必須 |
対応が必要な人、様子見でよい人
すべてのAzure SDK利用者が対応する必要はありません。対応優先度は、エージェント機能とOpenTelemetryをどれだけ使っているかで判断します。
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
JavaScript/TypeScriptで@azure/ai-projectsを使い、Foundry agentsを本番運用している | 高 | トレース設計、個人情報、コスト、監視画面への影響を事前確認すべき |
getOpenAIClient()やResponses API経由でエージェントを呼び出している | 高 | PRではresponses.createを追跡対象にする実装が含まれる |
| Azure Monitor Application InsightsでAIアプリを監視している | 中〜高 | 送信されるspan属性やデータ量の確認が必要 |
| PythonまたはC# SDKだけを使っている | 中 | Foundryのクライアント側トレース手順は別途存在するが、今回のPR自体はJSリポジトリの変更 |
| Storage、Key Vault、Cosmos DBなど一般的なAzure SDKのみ利用 | 低 | agent tracingの直接影響は限定的 |
| セキュリティ、監査、個人情報保護を担当している | 高 | メッセージ内容やツール引数がトレースに含まれる可能性を評価すべき |
具体的に追加されるトレース対象
エージェント作成系の操作にspanが付く
PRでは、createAgentVersionFromManifest、createVersion、createAgentFromManifest、createなどのエージェント作成・バージョン作成系操作に対して、tracingClient.withSpanを使ったspan作成が追加されています。spanには共通属性、エージェント属性、エージェントバージョン属性などを付与する形です。(GitHub)
これにより、エージェントを作った処理が「いつ」「どのエージェント名で」「どのエンドポイントに対して」「成功したか失敗したか」といった観点で追いやすくなります。
たとえば、複数チームが同じFoundryプロジェクトにエージェントを作成している場合、トレースを見れば「どの作成処理が遅いのか」「エラーが発生したのは作成時か呼び出し時か」を切り分けやすくなります。
OpenAI Responses API経由の呼び出しも追跡対象になる
PRでは、openaiClient.responses.createをラップし、GenAI tracingが有効な場合にエージェント呼び出しまたはチャット操作としてspanを作る処理が追加されています。agent_nameまたはagentがある場合はinvoke_agent、それ以外はchatとして扱う実装になっています。(GitHub)
さらに、非ストリーミング応答ではレスポンスID、モデル、トークン使用量、ステータスなどをspan属性やメトリックとして記録する処理が含まれています。(GitHub)
これは、AIエージェント運用ではかなり重要です。通常のHTTPログだけでは「エージェントがどのモデルを使い、どれだけトークンを消費し、どの会話IDに紐づいたか」を追うのが難しいためです。agent tracingが整うと、障害調査だけでなく、コスト分析や品質評価にも使いやすくなります。
ストリーミング応答のトレースも考慮されている
ストリーミング応答については、streamをラップし、response.completedイベントが来た時点で最終レスポンス属性を設定し、iteratorの完了・return・throwでspanを終了する処理が含まれています。(GitHub)
実務ではここが落とし穴です。ストリーミングを途中で破棄するアプリでは、spanの終了タイミングやメトリック記録が期待どおりにならない可能性があります。UI側でキャンセルボタンを実装している場合や、途中で接続が切れるチャットアプリでは、streamを最後まで読むだけでなく、キャンセル時の終了処理も確認してください。
traceparentとtracestateヘッダーの注入
getTracingFetchでは、GenAI tracingが有効な場合にtraceparentやtracestateなどのOpenTelemetryトレースコンテキストヘッダーを送信リクエストへ付与する処理が追加されています。これにより、アプリケーション側の処理とAzure側・外部観測基盤側の処理を同じトレースとしてつなぎやすくなります。(GitHub)
この変更の意味は、単体のログを増やすことではなく、分散トレースとして前後の処理をつなぐことです。
たとえば次のような流れを1つのトレースで追えるようになります。
| 処理 | 追跡できると便利なこと |
|---|---|
| Web APIがユーザー入力を受け取る | リクエスト全体の開始点が分かる |
| アプリがエージェントを呼び出す | どのエージェント呼び出しが遅いか分かる |
| エージェントがモデルやツールを使う | 遅延・失敗・トークン消費の原因を分解できる |
| アプリが応答を返す | 体感遅延と内部処理を関連付けられる |
有効化の考え方：PR案と既存のAzure SDK tracingを分けて理解する
PR案では、enableGenAITracing()、disableGenAITracing()、AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING環境変数による有効化が追加されています。また、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTでメッセージ内容の記録を制御する設計も確認できます。(GitHub)
ただし、レビューコメントでは、Azure SDKのcore-tracingは既定でno-opになり、ユーザーが@azure/opentelemetry-instrumentation-azure-sdkを設定すればOpenTelemetryベースのtracingが有効になるため、追加の有効化フラグは不要ではないか、という指摘もされています。(GitHub)
つまり、2026年5月5日前後の情報としては、次のように捉えるのが現実的です。
| 項目 | 現時点での見方 |
|---|---|
enableGenAITracing() | PR案として確認できるが、最終APIとして使う前にリリース確認が必要 |
AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING | PR案およびFoundry関連ドキュメントに登場する明示的な有効化の考え方 |
@azure/opentelemetry-instrumentation-azure-sdk | Azure SDKのOpenTelemetry連携で重要な既存パッケージ |
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT | メッセージ内容を記録するかを制御する環境変数として扱われている |
Azure SDK for JavaScriptの@azure/core-tracingドキュメントでも、既定ではno-opのInstrumenterが使われ、OpenTelemetryベースのtracingを有効にしたい場合は@azure/opentelemetry-instrumentation-azure-sdkをインストールして登録する流れが説明されています。(GitHub)
まず確認すべき設定とコマンド
利用中パッケージのバージョンを確認する
最初に、agent tracingの対象になり得るパッケージを確認します。
npm ls @azure/ai-projects
npm ls @azure/core-tracing
npm ls @azure/opentelemetry-instrumentation-azure-sdk
npm ls @azure/monitor-opentelemetry最新の公開バージョンも確認します。
npm view @azure/ai-projects version
npm view @azure/opentelemetry-instrumentation-azure-sdk version
npm view @azure/monitor-opentelemetry versionAzure SDK for JSのリリース一覧では、2026年5月5日に@azure/opentelemetry-instrumentation-azure-sdk_1.0.0が表示されています。一方で、指定PRのadding agent tracingはドラフトのため、@azure/ai-projectsに含まれているかは、リリースノートと実際のパッケージ内容で確認してください。(GitHub)
Azure SDK instrumentationは早めに登録する
@azure/opentelemetry-instrumentation-azure-sdkは、Azure SDKクライアントライブラリに対してOpenTelemetryのinstrumentationを有効化するためのパッケージです。登録後、Azureのデータプレーンパッケージは内部呼び出しやネットワーク呼び出しのspanを出力し始めます。(Microsoft Learn)
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk";
registerInstrumentations({
instrumentations: [createAzureSdkInstrumentation()],
});注意点は、Azure SDKクライアントライブラリを読み込む前に、できるだけ早くinstrumentationを登録することです。Microsoft Learnでも、OpenTelemetry instrumentationは必要なモジュールへのパッチに依存するため、Azureクライアントライブラリを読み込む前に登録すべきとされています。(Microsoft Learn)
Azure Monitorへ送る場合はApplication Insights接続を確認する
Azure Monitor Application Insightsへ送る場合は、OpenTelemetryのexporter設定に加えて、Foundryプロジェクト側でApplication Insightsが接続されているかを確認します。Foundryのセットアップ手順では、Application Insightsリソースの接続、Log Analytics Reader権限、Traces画面での確認が重要な前提として説明されています。(Microsoft Learn)
JavaScriptでは、Azure Monitor OpenTelemetryを使う場合にuseAzureMonitorを使う構成がサンプルとして示されています。(GitHub)
import { useAzureMonitor } from "@azure/monitor-opentelemetry";
useAzureMonitor({
azureMonitorExporterOptions: {
connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
},
});環境変数名はプロジェクトの運用ルールに合わせて構いません。ただし、接続文字列をソースコードへ直書きしないでください。ローカルでは.env、本番ではKey Vault、App Service設定、Container Appsのシークレットなどを使って管理するのが基本です。
メッセージ内容の記録は慎重に扱う
今回のagent tracingで最も注意すべき点は、メッセージ内容やツール呼び出しの扱いです。PR案では、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTがtrueの場合にメッセージ内容などを記録する設計があり、無効時はユーザー固有の内容ではなく汎用的なIDやタイプのみを記録する説明が含まれています。(GitHub)
さらにFoundryのトレース概念ドキュメントでも、トレースにはユーザー入力、エージェント出力、ツール使用、トークン消費、時間情報などが含まれ得ると説明されています。セキュリティとプライバシーの観点では、プロンプト、ツール引数、span属性に秘密情報や個人情報を入れないこと、必要に応じてマスク・最小化することが推奨されています。(Microsoft Learn)
本番環境では、まず次の方針で始めるのが安全です。
| 項目 | 推奨判断 |
|---|---|
| メッセージ本文 | 原則オフから開始 |
| エージェント名・モデル名・レスポンスID | 監視に必要なら記録 |
| ツール引数・戻り値 | 個人情報・機密情報が含まれる可能性を評価してから |
| トレースの保持期間 | Application Insightsの保持設定に合わせて確認 |
| 閲覧権限 | 最低限、運用担当・監査担当に限定 |
| サンプリング | 高トラフィック環境では必ず検討 |
移行というより「観測設計の見直し」と考える
この変更は、API呼び出しの書き換えを急ぐタイプの移行ではありません。むしろ、AIエージェントを本番運用するための観測設計を見直すきっかけです。
確認手順
| 手順 | やること | 判断基準 |
|---|---|---|
| 1 | PR #38363がマージ済みか確認 | ドラフト・レビュー中なら本番反映しない |
| 2 | @azure/ai-projectsのリリースノートを確認 | agent tracingが明記されているか |
| 3 | OpenTelemetry instrumentationの登録順を確認 | Azure SDK import前に登録できているか |
| 4 | Application Insights接続を確認 | FoundryのTraces画面に表示できるか |
| 5 | メッセージ内容の記録方針を決める | セキュリティレビューなしでオンにしない |
| 6 | ストリーミング応答をテスト | キャンセル時にもspanが閉じるか |
| 7 | 負荷テストでデータ量を見る | トレース量とコストが許容範囲か |
よくある失敗と対策
| 失敗しやすいポイント | 起きる問題 | 対策 |
|---|---|---|
| ドラフトPRを正式仕様として扱う | 未確定APIに依存して後から修正が必要になる | マージ、リリース、公式ドキュメント反映を確認する |
| instrumentation登録が遅い | Azure SDKのspanが出ない | アプリ起動直後、Azure SDK import前に登録する |
| exporterを設定していない | spanは作られても保存先に届かない | Azure Monitor、Console、OTLPのいずれかを明示する |
| Application Insights未接続 | FoundryのTracesで見えない | FoundryプロジェクトとApplication Insightsの接続を確認する |
| 権限不足 | トレースをクエリできない | Log Analytics Readerなど必要なRBACを付与する |
| メッセージ内容を不用意に記録 | 個人情報・機密情報が監視基盤に残る | content recordingは原則オフから始める |
| ストリーミングを途中破棄する | span終了やメトリック記録が不安定になる | キャンセル時のreturn/throw処理をテストする |
本番適用前のチェックリスト
以下を満たしてから本番反映を検討してください。
@azure/ai-projectsの該当バージョンにagent tracingが含まれていることを確認した@azure/opentelemetry-instrumentation-azure-sdkをAzure SDK読み込み前に登録している- Azure Monitor Application InsightsまたはOTLPの送信先を設定している
- FoundryプロジェクトにApplication Insightsが接続されている
- Traces画面またはApplication Insightsでspanを確認できる
- メッセージ本文、ツール引数、モデル出力の保存方針を決めている
- 本番トラフィックでのトレース量、保持期間、課金影響を確認した
- ストリーミング応答、キャンセル、エラー時のトレースをテストした
- セキュリティ担当者がトレースデータの閲覧権限を確認した
Azure SDK agent tracingをどう活用すべきか
agent tracingは、AIエージェントの「なぜ遅いのか」「どこで失敗したのか」「どのモデルやツールが使われたのか」を追うための基盤です。特に、RAG、ツール呼び出し、複数エージェント連携、ストリーミングUIを使うアプリでは、通常のログだけでは原因調査に時間がかかります。
一方で、AIエージェントのトレースは通常のWeb APIログよりも機密性が高くなりやすいです。ユーザー入力、モデル出力、ツール引数、検索結果、社内データの断片が含まれる可能性があるため、便利だからといってすぐに全文記録を有効にするのは避けるべきです。
まずは、エージェント名、操作名、レスポンスID、モデル名、トークン使用量、エラー種別、レイテンシなど、運用に必要なメタデータ中心で始めます。そのうえで、障害調査や品質評価に本文が必要な場合だけ、対象環境・保持期間・閲覧権限を限定してcontent recordingを検討してください。
まとめ：次に取るべき行動
Azure SDKのAzure SDK documentation update: adding agent tracingは、AIエージェント運用の可観測性を高める重要な動きです。ただし、指定PR #38363はドラフト段階のため、現時点では「即移行」ではなく「影響範囲の確認」と「監視設計の準備」が中心です。
まず、自社アプリが@azure/ai-projects、getOpenAIClient()、Responses API、Foundry agentsを使っているかを確認してください。該当する場合は、OpenTelemetry instrumentationの登録順、Application Insights接続、権限、メッセージ内容の記録方針を点検します。正式リリースに含まれたことを確認できたら、開発環境でspanの出力、ストリーミング応答、エラー時の挙動、トレース量をテストし、本番環境ではcontent recordingをオフにした最小構成から始めるのが現実的です。
コメント