Microsoft Teamsの「documentation update: feat: OpenTelemetry instrumentation + Agent365 baggage support」は、Teamsの画面や会議機能の変更ではなく、Teams向け.NET SDKで作るボット／エージェントの監視・トレース・Agent365連携に関する更新です。結論から言うと、Teamsボットを.NET SDKで運用している開発者、Azure MonitorやOTLPで可観測性を見ているSRE、Agent365向けにエージェント公開を考えているチームは、OpenTelemetryの登録設定とAgent365 baggageの付与方法を確認する必要があります。
特に重要なのは、Teams SDKの処理単位ごとにActivitySource spanとMeter metricが出るようになる点、そしてAgent365向けの必須属性をTeamsのアクティビティ情報から組み立てるBaggageBuilderが追加される点です。GitHub上のPR #475はドラフト状態として表示されているため、すぐに本番適用するというより、取り込むパッケージ版・マージ状況・公開API名を確認してから検証環境で試すのが安全です。(GitHub)
Microsoft Teams documentation updateで確認すべき変更点
今回のMicrosoft Teams documentation updateは、microsoft/teams.netリポジトリのPR「feat: OpenTelemetry instrumentation + Agent365 baggage support」に関する内容です。teams.netはTeams Platform上でアプリやボットを構築するための.NET向けパッケージ群で、リポジトリ上でも「Teams Platformで構築するためのパッケージ」と説明されています。(GitHub)
更新の中心は、Teams SDK内部の処理をOpenTelemetryで観測しやすくすることです。PRのSummaryでは、1ターン単位でturn、middleware、handler、auth.outbound、conversation_clientのspanを出し、teams.activities.received、teams.turn.duration、teams.handler.errors、teams.middleware.duration、teams.outbound.calls、teams.outbound.errorsなどのmetricを出す設計が示されています。(GitHub)
つまり、これまで「Teamsボットが遅い」「外部送信で失敗している」「どのミドルウェアで時間がかかっているか分からない」といった調査をログ中心で行っていたチームは、トレースとメトリクスで原因を追いやすくなります。
| 変更点 | 何が分かるようになるか | 確認すべき人 |
|---|---|---|
turn span | 1つのTeamsアクティビティ処理全体の時間とエラー | Teamsボット開発者、SRE |
middleware span | ミドルウェア単位の処理時間 | SDK拡張・認証・監査処理を入れている開発者 |
handler span | メッセージやinvokeのハンドラー処理 | ルーティングごとの性能を見たい開発者 |
auth.outbound span | 外向き認証処理の流れ | 認証失敗やトークン取得遅延を調査する担当者 |
conversation_client span | Bot Service APIへの送信・更新・削除 | 返信遅延や送信失敗を追う担当者 |
teams.* metrics | 受信数、処理時間、エラー数、外向き呼び出し数 | 運用監視・アラート設計担当者 |
これはTeams利用者向けではなく、Teamsボット開発者向けの更新
まず切り分けたいのは、この更新がTeamsクライアントのUI変更ではないことです。一般ユーザーがTeamsアプリで何かを設定する必要はありません。
影響があるのは、主に次のようなチームです。
| 対象 | 対応要否 | 理由 |
|---|---|---|
| Teamsボットを.NET SDKで開発しているチーム | 高 | SDKのspan・metricを収集できるようになるため |
| Azure Monitor / Application Insightsでボットを監視しているチーム | 中〜高 | OpenTelemetry経由の監視設計を見直せるため |
| OTLP Collector、Grafana、Jaegerなどを使うチーム | 中〜高 | Teams SDKのsource / meter登録が必要になるため |
| Agent365向けエージェントを公開予定のチーム | 高 | store validationに必要な属性・scope確認が必要なため |
| 通常のTeams利用者・会議管理者 | 低 | Teams画面や会議設定の変更ではないため |
| Teamsタブアプリのみ運用しているチーム | 低〜中 | teams.netのBot / Apps層を使っているかで影響が変わるため |
実務上は、「Teamsを使っているか」ではなく「Teams SDKでボット／エージェントの処理を実装しているか」で判断してください。
OpenTelemetry instrumentationで何が変わるのか
OpenTelemetry instrumentationとは、アプリの処理をトレース、メトリクス、ログとして外部に出せるようにする仕組みです。今回の更新では、Teams SDK側が.NETのActivitySourceとMeterを使って信号を発行し、アプリ側がOpenTelemetry SDKやexporterを設定して収集する形が整理されています。設計ドキュメントでは、Core層がMicrosoft.Teams.Core、Apps層がMicrosoft.Teams.Appsというsource / meter名を持つ方針が示されています。(GitHub)
重要なのは、SDKがspanやmetricを「出せる」だけでは、監視基盤に自動で流れるとは限らない点です。アプリ側でOpenTelemetryの設定にsourceとmeterを登録する必要があります。
典型的には、次のような考え方で設定します。実際の公開API名は、取り込んだパッケージのバージョンに合わせて確認してください。
using Microsoft.OpenTelemetry;
builder.Services.AddOpenTelemetry()
.UseMicrosoftOpenTelemetry(o =>
{
o.Exporters = ExportTarget.Otlp | ExportTarget.AzureMonitor;
})
.WithTracing(tracing => tracing
.AddSource("Microsoft.Teams.Core")
.AddSource("Microsoft.Teams.Apps"))
.WithMetrics(metrics => metrics
.AddMeter("Microsoft.Teams.Core")
.AddMeter("Microsoft.Teams.Apps"));
builder.Logging.AddOpenTelemetry(o =>
{
o.IncludeFormattedMessage = true;
});実装時は、文字列を直接書くよりも、SDKが公開する定数が使えるなら定数を使う方が安全です。ただしPR内ではTeamsCoreTelemetryやCoreTelemetryNamesのように命名差分が見えるため、最終的に利用するNuGetパッケージやブランチのAPIを確認してからコード化してください。PRのサンプルではCoreTelemetryNames.ActivitySourceNameやTeamsBotApplicationTelemetry.ActivitySourceNameを配列に入れ、.WithTracing()と.WithMetrics()で登録する実装が示されています。(GitHub)
追加されるspanとmetricの見方
今回のspanは、Teamsボットの1回の会話処理を分解して見るためのものです。概念的には、HTTP server spanの下にturnがあり、その中にmiddleware、handler、conversation_client、auth.outboundなどがぶら下がる構造になります。設計ドキュメントでも、HTTP server spanを親にしてTeams SDKの各spanが階層化される例が示されています。(GitHub)
現場で見るべきポイントは次の通りです。
| 観測対象 | 見るべき指標 | 典型的な判断 |
|---|---|---|
teams.turn.duration | Teamsの1ターン処理時間 | P95 / P99が伸びるなら、handlerか外部呼び出しを分解して確認 |
teams.middleware.duration | ミドルウェアごとの時間 | 認証、監査、コンテキスト生成で遅延がないか確認 |
teams.handler.errors | ハンドラー内エラー数 | 特定のactivity typeやinvokeで増えていないか確認 |
teams.outbound.calls | 送信・更新・削除の呼び出し数 | 想定以上の返信・更新ループがないか確認 |
teams.outbound.errors | 外向き呼び出し失敗数 | Bot Service API、認証、ネットワークの切り分けに使う |
おすすめは、まずturn全体の遅延をアラート対象にし、原因調査ではhandler、middleware、conversation_clientを見る構成です。最初からすべてのspanにアラートを張るとノイズが増えるため、運用開始時は「ターン全体」「外向きエラー」「ハンドラーエラー」の3つを優先すると扱いやすくなります。
Agent365 baggage supportとは何か
Agent365 baggage supportは、Agent365にテレメトリを送る際に必要なコンテキスト情報を、Teamsのアクティビティから組み立てるための仕組みです。
OpenTelemetryのbaggageは、処理の流れに沿って引き回されるキー・バリュー形式のコンテキストです。OpenTelemetry .NETの説明でも、baggageはトレース、メトリクス、ログに関係するコンテキストとして扱える一方、テレメトリに付与するには明示的な利用が必要だと説明されています。(GitHub)
今回の設計では、Teams SDKのCore層とApps層に、それぞれ別のBaggageBuilderを持たせる方針です。Core層はCoreActivityやConversationAccountから値を読み、Apps層はTeamsConversationAccount由来のuser.id、user.email、microsoft.agent.user.email、gen_ai.agent.descriptionなども扱う設計になっています。(GitHub)
Apps層のTeamsボットであれば、ハンドラーの先頭で次のようにbaggage scopeを作るイメージです。
teamsApp.OnMessage(async (context, ct) =>
{
using var baggageScope = new Microsoft.Teams.Apps.Diagnostics.BaggageBuilder()
.FromTeamsContext(context)
.OperationSource("teams-bot")
.Build();
// ここから下で作られるspanにAgent365向けのbaggageが付与される
// LLM呼び出し、ツール実行、応答送信などを行う
});OperationSource("teams-bot")のような値は、Teamsアクティビティから自動で分かるものではありません。アプリ側で運用上分かりやすい固定値を決めておくと、Agent365や監視画面で分類しやすくなります。
Agent365公開を考えるチームが特に確認すべきこと
Agent365向けにエージェントを公開する場合、baggageを設定するだけでは足りません。Microsoft OpenTelemetry DistroのAgent365ドキュメントでは、store validationに向けてInvokeAgentScope、InferenceScope、ExecuteToolScopeの実装が必要とされています。(GitHub)
Teams SDK側のBaggageBuilderは、Agent365に必要な共通属性を埋める補助です。一方で、LLM推論、ツール呼び出し、入力・出力メッセージなど、処理境界ごとのscopeはアプリ側で適切に作る必要があります。
| 確認項目 | なぜ重要か | 不足した場合の症状 |
|---|---|---|
microsoft.tenant.id | テナント識別に必要 | spanが正しく関連付かない、export対象外になる可能性 |
gen_ai.agent.id / gen_ai.agent.name | エージェント識別に必要 | Agent365上でエージェント単位の集計が崩れる |
user.id / user.email | 呼び出し元ユーザーの識別に必要 | validationや監査で不足する可能性 |
microsoft.agent.user.id / microsoft.agent.user.email | agentic user識別に必要 | Agent365側の必須属性不足になり得る |
gen_ai.conversation.id | 会話単位の関連付けに必要 | セッション追跡が困難になる |
InvokeAgentScope | エージェント呼び出し全体の記録 | store validationで不足する可能性 |
InferenceScope | LLM推論の記録 | モデル呼び出しの監査・分析ができない |
ExecuteToolScope | ツール実行の記録 | tool callの監査・検証ができない |
Agent365ドキュメントでは、InvokeAgentScope、ExecuteToolScope、InferenceScopeごとにrequired属性が列挙されています。たとえばInvokeAgentScopeではclient.address、user.id、user.email、microsoft.channel.name、gen_ai.conversation.id、gen_ai.input.messages、gen_ai.output.messages、server.address、server.port、microsoft.tenant.idなどがRequiredとして示されています。(GitHub)
Core-onlyボットでは不足する属性に注意
Teams SDKのApps層を使う一般的なTeamsルーターボットであれば、TeamsConversationAccountからユーザーIDやメールアドレスを取りやすくなります。一方、Core層だけを使うボットでは、Agent365 validationに必要な一部属性を自動取得できない可能性があります。
設計ドキュメントでも、Core-onlyボットではuser.id、user.email、microsoft.agent.user.emailなどを手動で設定する例が示されています。(GitHub)
Core-only構成でAgent365 exportを使う場合は、次のように「Teamsアクティビティから取れる値」と「アプリ側で補う値」を分けて確認してください。
using Microsoft.Teams.Core.Diagnostics;
using var baggageScope = new BaggageBuilder()
.FromCoreActivity(activity)
.Set("user.id", userAadObjectIdFromAuth)
.Set("user.email", userEmailFromAuth)
.Set("microsoft.agent.user.email", agentEmailFromConfig)
.OperationSource("teams-bot")
.Build();ここで注意したいのは、メールアドレスやユーザーIDは個人情報に該当し得ることです。baggageはspanに属性として付与され、export先に送られる設計のため、Azure Monitor、OTLP collector、Agent365、ログ保存先のアクセス権限と保持期間を事前に確認してください。Microsoft OpenTelemetry Distroのドキュメントでも、BaggageBuilderで設定した情報がrequest内のspanに付与される例が示されています。(GitHub)
TenantIdとchannelDataの扱いも確認する
今回の更新では、Core層のConversationAccountにTenantIdをtyped propertyとして昇格させる変更も示されています。これにより、Core層だけでもmicrosoft.tenant.idを埋めやすくする意図があります。(GitHub)
ただし、クラシックなBot FrameworkのTeams trafficでは、tenant idがfrom.tenantIdやrecipient.tenantIdではなくchannelData.tenant.idに入ることがあると設計ドキュメントで説明されています。そのため、Recipient.TenantIdだけを見て「tenant idが空」と判断しないよう注意が必要です。Teams SDK側のBaggageBuilderでは、typed fieldがnullの場合にchannelData.tenant.idへfallbackする設計が示されています。(GitHub)
また、microsoft.channel.linkをTeamsのチャネルIDやServiceUrlから安易に作らない方針も示されています。microsoft.channel.nameはTeamsのChannelId、たとえばmsteamsのような値で埋められますが、microsoft.channel.linkはAgent365上のサブチャネル的な意味合いに近く、Teamsのチーム／チャネルIDとは意味が異なるためです。(GitHub)
設定確認の実務手順
検証環境では、次の順番で確認すると抜け漏れを減らせます。
| 手順 | 作業 | 合格基準 |
| -: | ——————————————————- | ———————————————————— |
| 1 | 利用中のMicrosoft.Teams.*パッケージとPR反映状況を確認 | 対象機能が入った版を使っていることが分かる |
| 2 | OpenTelemetryのexporterを決める | Azure Monitor、OTLP、Agent365のどれに送るか決まっている |
| 3 | Microsoft.Teams.CoreとMicrosoft.Teams.Appsのsourceを登録 | turn、middleware、handlerなどが出る |
| 4 | meterを登録 | teams.activities.receivedやteams.turn.durationが取れる |
| 5 | テストメッセージをTeamsボットに送る | 1ターンのspan treeが確認できる |
| 6 | Agent365利用時はBaggageBuilderをhandler先頭に置く | 必須baggageがspanに付与される |
| 7 | LLM・ツール呼び出しにscopeを実装 | InvokeAgentScope、InferenceScope、ExecuteToolScopeが確認できる |
| 8 | 本番前にPIIとログ保持を確認 | user emailなどの取り扱いが社内ルールに合っている |
ローカル検証では、PR内のObservabilityBotサンプルも参考になります。サンプルにはMicrosoft.OpenTelemetry、OTLP、Agent365、Azure Monitorの設定、Teams SDKのsource / meter登録、BaggageBuilder().FromTeamsContext(context).OperationSource(...).Build()の使用例が含まれています。(GitHub)
失敗しやすいポイント
.UseMicrosoftOpenTelemetry()だけでTeams SDKのspanが出ると思い込む
Microsoft OpenTelemetry Distroを有効化しても、アプリ独自またはライブラリ独自のActivitySourceは登録が必要です。Teams SDKのspanを見たいなら、Microsoft.Teams.CoreとMicrosoft.Teams.Appsのsourceを登録してください。Distro側のドキュメントでも、独自のactivity sourceを追加する場合は.AddSource()を使う例が示されています。(GitHub)
Apps側だけ登録してCore側を忘れる
handlerだけ見えても、turn、middleware、auth.outbound、conversation_clientが見えなければ、原因調査の粒度が不足します。Teamsルーターボットでは、Apps層とCore層の両方を登録するのが基本です。
Agent365-only構成でHTTP spanが見えない
Microsoft OpenTelemetry DistroのAgent365-only modeでは、Agent365だけにexportする構成の場合、ASP.NET CoreやHttpClientなどのインフラ系instrumentationが抑制される動作が説明されています。Teamsの外向きHTTP呼び出しまで見たい場合は、Azure MonitorやOTLPを併用するか、必要なinstrumentationを明示的に有効化する設定を確認してください。(GitHub)
Console exporterを本番に残す
Console exporterはローカル検証には便利ですが、本番では標準出力にテレメトリが出てしまい、性能面や情報管理上のリスクがあります。Microsoft OpenTelemetry Distroのドキュメントでも、ExportTarget.Consoleはローカル開発向けで、本番では使わないよう注意が示されています。(GitHub)
baggageに個人情報を入れる範囲を決めていない
Agent365 validationのためにuser.emailなどが必要になる場面がありますが、だからといって無制限にbaggageへ入れてよいわけではありません。export先、閲覧権限、保存期間、マスキング方針を決めてから本番化してください。
移行・導入時の判断基準
この更新は、全チームが急いで対応すべきものではありません。次の基準で優先度を決めると判断しやすくなります。
| 状況 | 優先度 | 推奨アクション |
|---|---|---|
| Teamsボットの障害調査に時間がかかっている | 高 | OpenTelemetry設定を入れてturnとhandlerから可視化 |
| Agent365公開・store validationを予定している | 高 | BaggageBuilderと必須scopeを検証 |
| すでにAzure Monitorで監視している | 中〜高 | Teams SDKのsource / meterを追加登録 |
| OTLP CollectorやGrafanaを運用している | 中 | teams.* metricをダッシュボード化 |
| Teamsボットはあるが監視要件が薄い | 中 | まず検証環境でspanだけ確認 |
| Teamsボットを使っていない | 低 | 対応不要。関連プロジェクトがないかだけ確認 |
本番反映の前には、teams.turn.durationの基準値を検証環境で測り、リリース後に「何msを超えたら異常」と判断できる状態にしておくと効果的です。可観測性の導入は、データを出すことよりも、異常時に誰が何を見るかを決めることが重要です。
今すぐ確認すべきチェックリスト
Teamsボットを運用している場合は、まず次の項目を確認してください。
- 利用中の
Microsoft.Teams.*パッケージに対象更新が含まれるか - PRがマージ済みか、ドラフト段階の情報を参照していないか
Microsoft.Teams.CoreとMicrosoft.Teams.Appsのsource / meterを登録しているか- Azure Monitor、OTLP、Agent365のexport先を明確に分けているか
- Agent365向けに
BaggageBuilderをhandlerの早い段階で実行しているか - Core-only構成で不足する
user.id、user.email、microsoft.agent.user.emailを補っているか InvokeAgentScope、InferenceScope、ExecuteToolScopeをアプリ側で実装しているか- user emailなどの個人情報がexport先に送られることをレビューしているか
- Console exporterを本番設定に残していないか
channelData.tenant.idfallbackを前提にtenant idの確認をしているか
まとめ：Teamsボットの監視設計を見直すタイミング
今回のMicrosoft Teams documentation updateは、Teamsボット／エージェントの運用監視を強化するための更新です。turn、middleware、handler、auth.outbound、conversation_clientといったspanにより、Teamsボットの処理を段階ごとに追えるようになります。さらにteams.* metricsにより、受信数、処理時間、エラー、外向き呼び出しを継続的に監視できます。
Agent365を使うチームにとっては、BaggageBuilderによる必須属性の付与が特に重要です。ただし、baggageだけで公開要件が満たされるわけではありません。InvokeAgentScope、InferenceScope、ExecuteToolScopeを含め、Agent365側のvalidation要件と照らし合わせて実装を確認してください。
次に取るべき行動はシンプルです。まず自社のTeamsボットがteams.netのCore / Apps層を使っているかを確認し、検証環境でOpenTelemetryのsource / meter登録を追加します。そのうえで、1件のテストメッセージを送ってturnから返信送信までのspan treeが見えるかを確認してください。Agent365対応が必要な場合は、同じ検証でbaggage属性と必須scopeの不足を洗い出すのが最短ルートです。
コメント