Отправка события или действия

2025-05-21

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

Действия связаны с протоколом действий.

Что такое протокол действий?

Протокол действий является основной транспортной концепцией в Copilot Studio. Протокол действий обеспечивает бесшовную связь между пользователями и агентами. Он определяет стандартизированную структуру для всех взаимодействий, классифицируя их по различным типам деятельности.

Действия событий и действия сообщений — это два различных типа в протоколе действий, каждый из которых служит уникальным целям в рабочих процессах связи.

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

Действия событий, с другой стороны, обычно используются для обозначения невербальных действий или системных обновлений. Они обеспечивают асинхронную связь, запуская определенные функции или рабочие процессы, не требуя прямого взаимодействия с пользователем. Например, действие события может уведомлять агента о присоединении пользователя к разговору или об изменениях в окружающем контексте.

Отправка событий

Узел Действие события предназначен для отправки действий событий. Действия событий отправляются из агента и могут быть перехвачены и использованы каналом, который решает, следует ли использовать эти действия и как их использовать. Когда вы отправляете событие, вы даете ему имя, после чего можете установить для него значения. Это значение может быть в любом формате:

Примитивное литеральное значение
Ссылка на переменную
Формула Power Fx.

Значение сериализуется в JSON и добавляется к исходящему действию.

Снимок экрана, на котором показано меню параметров для узла действия-события.

Использовать этот узел можно следующим образом:

Вы можете настроить пользовательский элемент управления веб-чатом для обработки событий, отправленных от агента. Например, вы можете найти событие, возвращающееся от агента, и выполнить действие на странице. Пример 04.api/c.incoming-activity-event в Репозиторий образцов веб-чата Microsoft Bot Framework на GitHub демонстрирует, как может работать обработка событий.
Канал AudioCodes использует действия-события, чтобы вы могли управлять службой. Например, вы можете начинать или останавливать запись разговора. Дополнительные сведения см. в разделе Запись звонков.

Использование действий клиента

Во время оркестровки мы предоставляем языковой модели набор действий. Большинство людей думают о действиях как о вызове внешних систем.

Действия на стороне сервера через API.

Однако мы также можем использовать действия событий для выполнения действий из клиента.

Действия на стороне клиента через действия событий.

Когда оркестратор принимает решение о выполнении действия клиента, агент отправляет клиенту действие события, включая входные данные, определенные в действии.

Агент отправляет действие, а затем ждет, пока клиент выполнит действие и вернет результат. Когда клиент завершает работу, он отправляет агенту действие события, содержащее ответ. Агент воспринимает этот ответ как ответ действия и продолжает оркестрацию.

Примеры полезных данных для действий клиента

Предположим, что у нас есть действие клиента, которое извлекает текст на слайде PowerPoint.

Входные данные — это номер страницы, а выходные данные — текст на слайде.

Агент может отправить полезную нагрузку, например:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "from": { 
        "id": "d9c0dcf9-4045-8062-535b-73fb4dfee954", 
        "role": 0 
    }, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "page": 5      
    } 
}

После завершения операции клиент отправляет агенту полезные данные, например:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "content": "QA slide. Next steps"      
    } 
}

Настройка клиентских действий

Существует два способа регистрации действий клиента.

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

Например:

description: this tool retrieves the content of a powerpoint slide 
schemaName: GetSlideContent 
    dialog: 
      kind: TaskDialog 
      action: 
        kind: InvokeClientTaskAction 
        clientActionInputSchema: 
          kind: Record 
          properties: 
            page: 
            displayName: Page Number 
            description: The number of the slide 
            isRequired: true 
              type: Number 
        clientActionResponseSchema: 
          kind: Record 
          properties: 
            content: 
            displayName: Slide Content 
            description: The content of the slide 
              type: String

Иногда доступные действия являются динамическими, основанными на контексте клиента хостинга. Чтобы обеспечить большую гибкость, создатели могут установить системную переменную для динамической установки других инструментов клиентов, которые можно использовать для этого сеанса.

- kind: SetVariable 
  id: setVariable_76NZWK 
  variable: System.ClientPluginActions 
  value: |- 
    =[ 
      { 
        Description: "this tool retrieves the content of a powerpoint slide", 
        Identifier: "GetSlideContent", 
        Name: "GetSlideContent", 
        Response: {mode: "Generated"}, 
        Inputs: [ 
          { 
            Description: "The name of the menu for the form to launch", 
            IsAutomatic: true, 
            IsRequired: true, 
            Name: "Page Number", 
            PropertyName: "page", 
            Type: { 
              '$kind': "Number" 
            } 
          } 
        ], 
        Outputs: [ 
          { 
            Description: "The content of the slide", 
            Name: "Slide Content", 
            PropertyName: "content", 
            Type: { 
              '$kind': "String" 
            } 
          } 
        ] 
      } 
    ]

Отправка действий других типов

В дополнение к действиям событий, можно отправлять действия других типов с помощью узла Вызвать действие. Типы действий, которые вы можете отправлять, являются подмножеством тех, которые предлагаются в классе Bot Framework Schema — ActivityTypes. При использовании этого узла вы выбираете тип действия, а затем дополнительно задаете имя или значение.

К распространенным типам относятся следующие:

Ввод — отправляет действие по вводу, которое канал может выбрать и отобразить индикатор набора текста на клиенте.
Задержка может установить задержку между сообщениями. Например, можно отправить сообщение, затем отправить действие-задержку задержки, а затем еще одно сообщение. Клиент видит первое сообщение, за которым следует пауза, затем второе сообщение. В таких случаях значение устанавливается равным количеству миллисекунд для желаемой задержки. Дополнительные сведения см. в разделе Поле ActivityTypes.Delay.
Вызов/Ответ на вызов используются для Microsoft Teams. Вы создаете тему с триггером вызова для перехвата входящего вызова из Teams и используете узел Вызвать действие ответа для отправки соответствующего ответа обратно в Teams.
Передача отправляет действие передачи с явным контролем над значением. Передача обслуживания используется для некоторых внешних каналов, таких как AudioCodes.

Снимок экрана, на котором показан узел действия Invoke с раскрывающимся списком «Тип».

Поделиться через