アクティビティプロトコルについて

アクティビティプロトコルは、多くの Microsoft SDK、サービス、クライアントで Microsoft 全体で使用される通信プロトコルと標準プロトコルです。これには、Microsoft 365 Copilot、Microsoft Copilot Studio、Microsoft 365 Agents SDK が含まれます。アクティビティプロトコルは、 Activity の形状と、メッセージ、イベント、相互作用がチャネルからコード、およびその間のあらゆる場所にどのように流れるかを定義します。エージェントは、1 つ以上のチャネルに接続してユーザーと対話し、他のエージェントと連携できます。アクティビティプロトコルは、Microsoft とサードパーティのクライアントを含め、使用しているクライアント間の通信プロトコルを標準化するため、使用しているチャネルごとにカスタムロジックを作成する必要はありません。

アクティビティとは

Activityは、ユーザーとエージェント間の相互作用を表す構造化 JSON オブジェクトです。アクティビティは単なるテキストベースのメッセージではなく、複数のユーザーをサポートするクライアントへのユーザーの参加や退出、インジケーターの入力、ファイルのアップロード、カードアクション、開発者が独自に設計するカスタムイベントなど、さまざまな種類の操作を含めることができます。

すべてのアクティビティには、次に関するメタデータが含まれています。

誰が送信したか (差出人)
誰が受け取る必要がありますか (受信者)
会話コンテキスト
送信元のチャネル
相互作用の種類
ペイロードデータ

アクティビティ・スキーマ - キープロパティ

この仕様では、Activity protocol: Activity protocol - Activity を定義します。アクティビティプロトコルで定義されている主要なプロパティの一部を次に示します。

プロパティ	Description
`Id`	通常、チャネルから発信された場合にチャネルによって生成されます。
`Type`	この型は、アクティビティの意味 (メッセージの種類など) を制御します
`ChannelID`	`ChannelID`は、アクティビティが発生したチャネルを参照します。たとえば、 `msteams`と指定します。
`From`	アクティビティの送信者 (ユーザーまたはエージェントの場合があります)
`Recipient`	アクティビティの目的の受信者
`Text`	メッセージのテキストコンテンツ
`Attachment`	カード、ファイルの画像などの豊富なコンテンツ

アクティビティデータへのアクセス

開発者は、アクティビティ内のデータにアクセスして、 TurnContext オブジェクトからアクションを完了する必要があります。

TurnContext クラスは、Microsoft 365 Agents SDK の各言語バージョンで確認できます。

注

この記事のコードスニペットでは C# を使用します。 JavaScript バージョンと Python バージョンの構文と API 構造は似ています。

TurnContextは、Microsoft 365 Agents SDK のすべての会話ターンで使用される重要なオブジェクトです。受信アクティビティ、応答を送信するためのメソッド、会話状態管理、および会話の 1 つのターンを処理するために必要なコンテキストへのアクセスを提供します。コンテキストを維持し、適切な応答を送信し、クライアント/チャネルでユーザーと効果的にやり取りするために使用されます。エージェントがチャネルから新しいアクティビティを受信するたびに、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 クラス内では、一般的に使用されるキー情報には次のものが含まれます。

アクティビティ: アクティビティから情報を取得する主な方法
アダプター: アクティビティを作成したチャネルアダプター
TurnState: そのターンの状態

アクティビティの種類

アクティビティの種類は、クライアント、ユーザー、およびエージェント間のアクティビティの残りの部分で何が必要か、予期されるかを定義するため、重要です。

メッセージ

一般的なアクティビティの種類として「メッセージ」のタイプがあります。このタイプには、テキスト、添付ファイル、推奨されるアクションなど、いくつかの一般的な用途が含まれます。

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

メンバーが会話に参加または会話を離れると、の 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.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

イベント

のActivityの種類は、チャネルまたはクライアントがエージェントに構造化データを送信できるようにするカスタムイベントであり、Activityペイロード構造では事前に定義されていません。

特定の Event 型のメソッド/ルートハンドラーを作成し、次に基づいて目的のロジックを管理する必要があります。

Name - クライアント値 - 通常は JSON オブジェクトであるイベントペイロードからのイベント名または識別子

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

のActivityの種類は、メッセージだけでなく、コマンドまたは操作を実行するためにクライアントがエージェントに呼び出している特定の種類のアクティビティです。これらの種類のアクティビティの例は、 task/fetch と task/submitのMicrosoft Teamsで一般的です。すべてのチャネルでこれらの種類のアクティビティがサポートされているわけではありません。

Typing

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 は一般的に有効期間が短いので、そこに留まるとは考えないでください。そのため、後でこれを参照する必要がある場合は、独自のストレージに移動することが重要です。

引用

添付ファイルと引用文献が同じオブジェクトの種類でないことを知る必要があります。引用は、Microsoft Teamsなどのクライアントによって独自の方法で処理され、の Activityを使用します。activity.Entities.Addと共に追加し、クライアントに基づいて特定のEntity定義を持つ新しいCitation オブジェクトを追加できます。 JSON オブジェクトとしてシリアル化され、その後、クライアントでのレンダリング方法に基づいてクライアントがデシリアライズします。基本的に、添付ファイルはメッセージであり、引用文献は添付ファイルを参照でき、EntitiesペイロードのActivityで送信される別のオブジェクトです。

チャネル固有の考慮事項

Microsoft 365 Agents SDK は"ハブ" として構築されており、開発者は、サポートしているクライアントを含め、任意のクライアントと連携できるエージェントを作成し、開発者が同じフレームワークを使用して独自のチャネルアダプターを構築するためのツールを提供できます。これにより、エージェントに関しては開発者の幅が広がり、そのハブに接続するためのクライアントの拡張性が提供されます。これは、Microsoft Teams、Slack などの 1 つ以上のクライアントである可能性があります。

チャネルによって機能と制限が異なり、一般的なクライアントを操作するときの考慮事項の概要を次に示します。

channelIdの Activity プロパティを調べることで、アクティビティを受信したチャネルを確認できます。

チャネルには、すべてのチャネルの汎用 Activity ペイロードに準拠していない特定のデータが含まれており、TurnContext からアクセスできます。Activity.ChannelData 。具体的には、コードで使用するために変数にキャストします。

Microsoft Teams

高度な機能を備えた豊富なアダプティブカードをサポート
メッセージの更新と削除をサポートします
Teams の機能 (メンション、会議情報など) の特定のチャネルデータがある
タスクモジュールの呼び出しアクティビティをサポートします

Microsoft 365 Copilot

主にメッセージアクティビティに重点を置いた
応答での引用と参照をサポートします
ストリーミング応答が必要
リッチカード/アダプティブカードの制限付きサポート

WebChat/DirectLine

Web チャットは、エージェントが HTTPS を介して通信するために使用される HTTP プロトコルです

すべてのアクティビティの種類を完全にサポート
カスタムチャネルデータをサポート

サードパーティのチャネル

これには、Slack、Facebook などが含まれます。

特定のアクティビティの種類に対するサポートが制限されている可能性があります
カードのレンダリングが異なるか、サポートされていない可能性があります
常に特定のチャネルのドキュメントを確認する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-19