アクティビティプロトコルは、マイクロソフトの多くのSDK、サービス、クライアントで使用されている標準通信プロトコルです。 アクティビティプロトコルはMicrosoft 365 Copilot、Microsoft Copilot Studio、Microsoft Teams、Microsoft 365 エージェント SDKで使用されています。 アクティビティ プロトコルは、Activity の構造と、メッセージ、イベント、およびインタラクションがチャネルからコード、そしてその間のあらゆる場所へどのように流れるかを定義します。 エージェントは複数のチャネルに接続して、ユーザーとやり取りしたり、他のエージェントと協働することができます。 アクティビティ プロトコルは、Microsoftクライアントや非Microsoftクライアントを含む各種クライアントとの通信プロトコルを標準化するため、各チャネルごとに独自のロジックを作成する必要がありません。
Activity とは何ですか?
Activity とは、ユーザーとエージェント間のあらゆる対話を表す構造化されたJSONオブジェクトです。 アクティビティはテキストベースのメッセージに限定されません。 これには、ユーザーが参加または退出するイベント(複数ユーザー対応クライアントの場合)、タイピングインジケーター、ファイルアップロード、カードアクション、開発者が設計するカスタムイベントなど、さまざまな種類の対話が含まれます。
各アクティビティには次のようなメタデータが含まれています:
- 送信したユーザー (from)
- 受信すべきユーザー (受信者)
- 会話のコンテキスト
- 発信元のチャンネル
- 対話の種類
- ペイロード データ
アクティビティスキーマ - 主要プロパティ
この仕様では、アクティビティ プロトコル「アクティビティ プロトコル - アクティビティ」を定義します。 アクティビティプロトコルで定義されている主なプロパティの一部は以下の通りです。
| プロパティ | 内容 |
|---|---|
Id |
通常、チャネル起点の場合にチャネルによって生成されます |
Type |
タイプはアクティビティの意味を決定します。たとえば、メッセージタイプなどです |
ChannelID |
ChannelID は、そのアクティビティが発生したチャネルを参照します。 例: msteams。 |
From |
アクティビティの送信者(ユーザーまたはエージェント) |
Recipient |
アクティビティの対象となる受取人 |
Text |
メッセージのテキスト コンテンツ |
Attachment |
カードやファイルの画像などのリッチコンテンツ |
アクティビティデータにアクセスする
TurnContext オブジェクトでアクションを実行するためには、開発者はアクティビティ内のデータにアクセスする必要があります。
Microsoft 365 エージェント SDK の各言語バージョンには、TurnContext クラスが含まれています。
- .NET: TurnContext
- Python: TurnContext
- JavaScript: TurnContext
注意
この記事のコードスニペットはC#を使用しています。 JavaScript版とPython版の構文とAPI構造は似ています。
TurnContext は、Microsoft 365 エージェント SDK の各会話ターンで使用される重要なオブジェクトです。 受信活動、応答送信方法、会話の状態管理、そして単一の会話ターンを処理するために必要なコンテキストへのアクセスを提供します。 文脈を維持し、適切な応答を送り、クライアントやチャネルでユーザーと効果的に交流するために活用しましょう。 エージェントがチャネルから新しいアクティビティを受信するたびに、Agents SDK は新しい TurnContext インスタンスを作成し、登録済みのハンドラーやメソッドに渡します。 このコンテキストオブジェクトは、1ターンの間のみ存在し、ターン終了時に破棄されます。
ターンとは、クライアントから送信されたメッセージが、あなたのコードに到達するまでの往復する体験を指します。 コードはそのデータを処理し、必要があれば応答を返してターンを完了させることもできます。 その往復は以下の手順に分けられます。
受信アクティビティ: ユーザーがメッセージを送信するか、アクティビティを発生させるアクションを実行します。
あなたのコードはアクティビティを受信し、エージェントは
TurnContextを使ってそれを処理します。あなたのエージェントが 1 つまたは複数のアクティビティを送信します。
ターンが終了し、
TurnContextは破棄されます。
TurnContext からのデータへアクセスします。たとえば、次のとおりです。
var messageText = turnContext.Activity.Text;
var channelID = turnContext.Activity.ChannelId;
このコードスニペットはターン全体の例を示しています。
agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
var userMessage = turnContext.Activity.Text;
var response = $"you said: {userMessage}";
await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});
TurnContext クラス内で一般的に使用される重要な情報には、以下が含まれます。
アクティビティの種類
アクティビティのタイプによって、クライアント、ユーザー、エージェント間で必要とされる内容や期待される動作が決まります。
次が含まれます。
- Message
- ConversationUpdate
- イベント
- Invoke
- Typing (入力)
Message
一般的なアクティビティの種類としては、Activity のメッセージ タイプがあります。 この Activity タイプにはテキスト、添付ファイル、提案されたアクションが含まれます。
agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
var userMessage = turnContext.Activity.Text;
var response = $"you said: {userMessage}";
await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});
ConversationUpdate
ConversationUpdate タイプの Activity は、メンバーが会話に参加または退出した際にエージェントに通知します。 すべてのクライアントがこの通知に対応しているわけではありませんが、Microsoft Teamsは対応しています。
以下のコードスニペットは、会話の新メンバーに挨拶します:
agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
var membersAdded = turnContext.Activity.MembersAdded
if (membersAdded != null)
{
foreach (var member in membersAdded)
{
if (member.Id != turnContext.Activity.Recipient.Id)
{
await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
}
}
}
})
イベント
イベント タイプの Activity は、チャネルまたはクライアントが構造化データをエージェントに送信するために使用するカスタムイベントです。 このデータは Activity ペイロード構造にあらかじめ定義されていません。
特定の Event タイプに対してメソッドやルートハンドラを作成する必要があります。 次に、以下に基づいて目的のロジックを管理します。
agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>
{
var eventName = turnContext.Activity.Name;
var eventValue = turnContext.Activity.Value;
// custom event (E.g. a switch on eventName)
});
Invoke
Invoke タイプの Activity は、クライアントがコマンドや操作を実行する目的でエージェントに呼び出す特定の種類のアクティビティです。 メッセージだけではありません。 こうした種類の活動の例は、task/fetch および task/submit 向けの Microsoft Teams でよく見られます。 すべてのチャネルがこれらの種類のアクティビティをサポートしているわけではありません。
Typing (入力)
タイピング タイプの Activity アクティビティは、会話中に誰かがタイピングしていることを示す分類のアクティビティです。 このアクティビティは、例えばMicrosoft Teamsクライアントの人同士の会話でよく見られます。 タイピングアクティビティはすべてのクライアントでサポートされているわけではありません。 特筆すべきは、Microsoft 365 Copilot がタイピングアクティビティをサポートしていないことです。
await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken);
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken);
アクティビティの作成と送信
応答を送信するために、TurnContextはユーザーに応答を返すための複数の方法を提供します。
agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken); // uses string directly
await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken); // uses Message Factory
await turnContext.SendActivitiesAsync(activities, cancellationToken); // send multiple activities in an Activity array
}
添付ファイルを使用して作業する
エージェントは、ユーザー(または他のエージェント)が送信する添付ファイルをよく扱います。 クライアントは添付ファイルを含む Message アクティビティを送信します(これは特定の種類のアクティビティではありません)。 コードは、添付ファイル付きのメッセージを受信し、メタデータを読み取り、クライアントが提供したURLからファイルを安全に取得できるように処理する必要があります。 通常は、ファイルを自分のストレージに移します。
添付ファイルを受信するには
以下のコードは、添付ファイルを受信する方法を示しています。
agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
var activity = turnContext.Activity;
if (activity.Attachments != null && activity.Attachments.Count > 0)
{
foreach (var attachment in activity.Attachments)
{
// get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
// use the URL to securely download the attachment and complete your business logic
};
}
}
通常、添付ファイルのドキュメントを受け取るために、クライアントは認証済みの GET リクエストを送信し、実際の内容を取得します。 各アダプターにはデータを取得する方法が異なります。 たとえば、TeamsやOneDriveなどがあります。 また、これらのURLは通常有効期間が短いため、URLが長期間有効であると想定しないでください。 この制限があるため、後で内容を参照する必要がある場合は自分のストレージに移すことが重要です。
引用
Attachment と Citation は異なるオブジェクト型であることを理解しておく必要があります。 各クライアントは、Microsoft Teamsのように、Citationを異なる方法で取り扱います。 それらは、Activity の所有するエンティティのプロパティを使用しています。
activity.Entities.Add を使用して引用を追加し、クライアントに基づいて特定の Citation 定義を持つ新しい Entity オブジェクトを追加できます。 JSONオブジェクトとしてシリアライズされ、クライアント側での表示方法に応じてデシリアライズされます。 基本的に、添付ファイルはメッセージであり、引用は添付ファイルを参照することができ、Activity ペイロードの Entities で送信されるもう 1 つのオブジェクトです。
チャネル固有の考慮事項
Microsoft 365 エージェント SDK は、Microsoft がサポートするクライアントを含むあらゆるクライアントと連携できるエージェントを開発者が作成するために使用する "ハブ" として構築されています。 同じフレームワークを利用して、開発者が独自のチャネルアダプターを構築できるツールを提供します。 このアーキテクチャは、開発者にエージェントの多様性をもたらし、Microsoft TeamsやSlackなど、複数のクライアントがそのハブに接続できる拡張性を提供します。
チャンネルによって機能や制限は異なります。
Activity の channelId プロパティを調べることで、アクティビティを受信したチャネルを判別できます。
チャネルには、すべてのチャネルに共通する一般的な Activity ペイロードに準拠しない特定のデータが含まれます。 このデータは TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) プロパティから取得し、変数にキャストしてコードで利用できます。
以下のセクションでは、主要なクライアントを扱う際の留意点をまとめます。
Microsoft Teams
- 高度な機能を備えたリッチなアダプティブ カードをサポートします。
- メッセージの更新や削除をサポートします。
- Teamsの機能(メンションや会議情報など)に関連した特定のチャネルデータを保持しています。
- タスクモジュールの呼び出しアクティビティをサポートします。
Microsoft 365 Copilot
- 主にメッセージアクティビティに重点を置いています。
- 応答で引用や参照に対応します。
- ストリーミング応答が必要です。
- リッチカードとアダプティブ カードのサポートは制限されています。
Web チャット/DirectLine
Web チャットは、エージェントが HTTPS 経由で通信するために使用できる HTTP プロトコルです。
- すべてのアクティビティタイプが完全にサポートされています。
- カスタムチャンネルデータをサポートしています。
Microsoft 以外のチャネル
これらのチャンネルにはSlackやFacebookなどが含まれます。
- 特定のアクティビティタイプのサポートが限定される場合があります。
- カードレンダリングが異なっていたり、サポートされていない場合があります。
- 必ず各チャンネルのドキュメントを確認してください。
次の手順
- AgentApplication について確認する