Создание пользовательского агента обработчика с помощью библиотеки ИИ Teams и набора средств Teams
Вы можете создать пользовательский агент обработчика для Microsoft Teams, чтобы получить точный контроль над легкими операциями. Это демонстрирует эффективность языковой модели в точном понимании и выполнении намерений пользователя, согласуя его с действиями приложения.
В этом руководстве вы узнаете:
- Настройка нового проекта с помощью набора средств Teams.
- Импорт возможностей библиотеки ИИ Teams.
- Развертывание пользовательского агента обработчика в Teams и управление легкими операциями.
Вы увидите следующие выходные данные:
Предварительные условия
Ниже приведен список средств, необходимых для создания и развертывания пользовательского агента обработчика.
Установка | Для использования... | |
---|---|---|
Набор средств Teams | Расширение Microsoft Visual Studio Code, которое создает шаблон проекта для вашего приложения. Используйте последнюю версию. | |
Microsoft Teams | Для совместной работы со всеми пользователями вы работаете с приложениями для чата, собраний и звонков в одном месте. | |
Node.js | Серверной среды выполнения JavaScript. Дополнительные сведения см . вNode.js таблице совместимости версий для типа проекта. | |
Microsoft Edge (рекомендуется) или Google Chrome | Браузера со средствами разработчика. | |
Visual Studio Code; | Среды сборки JavaScript, TypeScript и Python. Используйте последнюю версию. | |
OpenAI или Azure OpenAI | Сначала создайте ключ API OpenAI, чтобы использовать GPT OpenAI. Если вы хотите разместить приложение или получить доступ к ресурсам в Microsoft Azure, перед началом работы необходимо создать службу Azure OpenAI . | |
Учетная запись разработчика Microsoft 365 | Доступ к учетной записи Teams с соответствующими разрешениями для установки приложения. |
Подготовка среды разработки
После установки необходимых средств настройте среду разработки.
Установка набора средств Teams
Набор средств Teams упрощает процесс разработки с помощью средств для подготовки и развертывания облачных ресурсов для приложения, публикации в Магазине Teams и многого другого.
Набор средств можно использовать с Visual Studio Code.
Вы также можете использовать ИНТЕРФЕЙС командной строки (интерфейс командной строки), который называется teamsapp
.
Откройте Visual Studio Code и выберите представление Расширения (CTRL+SHIFT+X️ / ⇧-X или View > Extensions).
В поле поиска введите Набор средств Teams.
Выберите Установить рядом с набором средств Teams.
После установки на панели действий Visual Studio Code появится значок набора средств Teams.
Набор средств Teams также можно найти в Visual Studio Code Marketplace.
Настройка клиента разработки Teams
Клиент — это как пространство или контейнер для вашей организации в Teams, где вы общаетесь в чате, обмениваются файлами и выполняете собрания. В этом пространстве также можно отправлять и тестировать пользовательское приложение. Давайте проверим, готовы ли вы к разработке с помощью клиента.
Проверка параметра отправки пользовательских приложений
После создания приложения необходимо загрузить это приложение в Teams, не распространяя его. Этот процесс называется отправкой пользовательского приложения. Войдите в учетную запись Microsoft 365, чтобы просмотреть этот параметр.
Примечание.
Отправка пользовательских приложений необходима для предварительного просмотра и тестирования приложений в локальной среде Teams. Если он не включен, вы не сможете просматривать и тестировать приложение в локальной среде Teams.
У вас уже есть клиент и есть ли у вас доступ администратора? Давайте проверка, если вы действительно делаете!
Проверьте, можно ли отправить пользовательское приложение в Teams:
В клиенте Teams щелкните значок Приложения .
Выберите Управление приложениями
Выберите Отправить приложение.
Найдите параметр Отправить пользовательское приложение. Если параметр отображается, включена отправка пользовательских приложений.
Примечание.
Если вы не найдете параметр для отправки пользовательского приложения, обратитесь к администратору Teams.
Создание бесплатного клиента разработчика Teams (необязательно)
Если у вас нет учетной записи разработчика Teams, ее можно получить бесплатно. Присоединяйтесь к программе для разработчиков Microsoft 365!
Перейдите в программу для разработчиков Microsoft 365.
Выберите Присоединиться и следуйте инструкциям на экране.
На экране приветствия выберите Настроить подписку E5.
Настройте свою учетную запись администратора. После завершения отобразится следующий экран.
Войдите в Teams с помощью только что настроенной учетной записи администратора. Убедитесь, что у вас есть параметр Отправить пользовательское приложение в Teams.
Получение бесплатной учетной записи Azure
Если вы хотите разместить приложение или получить доступ к ресурсам в Azure, у вас должна быть подписка Azure. Перед началом работы создайте бесплатную учетную запись.
Теперь у вас есть все средства для настройки учетной записи. Среда разработки готова к созданию проекта приложения.
Создание рабочей области проекта для приложения пользовательского агента обработчика
Давайте создадим свое первое пользовательское приложение агента обработчика.
Возможность пользовательского агента обработчика приложения Teams создает чат-бот ИИ. Он используется для выполнения простых и автоматизированных задач, например для предоставления обслуживания клиентов. Агент пользовательского обработчика взаимодействует с веб-службой и помогает использовать его предложения. Вы можете получить прогноз погоды, сделать резервирования или любую другую службу, предлагаемую с помощью пользовательского агента обработчика.
Как вы уже подготовились к созданию приложения или пользовательского агента обработчика, вы можете настроить новый проект Teams для создания пользовательского агента обработчика.
В этом руководстве вы узнаете:
- Настройка нового проекта пользовательского агента обработчика с помощью набора средств Teams.
- Сведения о структуре каталогов проекта приложения.
Создание рабочей области проекта пользовательского агента обработчика
Если предварительные требования выполнены, давайте начнем!
Откройте Visual Studio Code.
Щелкните значок Набора средств
Teams на панели действий Visual Studio Code.
Выберите Создать новое приложение.
Выберите Агент пользовательского обработчика.
Выберите Базовый чат-бот ИИ.
Выберите TypeScript в качестве языка программирования.
Выберите OpenAI или Azure OpenAI.
Введите Ключ OpenAI или Ключ Azure OpenAI и Конечную точку Azure OpenAI.
Выберите Папка по умолчанию , чтобы сохранить корневую папку проекта в расположении по умолчанию.
Вы также можете изменить расположение по умолчанию, выполнив следующие действия.
Нажмите кнопку Обзор.
Выберите расположение рабочей области проекта.
Выберите выбрать папку.
Введите подходящее имя для приложения и нажмите клавишу ВВОД.
Откроется диалоговое окно. Выберите Да, я доверяю авторам или Нет, я не доверяю авторам на основе ваших требований.
Пользовательский агент обработчика будет создан через несколько секунд.
После создания приложения набор средств Teams отображает следующее сообщение:
Краткий обзор создания приложения Teams.
Просмотрите этот краткий обзор для создания приложения Teams.
Обзор исходного кода приложения
После завершения формирования шаблонов просмотрите каталоги и файлы проектов в области Обозреватель Visual Studio Code.
Имя папки | Содержание |
---|---|
env/.env.local.user |
Файл конфигурации для локальной среды, используемый teamsapp.yml для настройки правил подготовки и развертывания. |
index.ts |
Основная точка входа для приложения. |
teamsBot.ts |
Обработчик действий Teams. |
appPackage |
Файлы шаблонов манифеста приложения и значки приложений (color.png и outline.png). |
appPackage/manifest.json |
Манифест приложения для запуска приложения в локальной и удаленной среде. |
config.ts |
config.ts заключает в себя доступ к переменным среды, используемым для настройки адаптера ботов. |
teamsapp.yml |
Это проект набора средств main Teams, который определяет свойства и определения этапов конфигурации. |
teamsapp.local.yml |
Это переопределяет teamsapp.yml действиями, которые обеспечивают локальное выполнение и отладку. |
Сборка и запуск первого пользовательского агента обработчика
После настройки рабочей области проекта с помощью Набора средств Teams выполните сборку проекта. Убедитесь, что вы вошли в учетную запись Microsoft 365.
Вход в учетную запись Microsoft 365
Используйте эту учетную запись для входа в Teams. Если вы используете клиент программы разработчика Microsoft 365, учетная запись администратора, настроенная при регистрации, — это учетная запись Microsoft 365.
Откройте Visual Studio Code.
Щелкните значок Набора средств
Teams на боковой панели.
Выберите Войти в M365.
Откроется веб-браузер по умолчанию, чтобы позволить вам войти в учетную запись.
Войдите в учетную запись Microsoft 365, используя свои учетные данные.
Закройте браузер при появлении запроса и вернитесь к Visual Studio Code.
Вернитесь к набору средств Teams в Visual Studio Code.
Используйте эту учетную запись для входа в Teams. Если вы используете клиент программы разработчика Microsoft 365, учетная запись администратора, настроенная при регистрации, — это учетная запись Microsoft 365.
Теперь вы можете создать приложение и запустить его локально!
Обновление пользовательского агента обработчика с помощью возможностей библиотеки ИИ Teams
Набор средств Teams — это самый простой способ формирования шаблонов и запуска пользовательского агента обработчика. Набор средств Teams создает базовую структуру, чтобы приступить к настройке пользовательского агента обработчика.
Давайте приступим к настройке возможностей библиотеки ИИ Teams:
Перейдите к Visual Studio Code и откройте окно терминала.
Выполните следующую команду в терминале, чтобы установить
yarn
:npm install npm install @microsoft/teams-ai
Примечание.
Если вы создаете пример с помощью набора средств Teams, вы найдете
.env.local.user
файл в программе установки, которая создается автоматически. Если файл недоступен, создайте.env.local.user
файл и обновите ключ OpenAI или ключ Azure OpenAI и конечную точку Azure OpenAI.Перейдите к файлу
app.ts
:Добавьте
TurnContext
в инструкцию import следующим образом:import { MemoryStorage, TurnContext} from 'botbuilder';
Добавьте
DefaultConversationState, Memory, TurnState
в инструкцию"@microsoft/teams-ai"
import следующим образом:// See https://aka.ms/teams-ai-library to learn more about the Teams AI library. import { Application, ActionPlanner, DefaultConversationState, Memory, TurnState, OpenAIModel, PromptManager } from "@microsoft/teams-ai";
После @microsoft/teams-ai добавьте следующее:
// eslint-disable-next-line @typescript-eslint/no-empty-interface interface ConversationState extends DefaultConversationState { lightsOn: boolean; } type ApplicationTurnState = TurnState<ConversationState>; if (!process.env.OPENAI_API_KEY) { throw new Error('Missing environment variables - please check that OPENAI_KEY or AZURE_OPENAI_KEY is set.'); }
После
Define storage and application code
добавьте следующее:// Define a prompt function for getting the current status of the lights planner.prompts.addFunction('getLightStatus', async (context: TurnContext, memory: Memory) => { return memory.getValue('conversation.lightsOn') ? 'on' : 'off'; });
После
return memory.getValue('conversation.lightsOn') ? 'on' : 'off';
добавьте следующее:// Register action handlers app.ai.action('LightsOn', async (context: TurnContext, state: ApplicationTurnState) => { state.conversation.lightsOn = true; await context.sendActivity(`[lights on]`); return `the lights are now on`; }); app.ai.action('LightsOff', async (context: TurnContext, state: ApplicationTurnState) => { state.conversation.lightsOn = false; await context.sendActivity(`[lights off]`); return `the lights are now off`; }); interface PauseParameters { time: number; } app.ai.action('Pause', async (context: TurnContext, state: ApplicationTurnState, parameters: PauseParameters) => { await context.sendActivity(`[pausing for ${parameters.time / 1000} seconds]`); await new Promise((resolve) => setTimeout(resolve, parameters.time)); return `done pausing`; });
Перейдите к файлу
adapter.ts
:В разделе
Import required bot services.
удалите существующий код и обновите следующий:// Import required bot services. // See https://aka.ms/bot-services to learn more about the different parts of a bot. import { TeamsAdapter } from '@microsoft/teams-ai'; import { ConfigurationServiceClientCredentialFactory } from 'botbuilder';
Удалите следующий код в разделе
This bot's main dialog.
:// This bot's main dialog. import config from "./config"; const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication( {}, new ConfigurationServiceClientCredentialFactory(config) );
После
import { ConfigurationServiceClientCredentialFactory } from 'botbuilder';
замените код в разделеCreate adapter.
следующим кодом:// Create adapter. // See https://aka.ms/about-bot-adapter to learn more about how bots work. const adapter = new TeamsAdapter( {}, new ConfigurationServiceClientCredentialFactory({ MicrosoftAppId: process.env.BOT_ID, MicrosoftAppPassword: process.env.BOT_PASSWORD, MicrosoftAppType: 'MultiTenant' }) );
Перейдите к файлу
index.ts
:В ,
Create HTTP server.
послеconsole.log(
\nБот запущен, ${server.name} прослушивая ${server.url});
, добавьте следующее:console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator'); console.log('\nTo test your bot in Teams, sideload the app manifest.json within Teams Apps.');
В корневой папке создайте новую структуру папок:последовательностьзапросов>.
В последовательности создайте следующие файлы:
- config.json
- skprompt.txt
- actions.json
Перейдите в
config.json
файл и добавьте следующий код, чтобы создать параметры модели запроса:{ "schema": 1.1, "description": "A bot that can turn the lights on and off", "type": "completion", "completion": { "model": "gpt-3.5-turbo", "completion_type": "chat", "include_history": true, "include_input": true, "max_input_tokens": 2800, "max_tokens": 1000, "temperature": 0.2, "top_p": 0.0, "presence_penalty": 0.6, "frequency_penalty": 0.0, "stop_sequences": [] }, "augmentation": { "augmentation_type": "sequence" } }
Агент пользовательского обработчика использует OpenAI или Azure OpenAI для моделирования на естественном языке. Файл
config.json
обрабатывает язык для пользовательского агента обработчика. Этот файл, инициированныйPromptManager
изindex.ts
файла , контролирует обработку языка агента. При инициации запроса диспетчер запросов выполняет поиск файла конфигурации запроса (последовательности или config.json) и передает параметры запроса в OpenAI или Azure OpenAI.Перейдите к файлу
skprompt.txt
. Добавьте следующие инструкции для OpenAI или Azure OpenAI для ведения и упрощения беседы:The following is a conversation with an AI assistant. The assistant can turn a light on or off. context: The lights are currently {{getLightStatus}}.
Файл
skprompt.txt
содержит текстовые запросы, с которыми пользователи взаимодействуют с OpenAI или Azure OpenAI. OpenAI или Azure OpenAI пытается использовать эти запросы для создания следующей серии слов, которые, скорее всего, будут следовать из предыдущего текста.Перейдите к файлу
actions.json
. Добавьте следующий код, чтобы определить действия для пользовательского агента обработчика:{ { "name": "LightsOn", "description": "Turn the lights on", "parameters": [] }, { "name": "LightsOff", "description": "Turn the lights off", "parameters": [] }, { "name": "Pause", "description": "Delays for a period of time", "parameters": { "type": "object", "properties": { "time": { "type": "number", "description": "The amount of time to delay in milliseconds" } }, "required": [ "time" ] } } }
Файл
actions.json
содержит действия, которые может выполнять агент пользовательского обработчика. ДляActionPlanner
выполнения действий изindex.ts
файла используются действия,actions.json
определенные в файле.
В этом примере используется OpenAI или Azure OpenAI для моделирования на естественном языке. Пользователь может взаимодействовать с агентом пользовательского обработчика на любом языке по своему выбору. Агент пользовательского обработчика понимает и реагирует соответствующим образом без дополнительного кода.
Локальная сборка и запуск пользовательского агента обработчика
Чтобы создать и запустить приложение в локальной среде, выполните следующие действия:
Выберите клавишу F5 , чтобы запустить приложение в режиме отладки.
Примечание.
Если набору средств Teams не удается проверка определенных предварительных требований, вам будет предложено проверка.
Узнайте, что происходит при локальном запуске приложения в отладчике.
Если вам интересно, при нажатии клавиши F5 набор средств Teams:
- Проверяет все следующие предварительные требования:
- Вы вошли в систему с помощью учетной записи Microsoft 365.
- Для учетной записи Microsoft 365 включена отправка пользовательских приложений.
- Установлена поддерживаемая версия Node.js.
- Порт, необходимый для приложения бота, доступен.
- Установите пакеты npm.
- Запускает Dev Tunnel для создания http-туннеля.
- Регистрирует приложение в Microsoft Entra ID и настраивает его.
- Регистрирует приложение в пакете SDK Bot Framework и настраивает его.
- Регистрирует приложение на портале разработчика Teams и настраивает его.
- Запускает приложение.
- Запускает Teams в веб-браузере и отправляет приложение.
Примечание.
При первом запуске приложения загружаются все зависимости, и приложение создается. По завершении сборки автоматически откроется окно браузера. Этот процесс может занять от трех до пяти минут.
Teams запускает приложение в веб-браузере.
При появлении запроса войдите с помощью учетной записи Microsoft 365.
Выберите Добавить при появлении запроса на отправку приложения в Teams на локальном компьютере.
Теперь агент пользовательского обработчика успешно работает в Teams! После загрузки приложения открывается сеанс чата с пользовательским агентом обработчика.
Вы можете ввести ,
LightsOn
чтобы начать взаимодействие с пользовательским агентом обработчика.
Узнайте, как устранять неполадки, если приложение не выполняется локально.
Чтобы успешно запустить приложение в Teams, убедитесь, что вы включили отправку пользовательских приложений в учетной записи Teams. Дополнительные сведения о отправке пользовательских приложений см. в разделе предварительных требований.
Важно!
Отправка пользовательских приложений доступна в средах GCC Community Cloud (GCC), GCC-High и Министерства обороны (DOD).
Совет
Проверьте наличие проблем перед отправкой пользовательского приложения с помощью средства проверки приложения. Это средство входит в набор средств. Исправьте ошибки при отправке приложения.
Развертывание пользовательского агента обработчика
Вы научились создавать, создавать и запускать пользовательский агент обработчика. Последний шаг — развертывание приложения в Azure.
Давайте развернем пользовательский агент обработчика в Azure с помощью набора средств Teams.
Вход в учетную запись Azure
Используйте эту учетную запись для доступа к портал Azure Майкрософт и подготовки новых облачных ресурсов для поддержки приложения.
Откройте Visual Studio Code.
Откройте папку проекта, в которой вы создали приложение.
Щелкните значок Набора средств
Teams на боковой панели.
Выберите Войти в Azure.
Совет
Если у вас установлено расширение учетной записи Azure и вы используете ту же учетную запись, этот шаг можно пропустить. Используйте ту же учетную запись, что и в других расширениях.
Откроется веб-браузер по умолчанию, чтобы позволить вам войти в учетную запись.
Войдите в учетную запись Azure, используя свои учетные данные.
Закройте браузер при появлении запроса и вернитесь к Visual Studio Code.
В разделе ACCOUNTS на боковой панели отображаются две учетные записи по отдельности. В нем также отображается количество доступных для использования подписок Azure. Убедитесь, что у вас есть по крайней мере одна доступная подписка Azure. В противном случае выйдите из нее и используйте другую учетную запись.
Теперь вы готовы к развертыванию приложения в Azure!
Поздравляем, вы создали пользовательский агент обработчика!
Развертывание приложения в Azure
Развертывание состоит из двух этапов. Во-первых, создаются необходимые облачные ресурсы (также известные как подготовка). Затем код приложения копируется в созданные облачные ресурсы. В этом руководстве вы развернете агент пользовательского обработчика.
В чем разница между подготовкой и развертыванием?
Шаг подготовки создает ресурсы в Azure и Microsoft 365 для приложения, но код (HTML, CSS, JavaScript) не копируется в ресурсы. Шаг Развертывание копирует код приложения в ресурсы, созданные на этапе подготовки. Обычно развертывание выполняется несколько раз без подготовки новых ресурсов. Так как процесс подготовки может занять некоторое время, он отделен от шага развертывания.
Выберите значок Набор инструментов Teams на боковой панели Visual Studio Code.
Выберите Подготовка.
Выберите подписку, используемую для ресурсов Azure.
Приложение размещается с помощью ресурсов Azure.
В диалоговом окне появится предупреждение о том, что при выполнении ресурсов в Azure могут возникнуть затраты.
Выберите Подготовка.
Процесс подготовки создает ресурсы в облаке Azure. Это может занять некоторое время. Ход выполнения можно отслеживать, наблюдая за диалогами в правом нижнем углу. Через несколько минут вы увидите следующее уведомление:
При необходимости можно просмотреть подготовленные ресурсы. В этом руководстве вам не нужно просматривать ресурсы.
Подготовленный ресурс отображается в разделе СРЕДА .
После завершения подготовки выберите Развернуть на панели ЖИЗНЕННЫЙ цикл .
Как и при подготовке, развертывание занимает некоторое время. Вы можете отслеживать процесс, наблюдая за диалогами в правом нижнем углу. Через несколько минут вы увидите уведомление о завершении.
Теперь вы можете использовать тот же процесс для развертывания пользовательского агента обработчика в Azure.
Запуск развернутого приложения
После завершения действий по подготовке и развертыванию:
Откройте панель отладки (CTRL+SHIFT+D️ / ⇧-D или Просмотр > запуска) из Visual Studio Code.
В раскрывающемся списке конфигурация запуска выберите Запустить удаленное управление (edge).
Нажмите кнопку Начать отладку (F5), чтобы запустить приложение из Azure.
Нажмите Добавить.
Набор инструментов отображает сообщение о том, что приложение добавлено в Teams.
Приложение загружается в клиенте Teams.
Узнайте, что происходит при развертывании приложения в Azure
До развертывания приложение работает локально:
- Серверная часть работает с использованием Azure Functions Core Tools.
- Конечная точка HTTP приложения, в которую Microsoft Teams загружает приложение, работает локально.
Развертывание — это двухэтапный процесс. Вы подготавливаете ресурсы в активной подписке Azure, а затем развертываете или отправляете код серверной части и внешнего интерфейса для приложения в Azure.
- Если серверная часть настроена, использует различные службы Azure, включая Служба приложений Azure и службу хранилища Azure.
- Интерфейсное приложение развертывается в учетной записи хранения Azure, настроенной для статического веб-размещения.
До развертывания приложение работает локально:
- Серверная часть работает с использованием Azure Functions Core Tools.
- Конечная точка HTTP приложения, в которую Microsoft Teams загружает приложение, работает локально.
Развертывание — это двухэтапный процесс. Вы подготавливаете ресурсы в активной подписке Azure, а затем развертываете или отправляете код серверной части и внешнего интерфейса для приложения в Azure.
- Если серверная часть настроена, использует различные службы Azure, включая Служба приложений Azure и службу хранилища Azure.
- Интерфейсное приложение развертывается в учетной записи хранения Azure, настроенной для статического веб-размещения.
Поздравляем!
Вы сделали это!
Вы создали пользовательский агент обработчика для управления индикаторами.
Вы завершили работу с этим руководством.
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.
Platform Docs