Игровая площадка агентов Microsoft 365

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

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

Ниже приведены преимущества агента Playground.

• Среда песочницы. Песочница на площадке агентов имитирует поведение, внешний вид и пользовательский интерфейс реального.

• Туннелирование. Внешняя служба туннелирования не требуется, так как платформа агентов работает на локальном сервере, с которым бот может взаимодействовать.

• Уменьшение зависимостей учетных записей. Клиент разработчика Microsoft 365 и разрешения на отправку приложения не нужны для отладки приложения.

• Быстрые итерации внутреннего цикла. Оптимизирует процесс внесения изменений в структуру приложения и логику приложения без необходимости повторного развертывания приложения в облаке.

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

• Надежный: Агентская площадка является надежной, так как адаптивная карточка приложения использует ту же технологию отрисовки, что и в Teams или WebChat.

• Интеграция с существующими приложениями. Платформа агентов легко интегрируется с существующими приложениями, созданными с помощью пакета SDK для агента или библиотеки ИИ Teams.

• Поддержка разных областей: агенты playground поддерживает тестирование в личных, командных и групповых чатах.

Предварительные условия

Убедитесь, что вы установили следующие средства для создания и развертывания приложений на детской площадке агентов:

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

Агенты Playground — это пакет npm с командой CLI с именем teamsapptester. При запуске teamsapptester startна локальном компьютере открывается веб-приложение, которое эмулирует клиент Teams или WebChat и службу Bot Framework. Этому веб-приложению не нужны облачные ресурсы, так как оно использует макетные данные для имитации контекстной информации.

Чтобы использовать приложение на детской площадке агентов, необходимо указать следующее:

• Конечная точка сообщения. Конечная точка сообщения — это URL-адрес, который связывает тестовую площадку агентов и приложение. Вы можете обновить конечную точку с помощью переменной BOT_ENDPOINT среды, запустить агентов Playground с помощью параметра --app-endpointили просто использовать значение http://localhost:3978/api/messagesпо умолчанию .
• Файл конфигурации (необязательно). Файл конфигурации информирует о вашей настраиваемой контекстной информации в Teams. Файл называется .m365agentsplayground.yml в корневой папке проекта. Если Teams не удается найти этот файл, используется конфигурация по умолчанию. Дополнительные сведения см. в разделе Настройка контекста Teams.

Взаимодействие с тестовой площадкой агентов в наборе средств агентов

Агенты Playground предлагает более быструю отладку приложений по сравнению с реальной средой.

Триггеры действий

Вы можете мимитить действие на детской площадке агентов с помощью триггеров действий. Существует два типа триггеров действий:

1. Предопределенные триггеры действий
2. Триггеры пользовательских действий

Предопределенные триггеры действий

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

Предопределенные триггеры действий доступны в меню Макет действий на игровой площадке агентов.

Чтобы имитировать действие add user , сделайте следующее:

1. На вкладке Агенты Playground перейдите в раздел Макет действия и выберите Добавить пользователя.

   

   Появится всплывающее окно для предварительного просмотра обработчика действий.

2. Выберите Отправить действие.

   

   Приложение отправляет ответ.

   

Триггеры пользовательских действий

Настраиваемое действие можно использовать для настройки триггеров действий, таких как , reactionsAddedв соответствии с требованиями приложения бота. Агенты Playground автоматически заполняет необходимые свойства действия. Вы также можете изменить тип действия и добавить дополнительные свойства.

1. Выберите Макет пользовательского>действия действия.

   

2. Добавьте messageReaction , чтобы настроить действие в свойстве type и вызвать пользовательское действие.

   {
     "type": "messageReaction",
     "reactionsAdded": [
       {
         "type": "like"
       }
     ],
     "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
   }
   

3. Выберите Отправить действие.

   

   Бот отправляет onReactionsAdded обработчик в ответ.

   

Настройка тестовой площадки агентов для проверки подлинности

При отладке приложения, требующего проверки подлинности, можно настроить Microsoft Entra идентификатор клиента и секрет клиента с помощью дополнительного идентификатора клиента. Если вы создали бот с помощью azure AI Служба Bot, учетные данные доступны в Служба приложений бота в разделе Конфигурация параметров>. Если вы не уверены в значениях, их можно удалить из файла конфигурации локально работающего приложения, а затем запустить приложение на игровой площадке агентов. Если приложение не требует выполнения этих параметров, настраивать их не нужно.

Переменная среды или командная строка

Перед запуском тестовой площадки агентов можно задать следующие переменные среды: AUTH_CLIENT_ID, AUTH_CLIENT_SECRETи AUTH_TENANT_ID. Эти значения используются для конфигурации проверки подлинности по умолчанию.

При запуске тестовой площадки агентов из командной строки можно также использовать параметры: --client-id, --client-secretи --tenant-id. Эти параметры переопределяют параметры переменных среды по умолчанию.

Интерфейс на стороне клиента

После запуска тестовой площадки агентов вы по-прежнему можете настроить проверку подлинности с помощью клиентского интерфейса следующим образом:

1. Выберите Настроить проверку подлинности.

   

