アクティビティの使用

2025-08-27

Activities は、エージェントによって送受信されるメインオブジェクトです。この前後の対話では、一般的に Activity Protocolと呼ばれるものを使用します。

エージェントは、クライアントとエージェントの間で作成 Activities 種類のイベントをリッスンします。 Microsoft 365 Agents SDK には、さまざまなチャネル言語をActivitiesに変換するChannel Adaptersがあります。通常、チャネルは通信のコアメソッドとして "Message" 型を持ち、それ以上に、クライアントに基づいてサポートされるアクティビティの種類はチャネルによって異なっていることに注意してください。

アクティビティは、次の 2 つの場所で使用されます。

イベントをリッスンする場合。エージェントは Activitiesをリッスンします。次の例では、エージェントは、任意の種類のテキストやメディアなどを含むことができるMessage型のActivityをリッスンします。

    agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
    {
        // custom logic here
    });

応答を送信する場合。開発者は、MessageFactoryを使用してMessageを構築し、SendActivityAsync メソッドで送信できます。

    await turnContext.SendActivityAsync(MessageFactory.Text({response}"), cancellationToken);

アクティビティの種類

Agents SDK では、それぞれ独自の目的を持つさまざまなアクティビティの種類がサポートされています。最も一般的なアクティビティの種類を次に示します。

メッセージ

メッセージは最も一般的なアクティビティの種類です。メッセージアクティビティは、ボットとユーザーの間でテキスト、メディア、リッチコンテンツを交換するために使用されます。たとえば、ユーザーはテキストメッセージをエージェントに送信し、エージェントはテキストメッセージで応答します。

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))

会話の更新

会話更新アクティビティは、メンバーが会話に追加または会話から削除されたときにエージェントに通知するために使用されます。たとえば、ユーザーがグループチャットに参加すると、エージェントに新しい参加者が通知されます。

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext, turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded;
    if (membersAdded != null && membersAdded.Any())
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome to the chat, {member.Name}!"), cancellationToken);
            }
        }
    }
});

タイピング

入力アクティビティは、送信者がメッセージをアクティブに入力していることを示します。たとえば、エージェントは、ユーザーのメッセージを処理していることを示す入力インジケーターを送信します。

agent.OnActivity(ActivityTypes.Typing, async (turnContext, turnState, cancellationToken) =>
{
    Console.WriteLine("User is typing...");
    await Task.CompletedTask;
});

会話の終了

会話の終了アクティビティは、会話が終了したことを示します。たとえば、エージェントは、ユーザーとの対話が完了すると、会話の終了アクティビティを送信します。このアクティビティの種類は、事前構築済みのフィードバックフォームを具体的に送信したり、会話が完了したことを示したりする場合に便利です。

    agent.OnActivity(ActivityTypes.EndOfConversation, async (turnContext, turnState, cancellationToken) =>
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Goodbye!"), cancellationToken);
    });

カスタムイベント

カスタムイベントアクティビティを使用すると、イベントを送受信できます。イベントは、カスタムデータを伝達できる軽量メッセージです。たとえば、エージェントは、クライアントアプリケーションで特定のアクションをトリガーするイベントを送信します。

    agent.OnActivity(ActivityTypes.Event, async (turnContext, turnState, cancellationToken) =>
    {
        var eventActivity = turnContext.Activity.AsEventActivity();
        if (eventActivity.Name == "customEvent")
        {
            var value = eventActivity.Value?.ToString();
            await turnContext.SendActivityAsync(MessageFactory.Text($"Received custom event with value: {value}"), cancellationToken);
        }
    });

クライアントに固有の他の種類のアクティビティがあります。たとえば、Microsoft Teamsには Message Reaction アクティビティが含まれます。カスタムアプリまたは Web サイトには、独自のイベントを含めることもできます。これらのイベントを操作するために、開発者は customEvent アクティビティの種類を使用できます。

次の方法で共有