Microsoftの「Understanding Activity Protocol」で最初に押さえるべき結論は、Activity Protocolが単なる新機能名ではなく、エージェント、ユーザー、チャネル間のやり取りをActivityという共通のJSON構造で扱うための通信ルールだという点です。Microsoft 365 Copilot、Microsoft Copilot Studio、Microsoft Teams、Microsoft 365 Agents SDKをまたいで利用されるため、管理者は「どのチャネルで何を許可するか」、開発者は「Activityの型・プロパティ・チャネル差分をどう処理するか」を確認する必要があります。(Microsoft Learn)
特に2026年5月22日付のMicrosoft 365 Agents SDK for Python v1.0.0リリースでは、Teams SSO Consent、Teams拡張、Copilot Web OAuth、チャネル別Typing Indicator、Proactive Telemetryなど、Activityを中心にした実装・運用に関わる周辺機能が整理されています。なお、Microsoft Learnの「Understanding Activity Protocol」ページ自体は2026年4月29日更新として表示されているため、日付を厳密に扱う場合はLearn本文とSDKリリースノートを分けて確認すると安全です。(Microsoft Learn) (GitHub)
Activity Protocolはエージェント通信の「共通語」
Activity Protocolは、ユーザーの発言、ボタン操作、ファイル添付、会話参加、入力中表示、カスタムイベントなどをActivityとして表現します。Microsoft Learnでは、Activity ProtocolがMicrosoft 365 Copilot、Microsoft Copilot Studio、Microsoft Teams、Microsoft 365 Agents SDKで使われ、チャネルから開発者のコードまでメッセージやイベントが流れる構造を定義すると説明されています。(Microsoft Learn)
従来の感覚でいうと、Teams用、Copilot用、Webチャット用にそれぞれ別々の受信処理を書くのではなく、まずActivityとして受け取り、typeやchannelId、from、recipient、text、attachmentsなどを見て処理を分岐する考え方です。これにより、複数チャネル対応のエージェントを作るときに、実装の共通部分を増やしやすくなります。
ただし「共通化される」といっても、すべてのチャネルで同じ体験が保証されるわけではありません。Teams、Microsoft 365 Copilot、Web Chat、非Microsoftチャネルでは、カード表示、Invoke、Typing、引用、添付ファイルの扱いに差があります。Activity Protocolは共通の器であり、チャネル固有の制約を消すものではない点が重要です。(Microsoft Learn)
何が変わるのか
今回のポイントは、Activity Protocolそのものが突然別物になるというより、Microsoft 365 Agents SDKを使ったエージェント開発で「Activityを中心に設計する」前提がより明確になったことです。
| 確認ポイント | 変化の内容 | 実務上の影響 |
|---|---|---|
| 通信モデル | ユーザー、エージェント、チャネル間のやり取りをActivityとして扱う | チャネルごとの独自処理を減らし、共通ハンドラーを設計しやすくなる |
| 対象サービス | Microsoft 365 Copilot、Copilot Studio、Teams、Microsoft 365 Agents SDKで利用 | TeamsだけでなくCopilotやCopilot Studio連携も見据えた設計が必要 |
| 開発単位 | TurnContextから受信Activityを読み取り、応答Activityを送信する | 1回の会話ターンごとに処理・状態管理・応答を整理する必要がある |
| チャネル差分 | Teams、Copilot、Web Chat、非Microsoftチャネルで対応機能が異なる | 本番展開前にチャネル別のテストマトリクスが必要 |
| SDK周辺機能 | Python SDK v1.0.0でTeams SSO Consent、Teams拡張、Copilot Web OAuth、チャネル別Typing Indicatorなどが追加・整理 | 認証、Teams拡張、Copilot Web、Typing表示を使う実装は移行確認が必要 |
Microsoft 365 Agents SDK for Python v1.0.0のリリースノートでは、BotFramework由来のDialogs Library、Teams SSO Consent Requiredフロー、Teams拡張の更新、msteams:copilot-webのような複合チャネルIDを考慮したCopilot Web OAuth Base-Channel対応、チャネル別Typing Indicator、Proactive Telemetryなどが挙げられています。(GitHub)
影響を受ける対象者
Activity Protocolの影響は、コードを書く開発者だけに限られません。Microsoft 365環境でエージェントを展開する場合、管理者、セキュリティ担当、運用担当も確認すべき範囲があります。
| 対象者 | 確認すべきこと |
|---|---|
| Microsoft 365管理者 | Teams、Copilot、Copilot Studioなど、どのチャネルでエージェントを使わせるか |
| Teams管理者 | Teamsアプリ、SSO、メッセージ拡張、タスクモジュール、会議イベントの利用範囲 |
| 開発者 | Activityスキーマ、TurnContext、Activity Type、添付ファイル、引用、channelData |
| セキュリティ担当 | 添付ファイルURL、認証、同意、ログ、個人情報、外部チャネル連携 |
| 運用担当 | チャネル別の障害切り分け、Activityログ、バージョン差分、段階展開 |
特に社内向けエージェントでは、Teamsで動けば十分とは限りません。将来的にMicrosoft 365 CopilotやCopilot Studio、Web Chatへ展開する可能性があるなら、初期設計の段階でActivity Protocolを前提にしておくほうが手戻りを減らせます。
Activityスキーマで見るべき主要プロパティ
Activity Protocolでは、やり取りの内容だけでなく、送信者、受信者、会話コンテキスト、発生元チャネル、インタラクション種別、ペイロードデータといったメタデータをActivityに含めます。Microsoft Learnでは、Id、Type、ChannelID、From、Recipient、Text、Attachmentなどが主要プロパティとして紹介されています。(Microsoft Learn)
| プロパティ | 役割 | 確認ポイント |
|---|---|---|
id | Activityの識別子 | 多くの場合チャネル側で生成される。アプリ側で勝手に永続IDとして扱わない |
type | Activityの種類 | message、event、invoke、typingなどで処理を分ける |
channelId | 発生元チャネル | msteamsなどを見て、チャネル固有処理を判断する |
from | 送信者 | ユーザーかエージェントかを判定する |
recipient | 受信者 | 応答先の制御やメンション処理で使う |
text | メッセージ本文 | 通常のテキスト会話で中心になる |
attachments | カード、画像、ファイルなど | URLの有効期限や保存先、権限を確認する |
entities | メンション、引用などの追加情報 | 引用は添付ファイルとは別物として扱う |
channelData | チャネル固有データ | Teams固有情報などを扱えるが、他チャネルでは同じ形とは限らない |
GitHub上のActivity Protocol仕様では、ActivityオブジェクトはJSONとしてシリアライズ可能であること、typeフィールドがActivityの意味を制御すること、未知の追加フィールドを受信側が受け入れる前提が示されています。実装では「知らないフィールドが来たら落ちる」設計ではなく、必要なフィールドだけを安全に読み取り、未知の値にはフォールバックする作りが現実的です。(GitHub)
開発者が確認すべき実装ポイント
TurnContextは1ターン限りの処理単位として扱う
Microsoft 365 Agents SDKでは、チャネルから新しいActivityを受け取るたびにTurnContextが作成され、登録済みのハンドラーやメソッドに渡されます。TurnContextは1回の会話ターンの間だけ存在し、ターン終了後に破棄されます。(Microsoft Learn)
つまり、TurnContextそのものを長期保存して後から使う設計は避けるべきです。後続処理やプロアクティブメッセージで必要になる情報は、会話参照、ユーザーID、チャネルID、業務上必要な状態などに分けて保存します。
var messageText = turnContext.Activity.Text;
var channelId = turnContext.Activity.ChannelId;このように、まずturnContext.Activityから必要な情報を取り出し、Activity.TypeとChannelIdを起点に処理を分岐するのが基本です。
Activity Typeごとにハンドリングを分ける
Activityには複数の種類があります。Microsoft Learnでは、代表的なActivity TypeとしてMessage、ConversationUpdate、Event、Invoke、Typingが挙げられています。(Microsoft Learn)
| Activity Type | 主な用途 | 実装時の注意点 |
|---|---|---|
Message | 通常のテキスト、添付、候補アクション | 最も基本。添付ファイルもMessage Activityに含まれる |
ConversationUpdate | メンバー参加・退出など | すべてのクライアントが対応するわけではない。Teamsでは利用される |
Event | クライアントやチャネルが送るカスタムイベント | nameとvalueを見て独自処理を作る |
Invoke | コマンドや操作実行 | Teamsのtask/fetch、task/submitなどで使われる。未対応チャネルもある |
Typing | 入力中表示 | すべてのクライアントで使えるわけではなく、Microsoft 365 CopilotはTyping Activityをサポートしない |
失敗しやすいのは、すべてをMessageとして処理してしまうパターンです。たとえばTeamsのタスクモジュールやメッセージ拡張ではInvokeが関係するため、通常メッセージだけを想定した実装では期待通りに動かないことがあります。
添付ファイルは「受け取ったら終わり」ではない
Activity Protocolでは、ファイルやカードなどのリッチコンテンツは添付ファイルとして扱われます。Microsoft Learnでは、添付ファイルの実体を取得するためにクライアントが提供したURLを使い、必要に応じて自分のストレージへ移すことが説明されています。また、これらのURLは短命であることが多く、後から参照し続けられる前提にしないよう注意が示されています。(Microsoft Learn)
実務では、次のように扱うと安全です。
- 添付ファイルの
contentUrlをログにそのまま残さない - 必要なファイルは早めに取得し、組織で管理するストレージへ保存する
- 保存時にアクセス権、保持期間、削除ポリシーを決める
- ウイルススキャンやファイル種別制限をアプリ側でも検討する
- ファイル取得失敗時のユーザー向けエラー文を用意する
引用と添付ファイルを混同しない
Microsoft Learnでは、AttachmentとCitationは同じオブジェクト型ではないと説明されています。Teamsなどのクライアントでは、引用はActivityのEntitiesプロパティを通じて扱われ、添付ファイルとは別の情報として処理されます。(Microsoft Learn)
RAG構成のエージェントや社内ドキュメント検索エージェントでは、この違いが重要です。回答の根拠として文書を示したい場合、単にファイルを添付するだけでは「引用」としてクライアントに表示されない可能性があります。チャネルごとの引用表示仕様を確認し、Entitiesに必要な情報を入れる設計にしましょう。
管理者が確認すべき設定・展開ポイント
対象チャネルを先に決める
Activity Protocolは複数チャネル対応をしやすくしますが、管理上は「どのチャネルで使うか」を先に決める必要があります。Teams、Microsoft 365 Copilot、Copilot Studio、Web Chat、非Microsoftチャネルでは、使えるActivity Typeやカード表示、認証、引用、添付ファイルの扱いが異なります。(Microsoft Learn)
展開前に、少なくとも次のような対応表を作ると判断しやすくなります。
| チャネル | 確認項目 |
|---|---|
| Microsoft Teams | Adaptive Cards、メッセージ更新・削除、メンション、会議情報、Invoke、SSO |
| Microsoft 365 Copilot | メッセージ中心の処理、引用、ストリーミング応答、カード制限 |
| Copilot Studio | 接続方式、認証、環境、DLP、既存トピックやコネクタとの関係 |
| Web Chat / DirectLine | HTTPS通信、カスタムchannelData、Activity Type全般 |
| 非Microsoftチャネル | カード表示、Typing、添付、認証、個別ドキュメントの確認 |
認証と同意の流れをテストする
Microsoft 365 Agents SDK for Python v1.0.0では、Teams SSOのConsent Requiredフロー対応や、Copilot Web OAuth Base-Channel対応が追加されています。特にmsteams:copilot-webのような複合チャネルIDを受け取るケースでは、OAuthトークン交換でベースチャネルを使うためのオプションが追加されています。(GitHub)
管理者と開発者は、次の観点で確認しましょう。
- 初回利用時に同意画面が想定通り表示されるか
- Teams上とCopilot Web上で認証結果が変わらないか
- 条件付きアクセスや多要素認証の影響を受けるか
- 同意が必要な権限を過剰に要求していないか
- 失敗時にユーザーへ分かりやすい案内を返せるか
段階展開に向いたログを残す
Activity Protocol対応の運用では、単に「エラーが出た」だけでは切り分けが難しくなります。最低限、type、channelId、処理結果、例外種別、応答有無、ユーザーに返したメッセージ種別は追跡できるようにしましょう。
ただし、Activityには本文、添付ファイル情報、ユーザー情報が含まれる可能性があります。ログに全文を残すのではなく、個人情報や機密情報を除外・マスキングし、必要なメタデータ中心に記録する設計が現実的です。
移行・展開で失敗しやすいポイント
| 失敗例 | 起きる問題 | 対策 |
|---|---|---|
| Teamsで動いた処理をCopilotにもそのまま展開する | Typing、カード、引用、ストリーミングで差が出る | チャネル別に対応機能を確認する |
Activity.Typeを見ずにすべてMessage扱いする | InvokeやEventが処理されない | Typeごとのハンドラーを用意する |
| 添付ファイルURLを長期保存する | 後日アクセスできない、セキュリティ上危険 | 必要なファイルは自社管理ストレージに移す |
channelDataに依存しすぎる | 他チャネルで動かない | 共通項目とチャネル固有項目を分離する |
| 引用をAttachmentとして実装する | クライアント側で引用として表示されない | Entitiesでの引用表現を確認する |
| 複合チャネルIDを想定しない | Copilot WebやTeams連携時のOAuthで問題が出る可能性 | channelIdの形式を固定文字列だけで決め打ちしない |
TurnContextを後続処理に使い回す | ターン終了後の処理で破綻する | 必要な参照情報だけ保存する |
特に注意したいのは、channelIdの決め打ちです。2026年5月22日のSDKリリースノートでは、msteams:copilot-webのような複合チャネルIDに関連するOAuth対応が明記されています。文字列が完全にmsteamsでなければTeams系ではない、といった単純な判定は避けたほうが安全です。(GitHub)
展開前チェックリスト
本番導入前には、次の順番で確認すると抜け漏れを減らせます。
- 利用するSDKの言語とバージョンを確認する
Activity.Typeごとの処理一覧を作るchannelIdごとの対応表を作る- Teams、Copilot、Copilot Studioなど対象チャネルで実機テストする
- 添付ファイルの取得、保存、削除、スキャン方針を決める
- 引用表示が必要な場合は
Entitiesの扱いを検証する - SSO、OAuth、同意画面、条件付きアクセスをテストする
- カード表示やInvokeが未対応のチャネル向けに代替応答を用意する
- ログに本文や添付URLを残しすぎないようにする
- まず限定ユーザーで段階展開し、Activityログから失敗パターンを確認する
このチェックリストで重要なのは、開発者だけで完結させないことです。Teamsアプリの許可、Copilot利用ポリシー、添付ファイルの扱い、認証同意、ログ保管は、管理者やセキュリティ担当と一緒に確認する必要があります。
まず何から対応すべきか
既存のTeams BotやCopilot Studio連携をMicrosoft 365 Agents SDKへ寄せていく場合、最初にやるべきことはコードの書き換えではありません。まず、現在のエージェントが受け取っている入力と返している応答を、Activity単位で棚卸しします。
具体的には、次の4点を表にします。
| 棚卸し項目 | 例 |
|---|---|
| 受け取るActivity Type | Message、Invoke、Event、ConversationUpdate |
| 利用するプロパティ | Text、Attachments、Entities、ChannelData |
| 対象チャネル | Teams、Microsoft 365 Copilot、Copilot Studio、Web Chat |
| チャネル固有処理 | Teamsメンション、タスクモジュール、Copilot引用、ストリーミング |
この棚卸しができれば、移行時に「共通化できる処理」と「チャネル別に残す処理」が見えてきます。Activity Protocolの価値は、すべてを無理に同じ処理へ押し込むことではなく、共通部分と差分を明確に分けられる点にあります。
MicrosoftのUnderstanding Activity Protocolは、Microsoft 365エージェント開発の土台を理解するための重要な公式情報です。管理者は対象チャネル、権限、認証、添付ファイル、ログを確認し、開発者はActivity、TurnContext、Activity Type、channelData、引用と添付の違いを押さえてください。次に取るべき行動は、既存または新規エージェントの入出力をActivity単位で整理し、チャネル別のテスト表を作ることです。それが、TeamsだけでなくMicrosoft 365 CopilotやCopilot Studioまで見据えた、安全で拡張しやすい展開につながります。
コメント