2026年5月5日に公開された Microsoft developer platform の更新「Fix getCallerBaggagePairs: resolve userId across all channels」でまず確認すべき点は、OpenTelemetry の baggage に入る userId の決定ロジックが、Teams 前提の aadObjectId だけではなく、agenticUserId や from.id へフォールバックするようになったことです。これにより、Teams 以外のチャネルや Agent-to-Agent（A2A）呼び出しでも userId が空になりにくくなります。PR は 2026年5月5日に投稿され、2026年5月6日に main ブランチへマージされています。(GitHub)
この変更は、認証方式を変えるものではありません。主な影響は、Agent 365 / A365 関連の可観測性、トレース、ログ、ダッシュボード、監査・分析で使われる「呼び出し元ユーザーの識別」にあります。特に、Node.js / TypeScript で @microsoft/opentelemetry の A365 hosting middleware、BaggageMiddleware、configureA365Hosting()、BaggageBuilderUtils.fromTurnContext() を使っている開発チームは、アップデート後の userId の値を必ず確認してください。
Microsoft developer platformで何が変わったのか
今回の変更対象は、Microsoft の opentelemetry-distro-javascript リポジトリにある getCallerBaggagePairs() の userId 解決処理です。
変更前は、userId baggage が from.aadObjectId からのみ設定されていました。しかし、aadObjectId は Teams では利用できても、Teams 以外のチャネルや A2A 呼び出しでは undefined になるケースがあります。そのため、テレメトリ上でユーザー識別子が欠落し、チャネル横断の分析や障害調査が難しくなる可能性がありました。
変更後は、以下の順序で userId が解決されます。
| 優先順位 | 参照される値 | 主な想定シーン |
|---|---|---|
| 1 | aadObjectId | Teams など、Microsoft Entra ID のオブジェクトIDが取得できる場合 |
| 2 | agenticUserId | A2A 呼び出しなど、エージェント由来の識別子がある場合 |
| 3 | from.id | Teams 以外のチャネル、Web Chat、Direct Line、独自チャネルなど |
PR の差分では、USER_ID_KEY に設定する値が from.aadObjectId から from.aadObjectId || from.agenticUserId || from.id に変更され、ActivityLike.from 型にも任意の id フィールドが追加されています。あわせて、非 Teams チャネル、A2A、複数識別子がある場合の優先順位を検証するテストも追加されています。(GitHub)
なぜuserIdのフォールバックが重要なのか
OpenTelemetry の baggage は、リクエストに付随して伝搬されるキー・バリュー形式のコンテキスト情報です。トレース、メトリクス、ログの分析に必要なユーザーID、アカウントID、製品IDなどを下流サービスへ渡す用途で使われます。(OpenTelemetry)
A365 / Agent 365 のエージェントアプリでは、1つの会話や処理が複数のサービス、ツール、エージェント、外部APIにまたがることがあります。このとき userId が欠けると、次のような問題が起きやすくなります。
- Teams では追跡できるが、Web Chat や独自チャネルでは同じ分析軸が使えない
- A2A 呼び出しで、上流エージェントや呼び出し元を区別しづらい
- 「特定ユーザーでだけ遅い」「特定チャネルでエラーが多い」といった調査に時間がかかる
- ダッシュボード上で
unknown、空欄、未分類のデータが増える - 監査・セキュリティ調査時に、イベントと呼び出し元の対応付けが弱くなる
今回の修正は、この欠落を減らすためのものです。特に「Teams だけでなく複数チャネルでエージェントを提供している」環境では、テレメトリ品質に直接影響します。
チャネル別に見る変更後のuserId
PR で示された挙動を実務向けに整理すると、次のようになります。
| 利用チャネル・呼び出し | 変更前のuserId | 変更後のuserId | 対応の必要性 |
|---|---|---|---|
| Teams | aadObjectId | aadObjectId | 基本的には影響小。ただし既存ダッシュボードの値を確認 |
| Teams以外のチャネル | 空になりやすい | from.id | 影響大。新たにユーザー別集計が可能になる |
| A2A呼び出し（ユーザー由来） | 状況により空 | aadObjectId があれば優先 | 優先順位の確認が必要 |
| A2A呼び出し（エージェント由来） | 空になりやすい | agenticUserId | エージェント識別・監査観点で確認 |
| 複数の識別子が存在 | aadObjectId のみ | aadObjectId を最優先 | 既存のTeams分析との互換性は保ちやすい |
重要なのは、aadObjectId がある場合は引き続き最優先される点です。つまり、Teams で取得できていた Microsoft Entra ID ベースの識別子が、急に from.id や agenticUserId に置き換わる設計ではありません。
一方で、これまで空だった userId に値が入るようになるチャネルでは、ダッシュボードやクエリの結果が変わります。これは多くの場合は改善ですが、既存の集計ロジックによっては「ユーザー数が急に増えた」「未分類が減った」「アラート条件に該当するデータが増えた」と見えることがあります。
対応すべき開発者・運用担当者
今回の Microsoft developer platform 更新で対応を検討すべきなのは、主に次のチームです。
Node.js / TypeScriptでMicrosoft OpenTelemetry Distroを使っているチーム
Microsoft OpenTelemetry Distro は、Microsoft Agent 365、Microsoft Foundry、Azure Monitor、OTLP 互換バックエンドなどへテレメトリを送るための可観測性ディストリビューションです。Node.js では npm install @microsoft/opentelemetry で導入する形が案内されています。(Microsoft Learn)
次のようなコードを使っている場合は、今回の変更の影響を受ける可能性があります。
import { configureA365Hosting } from "@microsoft/opentelemetry";
configureA365Hosting(adapter);または、明示的に baggage middleware を登録している場合です。
import { BaggageMiddleware } from "@microsoft/opentelemetry";
adapter.use(new BaggageMiddleware());Microsoft のドキュメントでは、Baggage middleware を登録すると、すべての着信 TurnContext から呼び出し元、エージェント、テナント、チャネル、会話の詳細が抽出され、要求が baggage scope にラップされると説明されています。(Microsoft Learn)
複数チャネルでエージェントを提供しているチーム
Teams だけでなく、Web Chat、Direct Line、独自UI、外部サービス連携、A2A 呼び出しを使っている場合は、今回の修正によって userId の入り方が変わります。
特に確認すべきなのは、次のような構成です。
| 構成 | 確認すべき理由 |
|---|---|
| Teams + Web Chat | Teamsでは aadObjectId、Web Chatでは from.id になり、同じ「ユーザーID」でも形式が異なる可能性がある |
| 独自チャネル | from.id の値が安定しているか、セッションごとに変わるかで分析精度が変わる |
| A2A構成 | 呼び出し元が人間なのかエージェントなのかで userId の意味が変わる |
| 複数テナント | userId 単体では衝突する可能性があるため、tenantId との組み合わせで見る必要がある |
移行時に確認すべきポイント
今回の変更は、基本的には不具合修正に近い内容です。ただし、テレメトリの値が変わるため、何も確認せず本番反映するのは避けるべきです。
パッケージに修正が含まれているか確認する
PR は main ブランチにマージされていますが、利用中の npm パッケージにいつ含まれるかは、リリースやタグ、パッケージの公開タイミングに依存します。日付だけで「手元の環境にも反映済み」と判断しないでください。
確認する場所は次の3つです。
| 確認対象 | 見るべき内容 |
|---|---|
package.json | @microsoft/opentelemetry の指定バージョン |
package-lock.json / pnpm-lock.yaml / yarn.lock | 実際に解決されたバージョン |
| GitHub Releases / npm の公開情報 | PR #116 を含むリリースかどうか |
開発環境では、単に npm install し直すだけでなく、ロックファイルの差分も確認してください。CI/CD で固定バージョンを使っている場合、ローカルだけ更新されて本番には反映されないことがあります。
userIdの値をチャネル別にテストする
アップデート後は、最低限次の4パターンをテストします。
| テストケース | 入力例 | 期待されるuserId |
|---|---|---|
| Teams | from.aadObjectId = "aad-oid" | aad-oid |
| Teams以外 | from.id = "webchat-user-123" | webchat-user-123 |
| A2A | from.agenticUserId = "[email protected]" | [email protected] |
| 複数指定 | aadObjectId、agenticUserId、from.id がすべて存在 | aadObjectId |
テストでは「値が入るか」だけでなく、「どの値が優先されるか」を確認することが重要です。特に、from.id と agenticUserId の両方が入るケースでは、A2A 呼び出しの設計意図に合っているかを見てください。
ダッシュボードとアラート条件を見直す
userId が空だったデータに値が入るようになると、可観測性の品質は上がります。一方で、既存の集計結果は変化します。
見直すべき代表例は次のとおりです。
| 項目 | 起きやすい変化 | 対応 |
|---|---|---|
| ユーザー別エラー率 | これまで未分類だったエラーが特定ユーザーに紐づく | 変更日を境に集計を比較する |
| ユーザー数・ユニークID数 | from.id の粒度次第で増える | チャネル別にカーディナリティを確認 |
| SLA / SLO ダッシュボード | 空の userId を除外していた場合、対象データが増える | フィルター条件を再確認 |
| アラート | userId != null 条件の該当件数が増える | しきい値を一時的に観察する |
| 監査ログ連携 | 追跡できる対象が増える | 個人情報・識別子の扱いを確認 |
特に注意したいのは、from.id の安定性です。チャネルによっては、同じ人でもチャネルID、会話ID、セッションIDに近い値になる場合があります。その場合、「人」を表すIDとして使うのか、「チャネル上の参加者」を表すIDとして使うのかを明確にしておく必要があります。
セキュリティとプライバシーで注意すべき点
userId が入りやすくなることは、分析や障害調査には有利です。しかし、baggage は伝搬される情報であるため、扱いには注意が必要です。
OpenTelemetry のドキュメントでは、baggage はサービスやプロセス間でデータを渡す仕組みであり、機密性の高い項目は意図しないリソースと共有される可能性があると説明されています。また、baggage は明示的に追加しない限り、スパン、メトリクス、ログの属性と自動的に同一視されるものではありません。(OpenTelemetry)
実務では、次の観点で確認してください。
| 観点 | 確認内容 |
|---|---|
| 個人情報 | userId がメールアドレス、社員番号、外部IDなどに該当しないか |
| 外部送信 | OTLP 互換バックエンド、ログ基盤、外部監視サービスへ送ってよい値か |
| マスキング | ログやエクスポート先でマスキング・ハッシュ化が必要か |
| アクセス権 | userId を含むトレースやログを閲覧できる人が適切か |
| 保持期間 | 監査・調査に必要な期間とプライバシー要件が合っているか |
「識別できる値が増える」変更は、可観測性の改善であると同時に、データガバナンス上の確認ポイントでもあります。特に agenticUserId にメールアドレス形式の値が入る可能性がある環境では、ログ出力先と閲覧権限を見直してください。
設定確認の実務手順
本番反映前には、次の順序で確認すると安全です。
まずA365 hosting middlewareの有効化状況を確認する
configureA365Hosting() を使っている場合、A365 hosting middleware は exporter の設定とは別に adapter へ明示的に取り付けます。GitHub の README では、configureA365Hosting(adapter) によって既定で BaggageMiddleware と OutputLoggingMiddleware が登録されると説明されています。(GitHub)
import { configureA365Hosting } from "@microsoft/opentelemetry";
configureA365Hosting(adapter, {
enableBaggage: true,
enableOutputLogging: false,
});応答内容に機密情報が含まれる可能性がある場合は、enableOutputLogging: false を検討してください。今回の userId 修正とは別論点ですが、同じ可観測性設定の中で見落とされやすいポイントです。
ローカル出力または検証環境で値を確認する
Microsoft Learn では、リモートの宛先に送る前にローカル出力でインストルメンテーションを検証する方法も案内されています。Node.js では、A365 exporter を無効化しつつ useMicrosoftOpenTelemetry() を呼び出し、アプリケーションコードを実行してから shutdownMicrosoftOpenTelemetry() で終了処理を行う例が示されています。(Microsoft Learn)
検証では、次の観点をログまたはトレース上で確認します。
- Teams では
aadObjectIdがuserIdとして使われているか - Teams 以外では
from.idが入っているか - A2A 呼び出しでは
agenticUserIdが期待どおり入っているか - 空文字や
undefinedが不要に属性化されていないか tenantId、agentId、conversationIdなど他の baggage と組み合わせて分析できるか
本番反映後は変更日を境に比較する
2026年5月5日または実際のデプロイ日を境に、userId の分布を比較してください。見るべき指標は、単純なエラー数ではなく「空の userId がどれだけ減ったか」「チャネル別に想定外のID形式が混ざっていないか」です。
たとえば、以下のような観点で比較します。
| 比較項目 | 良い状態 | 注意が必要な状態 |
|---|---|---|
| 空のuserId割合 | Teams以外で減少している | 依然として空が多い |
| チャネル別userId形式 | TeamsはAAD、非Teamsはfrom.idなど想定どおり | 同一チャネルで形式が混在しすぎる |
| ユニークuserId数 | チャネル増加分として説明できる | セッション単位で急増している |
| エラー調査 | ユーザー・チャネル単位で追いやすい | かえって識別子の意味が曖昧になっている |
よくある誤解と失敗しやすいポイント
「Teamsだけ使っているから関係ない」と判断する
Teams のみで aadObjectId が安定して取得できている場合、影響は小さい可能性があります。ただし、将来的に Web Chat、独自チャネル、A2A 連携を追加する予定があるなら、今のうちに userId の意味を設計しておくべきです。
userId を「Microsoft Entra ID のユーザー」として扱うのか、「チャネル上の呼び出し元」として扱うのかで、ダッシュボードや監査ログの設計が変わります。
from.idを常に人間のIDだと見なす
from.id はチャネル上の送信元IDとして使われることがありますが、常に組織内の個人を一意に表すとは限りません。チャネルやアダプターの仕様によっては、ユーザー、会話参加者、ボット、エージェント、セッションに近い意味を持つことがあります。
そのため、from.id を使う場合は channelId、tenantId、conversationId と合わせて見るのが安全です。
ダッシュボードの過去データと単純比較する
アップデート前は userId が空だったデータが、アップデート後には値を持つようになります。この場合、ユーザー別集計の母数が変わるため、過去データとの単純比較は誤解を招きます。
本番反映後しばらくは、ダッシュボードに「userId解決ロジック変更後」の注記を入れるか、変更日前後で別々に集計することをおすすめします。
監査・プライバシー確認を後回しにする
userId は障害調査に便利ですが、識別子である以上、取り扱いルールが必要です。特に外部の OTLP 互換バックエンドやログ基盤へ送っている場合、送信先、保持期間、アクセス権限、マスキング方針を確認してください。
今回の更新で取るべき次のアクション
今回の Microsoft developer platform 更新は、A365 / Agent 365 の可観測性で userId をより確実に解決するための修正です。Teams では従来どおり aadObjectId が優先され、Teams 以外では from.id、A2A では agenticUserId が fallback として使われます。
開発・運用チームは、まず利用中の @microsoft/opentelemetry に PR #116 相当の修正が含まれているかを確認してください。そのうえで、Teams、非 Teams、A2A の代表リクエストを検証し、userId の値、ダッシュボード、アラート、ログ送信先、プライバシー要件を見直します。
特に複数チャネル展開をしているエージェントでは、今回の修正によって「見えなかったユーザー軸」が見えるようになります。単なる依存関係更新として扱わず、可観測性設計を一段見直すタイミングとして活用するとよいでしょう。
コメント