2. Заполните поля в форме и нажмите кнопку Сохранить.

   

Если конфигурация успешно настроена, на панели журнала отображается сообщение.

Логика проверки подлинности

Агенты Playground получает маркер JWT с помощью предоставленных параметров проверки подлинности и включает его в заголовок Authorization при взаимодействии с приложением. Маркер JWT в заголовке ответа приложения также проверяется на тестовой площадке агентов. Дополнительные сведения о процессе проверки подлинности см. в статье Проверка подлинности с помощью API соединителя Bot.

Поддержка нескольких каналов

Teams — это канал по умолчанию, используемый для отладки приложения, но поддерживаются и другие каналы. Вы можете изменить канал, задав DEFAULT_CHANNEL_ID переменную среды или используя --channel-id параметр при запуске платформы агентов из командной строки.

В настоящее время допустимые идентификаторы каналов: msteams, , directlinewebchatи emulator. При установке идентификатора канала свойства сообщений, отправляемых в приложение, изменяются соответствующим образом, чтобы имитировать реальную среду. directline Для каналов и webchat отображается соответствующий клиент, а карта отрисовка отличается от отображения канала Teams.

Настройка контекста Teams

Файл конфигурации в корневой папке проекта позволяет настроить сведения о контексте Teams, такие как чаты, команды и пользователи. Он предоставляет макетные данные для тестирования API Bot Framework или методов из пакета SDK агента или библиотеки ИИ Teams, например TeamsInfo.getTeamMembers.

Конфигурация по умолчанию

# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.0/config.schema.json
# Visit https://aka.ms/teams-app-test-tool-config-guide for more details on this file.

# This configuration file customizes the Teams context information like chats, teams, and users.
# It contains mock data for testing Bot Framework APIs or Bot Builder SDK methods such as TeamsInfo.getTeamMembers().
# You can customize this file to change API response if your bot code uses these APIs.
version: "0.1.0"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
  id: 00000000-0000-0000-0000-00000000000011
  name: Test Bot
currentUser:
  id: user-id-0
  name: Alex Wilber
  userPrincipleName: [email protected]
  aadObjectId: 00000000-0000-0000-0000-0000000000020
  givenName: Alex
  surname: Wilber
  email: [email protected]
users:
  - id: user-id-1
    name: Megan Bowen
    userPrincipleName: [email protected]
    aadObjectId: 00000000-0000-0000-0000-0000000000021
    givenName: Megan
    surname: Bowen
    email: [email protected]
  - id: user-id-2
    name: Adele Vance
    userPrincipleName: [email protected]
    aadObjectId: 00000000-0000-0000-0000-0000000000022
    givenName: Adele
    surname: Vance
    email: [email protected]
  - id: user-id-3
    name: Isaiah Langer
    userPrincipleName: [email protected]
    aadObjectId: 00000000-0000-0000-0000-0000000000023
    givenName: Isaiah
    surname: Langer
    email: [email protected]
  - id: user-id-4
    name: Patti Fernandez
    userPrincipleName: [email protected]
    aadObjectId: 00000000-0000-0000-0000-0000000000024
    givenName: Patti
    surname: Fernandez
    email: [email protected]
  - id: user-id-5
    name: Lynne Robbins
    userPrincipleName: [email protected]
    aadObjectId: 00000000-0000-0000-0000-0000000000025
    givenName: Lynne
    surname: Robbins
    email: [email protected]
personalChat:
  id: personal-chat-id
groupChat:
  id: group-chat-id
  name: Group Chat
team:
  id: team-id
  name: My Team
  aadGroupId: 00000000-0000-0000-0000-000000000031
  channels:
    - id: channel-announcements-id
      name: Announcements

Обновление файла конфигурации

Если код бота использует API Bot Framework, вы можете изменить файл конфигурации, чтобы настроить ответы API. Например, рассмотрим бот уведомлений Azure DevOps, установленный в команде, который извлекает неактивные ошибки из Azure DevOps. Он определяет владельцев неактивных ошибок, получает их адреса электронной почты и отправляет ежедневные уведомления в личные чаты.

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

1. Перейдите к файлу .m365agentsplayground.yml в корневой папке проекта.

2. Перейдите в users раздел и обновите name, userPrincipleNameи email необходимого пользователя.

   users:
       - id: user-id-1
         name: Megan Bowen
         userPrincipleName: [email protected]
         aadObjectId: 00000000-0000-0000-0000-0000000000021
         givenName: Megan
         surname: Bowen
         email: [email protected]
   

3. Сохраните файл и выберите F5 , чтобы выполнить отладку на детской площадке агентов.

Важно понимать, что обновление файла конфигурации имеет три основных последствия:

• Он влияет на ответы, возвращаемые API-интерфейсами соединителя Bot Framework. Например, TeamsInfo.getPagedMembers().
• Он изменяет сведения в полезных данных действия. Например, activity.recipient.
• Он влияет на пользовательский интерфейс на детской площадке агентов. Например, имена групповых чатов.

Ограничения

