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

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

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

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

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

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

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

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

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

  • Примитивное литеральное значение
  • Ссылка на переменную
  • Формула 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. При использовании этого узла вы выбираете тип действия, а затем дополнительно задаете имя или значение.

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

  • Ввод — отправляет действие по вводу, которое канал может выбрать и отобразить индикатор набора текста на клиенте.
  • Invoke и Invoke respond используются для Microsoft Teams. Вы создаете тему с триггером вызова для перехвата входящего вызова из Teams и используете узел Вызвать действие ответа для отправки соответствующего ответа обратно в Teams.
  • Передача отправляет действие передачи с явным контролем над значением. Для внешних каналов, таких как AudioCodes, используется handoff.

Связанный контент

  • Last updated on