Понимание протокола активности

Протокол активности — это стандартный протокол коммуникации используемый в Microsoft во многих SDK, сервисах и клиентах Microsoft. Протокол активности используется Microsoft 365 Copilot, Microsoft Copilot Studio и Пакет SDK агентов Microsoft 365. Протокол активности определяет структуру Activity и то, как сообщения, события и взаимодействия переходят из канала в ваш код и в другие места между ними. Агенты могут подключаться к одному или нескольким каналам для взаимодействия с пользователями и работы с другими агентами. Протокол активности стандартизирует протокол связи с любым клиентом, с которым вы работаете, включая клиентов Microsoft и не из Microsoft, чтобы не создавать собственную логику для каждого канала.

Что такое занятие?

An Activity — это структурированный JSON-объект, который представляет любое взаимодействие между пользователем и вашим агентом. Активности не ограничиваются только текстовыми сообщениями. Они могут включать различные типы взаимодействия, такие как присоединение пользователя или уход для клиентов с поддержкой нескольких пользователей, индикаторы набора информации, загрузка файлов, действия с картами и кастомные события, разработанные разработчиками.

Каждое действие включает метаданные о:

• Кто его отправил (от)
• Кто должен его получить (получатель)
• Контекст разговора
• Канал, откуда он происходил
• Тип взаимодействия
• Данные полезной нагрузки

Схема активности — ключевые свойства

Эта спецификация определяет Протокол активности: Протокол активности — Активность. Некоторые ключевые свойства, определённые в протоколе активности, включают:

Данные о активности доступа

Чтобы выполнить действия объекта TurnContext , разработчикам необходимо получить доступ к данным внутри активности.

В каждой языковой версии Пакет SDK агентов Microsoft 365 можно найти класс TurnContext:

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

TurnContext — важный объект, который используется в каждом повороте разговора в Пакет SDK агентов Microsoft 365. Он предоставляет доступ к входящей активности, методам отправки ответов, управлению состоянием разговора и контексту, необходимому для обработки одного оборота разговора. Используйте его для поддержания контекста, отправки соответствующих ответов и эффективного взаимодействия с пользователями в их клиенте или канале. Каждый раз, когда ваш агент получает новую активность от канала, SDK агента создаёт новый TurnContext экземпляр и передаёт его вашим зарегистрированным обработчикам или методам. Этот контекстный объект существует в течение одного хода, а затем избавляется от него после окончания хода.

Поворот определяется как обратный путь сообщения, отправленного клиентом, который совершает путь к вашему коду. Ваш код обрабатывает эти данные и может по желанию отправить ответ для завершения хода. Этот маршрут можно разделить на следующие этапы:

1. Входящая активность: пользователь отправляет сообщение или выполняет действие, создающее активность.

2. Ваш код получает активность, а агент обрабатывает её с помощью TurnContext.

3. Ваш агент отправляет одну или несколько активностей обратно.

4. Ход заканчивается, 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: Состояние для хода.

Типы действий

Тип активности определяет, чего остальная часть активности требует или ожидает между клиентами, пользователями и агентами.

К ним относятся:

• Message
• ОбсуждениеОбновление
• Событию
• Invoke
• Печатание

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

ОбсуждениеОбновление

Тип 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

Тип вызова — Activity это специфический тип действия, который клиент вызывает агенту для выполнения команды или операции. Это не просто послание. Примеры таких видов деятельности часто встречаются в Microsoft Teams для task/fetch и task/submit. Не все каналы поддерживают такие мероприятия.

Печатание

Тип типизации — 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 обычно недолговечны, поэтому не стоит считать, что они остаются актуальными надолго. Это ограничение объясняет, почему переезд в собственное хранилище важно, если нужно позже обратиться к содержимому.

Цитаты

Важно понимать, что Attachment и Citation — это не один и тот же тип объекта. Клиенты, такие как Microsoft Teams, обрабатывают цитаты по-своему. Они используют свойство Сущности .Activity Вы можете добавить ссылки и activity.Entities.Add добавить новый Entity объект с конкретным Citation определением в зависимости от вашего клиента. Он сериализируется как JSON-объект, который клиент затем десериализирует в зависимости от того, как он отображается в клиенте. По сути, вложения — это сообщения, а цитаты могут ссылаться на вложения и являются ещё одним объектом, отправляемым Entities из Activity полезной нагрузки.

Особенности канала

Пакет SDK агентов Microsoft 365 построен как «Хаб», который разработчики используют для создания агентов, способных работать с клиентами любой, включая клиентов, которых мы поддерживаем. Он предоставляет разработчикам инструменты для создания собственного адаптера каналов с использованием той же структуры. Эта архитектура даёт разработчикам широкую свободу в поиске агентов и расширяет возможности для подключения клиентов к этому хабу, а это может быть один или несколько клиентов, таких как Microsoft Teams, Slack и другие.

У разных каналов разные возможности и ограничения.

Вы можете проверить канал, с которого получили активность, проверив channelId свойство в Activity.

Каналы включают конкретные данные, которые не соответствуют общей Activity полезной нагрузке на всех каналах. Вы можете получить доступ к этим данным из свойства TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) , перенаправив их в переменные для использования в вашем коде.

В следующих разделах изложены основные аспекты при работе с обычными клиентами.

Microsoft Teams

• Поддерживает богатые Adaptive Cards с расширенными функциями.
• Поддерживает обновления и удаление сообщений.
• Содержит конкретные данные канала для функций Teams, таких как упоминания и информация о встречах.
• Поддерживает вызов действий для модулей задач.

Microsoft 365 Copilot

• В основном сосредоточена на активностях с посланиями.
• Поддерживает ссылки и ссылки в ответах.
• Требуется потоковые ответы.
• Ограниченная поддержка богатых и адаптивных карт.

Веб-чат/DirectLine

Веб-чат — это HTTP-протокол, который агенты могут использовать для общения по HTTPS.

• Полная поддержка для всех типов активности.
• Поддерживает пользовательские данные канала.

Каналы, не связанные с Microsoft

К таким каналам относятся Slack, Facebook и другие.

• Возможно, поддержка некоторых типов активности ограничена.
• Рендеринг карт может отличаться или не поддерживаться.
• Всегда проверяйте документацию по конкретному каналу.

Дальнейшие шаги

• Узнайте о AgentApplication