• Функции бота или агента, включенные в манифест приложения Teams, недоступны, так как платформа агентов не обрабатывает их.

• Агентская площадка поддерживает не все типы карточек, кроме адаптивных карточек.

• На игровой площадке агентов не поддерживаются следующие функции адаптивной карточки:

  • Поиск typeahead
  • Упоминание пользователя
  • Представление этапа
  • Полная ширина

• На тестовой площадке агентов не поддерживаются следующие возможности:

  • Мобильная версия
  • Собрание

• Тестовая площадка агентов может эмулировать следующие возможности:

  Возможности	Отладка на детской площадке агентов	Локальная отладка приложений
  Базовая отправка и получение сообщений	Доступно	Доступно
  API Bot Framework (TeamsInfo.getPagedMembers()...	Доступно (ответ с помощью макетированных данных)	Доступно
  Отправка событий Teams	Доступно (имитация действия)	Доступно
  Индикатор ввода	Компонент недоступен	Доступно
  Вкладка, расширение сообщений, диалоговые окна (называемые модулями задач в TeamsJS версии 1.x), единый вход (SSO) и неадаптивные карточки	Компонент недоступен	Доступно

Отладка существующего приложения с помощью детской площадки агентов

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

1. Откройте папку проекта существующего бота в наборе средств агентов.

2. Перейдите в разделEXPLORER.vscode>.

3. Выберите launch.json и добавьте следующий код в конец файла:

   // .vscode/launch.json 
   
   { 
       ... 
       "compounds": [ 
           ... 
           { 
               "name": "Debug in Microsoft 365 Agents Playground", 
               "configurations": [ 
                   "Attach to Local Service" 
               ], 
               "preLaunchTask": "Start App in Microsoft 365 Agents Playground", 
               "presentation": { 
                   "group": "1-local", 
                   "order": 1 
               }, 
               "stopAll": true 
           }, 
       ] 
   } 
   

4. Перейдите к tasks.json и добавьте следующий код в конец файла:

       { 
         "label": "Start Microsoft 365 Agents Playground", 
         "type": "shell", 
         "command": "npm run dev:teamsfx:launch-playground", 
         "isBackground": true, 
         "options": { 
           "env": { 
             "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin:${env:PATH}" 
           } 
         }, 
         "windows": { 
           "options": { 
             "env": { 
               "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin;${env:PATH}" 
             } 
           } 
         }, 
         "problemMatcher": { 
           "pattern": [ 
             { 
               "regexp": "^.*$", 
               "file": 0, 
               "location": 1, 
               "message": 2 
             } 
           ], 
           "background": { 
             "activeOnStart": true, 
             "beginsPattern": ".*", 
             "endsPattern": "Listening on" 
           } 
         }, 
         "presentation": { 
           "panel": "dedicated", 
           "reveal": "silent" 
         } 
       }, 
     ],
   }
   

5. В разделе EXPLORER создайте файл .localConfigs.playground и добавьте следующий код:

   // .localConfigs.playground
   # A gitignored place holder file for local runtime configurations when debug in Agents Playground
   BOT_ID=
   BOT_PASSWORD=
   TEAMSFX_NOTIFICATION_STORE_FILENAME=.notification.playgroundstore.json
   

6. Перейдите в раздел Обозреватель>env.

7. Создайте файл .env.playground и добавьте следующий код:

   // .env.playground
   # This file includes environment variables that can be committed to git. It's gitignored by default because it represents your local development environment
   # Built-in environment variables
   TEAMSFX_ENV=playground
   # Environment variables used by Agents Playground
   TEAMSAPPTESTER_PORT=56150
   

8. Если у вас есть настраиваемые переменные среды, задайте их значения в .env.playground или .env.playground.user.

9. Добавьте ключ OpenAI или ключ Azure OpenAI и конечную точку в .env.playground.user.

   # SECRET_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_ENDPOINT=<https://your-openai-service-name.openai.azure.com/>
   

10. Перейдите к package.json и добавьте следующий код в scripts свойство :

    "scripts": {
        ... 
        "dev:teamsfx:playground": "env-cmd --silent -f .localConfigs.playgroundnd npm run dev", 
        "dev:teamsfx:launch-playground": "env-cmd --silent -f env/.env.playground teamsapptester start", 
        ... 
    },
    

11. В левой области выберите Запуск и отладка (Ctrl+Shift+D) и выберите Отладка на игровой площадке агентов Microsoft 365 в раскрывающемся списке.

    

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

Отключение сбора данных

Если вы решите, что вы не хотите разрешать Сбор данных об использовании для платформы агентов, вы можете легко отключить сбор данных, добавив параметр --disable-telemetry при запуске агента Playground с помощью командной строки.

Вопросы и ответы

Пример кода

Пошаговые инструкции

Следуйте инструкциям в пошаговом руководстве по отладке бота чата ИИ с помощью платформы агентов.

См. также

• Обзор набора средств агентов Microsoft 365
• Установка microsoft 365 Agents Toolkit
• Создание ботов для Teams
• Библиотека ИИ Teams
• Адаптивная карточка
• Пакет SDK для агентов