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

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

アクティビティとは

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

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

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

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

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

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

アクティビティデータにアクセスする

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

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

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

TurnContext は、Microsoft 365 エージェント 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: そのターンの状態

アクティビティの種類

アクティビティの種類は、アクティビティの残りの部分がクライアント、ユーザー、およびエージェント間で必要とするもの、または期待するものを定義します。

これらには次のものが含まれます。

メッセージ
会話更新
Event
Invoke
Typing

メッセージ

アクティビティの一般的な種類は、の種類です。この 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);
});

会話更新

メンバーが会話に参加または会話を離れると、の 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);
            }
        }
    }
})

Events

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

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

名前: クライアントからのイベント名または識別子
値: 通常は 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

の種類は、クライアントがエージェントを呼び出してコマンドまたは操作を実行する特定の種類のアクティビティです。単なるメッセージではありません。これらの種類のアクティビティの例は、 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 は一般的に有効期間が短いので、URL が長期間有効であると想定しないようにすることも重要です。この制限は、後で内容を参照する必要がある場合に、独自のストレージへの移行が重要である理由です。

引用

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

チャネル固有の考慮事項

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

チャネルによって、機能と制限が異なります。

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

チャネルには、すべてのチャネルの汎用 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 について

フィードバック

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

Last updated on 2026-04-29