Using Activities

Activities are the main object sent and received by your agent. This back-and-forth interaction uses something commonly referred to as the Activity Protocol.

Your agent listens for events that are types of Activities created between the client and your agent. The Microsoft 365 Agents SDK has Channel Adapters that translate the different channel languages into Activities. Be aware that typically channels will have the 'Message' type as a core method of communication, and beyond that it is channel dependent what types of activities are supported based on the client.

Activities are used in two places:

1. When listening for events. The agent listens for Activities. In the following example, the agent listens for an Activity of type Message that can contain any type of text, media, and so on.

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

1. When sending responses. Developers can construct a Message using MessageFactory and send it in the SendActivityAsync method.

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

Activity types

The Agents SDK supports various activity types, each with its own purpose. Here are some of the most common activity types.

Message

Message is the most common type of activity. A message activity is used to exchange text, media, and rich content between the bot and the user. For example, a user sends a text message to the agent, and the agent replies with a text message.

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

Conversation Update

A conversation update activity is used to notify the agent when members are added to or removed from a conversation. For example, a user joins a group chat, and the agent is notified of the new participant.

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);
            }
        }
    }
});

Typing

A typing activity indicates that the sender is actively typing a message. For example, the agent sends a typing indicator to show that it's processing the user's message.

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

End of Conversation

An end of conversation activity indicates that the conversation is finished. For example, the agent sends an end-of-conversation activity when it completes its interaction with the user. This activity type is useful if you want to specifically send prebuilt feedback forms or show that a conversation is done.

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

Custom Event

A custom event activity lets you send and receive events. Events are lightweight messages that can carry custom data. For example, the agent sends an event to trigger a specific action in the client application.

    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);
        }
    });

There are other types of activities that are specific to clients. For example, Microsoft Teams includes a Message Reaction activity. Custom apps or websites can also have their own events. To interact with these events, developers can use the customEvent activity type.