使用 Teams AI 库和 Teams 工具包生成自定义引擎代理

你可以为 Microsoft Teams 创建自定义引擎代理，以精确控制轻型作。 这展示了语言模型在准确理解和执行用户意向方面的有效性，使其与应用作保持一致。

在本教程中，你将了解：

• 如何使用 Teams 工具包设置新项目。
• 如何导入 Teams AI 库功能。
• 如何在 Teams 中部署自定义引擎代理并控制轻型作。

可以看到以下输出：

先决条件

• 剩余 5 分钟

下面是生成和部署自定义引擎代理所需的工具列表。

准备开发环境

安装所需的工具后，设置开发环境。

安装 Teams 工具包

Teams 工具包使用工具为应用预配和部署云资源、发布到 Teams 应用商店等，帮助简化开发过程。

可以将工具包与Visual Studio Code配合使用。 还可以使用 CLI (命令行接口) ，称为 teamsapp。

npm install -g @microsoft/teamsapp-cli

sudo npm install -g --unsafe-perm @microsoft/teamsapp-cli

设置 Teams 开发租户

租户类似于 Teams 中组织的空间或容器，可在其中聊天、共享文件和运行会议。 此空间也是上传和测试自定义应用的位置。 让我们验证是否已准备好使用租户进行开发。

检查自定义应用上传选项

创建应用后，必须在 Teams 中加载应用，而无需分发它。 此过程称为自定义应用上传。 登录到 Microsoft 365 帐户以查看此选项。

是否已拥有租户，并且是否具有管理员访问权限？ 我们来检查，如果你真的这样做了！

验证是否可以在 Teams 中上传自定义应用：

1. 在 Teams 客户端中，选择“ 应用” 图标。

2. 选择“管理应用”。

3. 选择 “上传应用”。

4. 查找“ 上传自定义应用”选项。 如果看到 选项，则表示已启用自定义应用上传。

   

   注意

   如果找不到上传自定义应用的选项，请与 Teams 管理员联系。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 开发人员帐户，可以免费获取它。 加入 Microsoft 365 开发人员计划！

1. 转到 Microsoft 365 开发人员计划。

2. 选择“ 立即加入 ”，然后按照屏幕上的说明进行作。

3. 在欢迎屏幕中，选择“ 设置 E5 订阅”。

4. 设置管理员帐户。 完成后，将显示以下屏幕。

   

5. 使用刚刚设置的管理员帐户登录到 Teams。 验证在 Teams 中是否具有 “上传自定义应用 ”选项。

获取免费的 Azure 帐户

如果要在 Azure 中托管应用或访问资源，则必须拥有 Azure 订阅。 在开始之前创建一个免费帐户。

现在，你已准备好设置帐户的所有工具。 开发环境已准备好开始生成应用项目。

为自定义引擎代理应用创建项目工作区

• 剩余 4 分钟

让我们创建第一个自定义引擎代理应用。

Teams 应用的自定义引擎代理功能可创建 AI 聊天机器人。 使用它来运行简单的自动化任务，例如，提供客户服务。 自定义引擎代理与 Web 服务通信，并帮助你使用其产品/服务。 可以获取天气预报、进行预订或使用自定义引擎代理提供的任何其他服务。

由于已准备好创建应用或自定义引擎代理，因此可以设置用于创建自定义引擎代理的新 Teams 项目。

在本教程中，你将了解：

1. 如何使用 Teams 工具包设置新的自定义引擎代理项目。
2. 关于应用项目的目录结构。

创建自定义引擎代理项目工作区

如果先决条件已到位，让我们开始吧！

teamsapp new

浏览应用源代码

基架完成后，在 Visual Studio Code 的“资源管理器”区域中查看项目目录和文件。

生成并运行第一个自定义引擎代理

• 剩余 3 分钟

使用 Teams 工具包设置项目工作区后，生成项目。 确保已登录到 Microsoft 365 帐户。

登录到 Microsoft 365 帐户

使用此帐户登录到 Teams。 如果使用 Microsoft 365 开发人员计划租户，则注册时设置的管理员帐户是 Microsoft 365 帐户。

使用 Teams AI 库功能更新自定义引擎代理

Teams 工具包是搭建基架并运行自定义引擎代理的最简单方法。 Teams 工具包创建基本结构，以便你开始配置自定义引擎代理。

让我们开始配置 Teams AI 库功能：

1. 转到Visual Studio Code并打开终端窗口。

2. 在终端中运行以下命令以安装 yarn：

   npm install
   npm install @microsoft/teams-ai
   
   

   注意

   如果要通过 Teams 工具包创建示例，则会 .env.local.user 在自动创建的安装程序中找到文件。 如果文件不可用，请创建文件并 .env.local.user 更新 OpenAI 密钥或 Azure OpenAI 密钥和 Azure OpenAI 终结点。

3. 转到 app.ts 文件：

   1. 将 添加到 TurnContext import 语句，如下所示：

      
      import { MemoryStorage, TurnContext} from 'botbuilder';
      

   2. 将 添加到 DefaultConversationState, Memory, TurnState import 语句， "@microsoft/teams-ai" 如下所示：

           // 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";
      
      

   3. 在“@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.');
      }
      

   4. 在 之后 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';
      });
      

   5. 在 之后 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`;
      });
      

4. 转到 adapter.ts 文件：

   1. 在 下 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';
      

   2. 在 下 This bot's main dialog.删除以下代码：

      // This bot's main dialog.
      import config from "./config";
      
      const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
      {},
      new ConfigurationServiceClientCredentialFactory(config)
      );
      

   3. 在 之后 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'
          })
      );
      

5. 转到 index.ts 文件：

   1. 在 中 Create HTTP server.，\n机器人启动后 console.log( ，${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.');
      

6. 在根文件夹中，创建新的文件夹结构： 提示>序列。

7. 在 “顺序”下，创建以下文件：

   • config.json
   • skprompt.txt
   • actions.json

8. 转到 文件并 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 处理自定义引擎代理的语言处理。 此文件由 PromptManagerindex.ts 文件中的 启动，负责监督代理的语言处理。 启动提示时，提示管理器 (序列/config.json) 搜索提示配置文件，并将提示设置传递给 OpenAI 或 Azure OpenAI。

9. 转到 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 尝试使用这些提示生成最有可能从上一个文本中遵循的下一系列字词。

10. 转到 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 进行其所有自然语言建模，用户可以使用其选择的任何语言与自定义引擎代理通信。 自定义引擎代理无需额外代码即可正确理解和响应。

在本地生成并运行自定义引擎代理

若要在本地环境中生成和运行应用，请执行以下作：

1. 选择 F5 键以在调试模式下运行应用。

   注意

   如果 Teams 工具包无法检查特定的先决条件，则会提示你检查。

   了解在调试器中本地运行应用时会发生什么情况。

   如果你想知道，当你按 F5 键时，Teams 工具包：

   1. 检查以下所有先决条件：

   • 你使用 Microsoft 365 帐户登录。
   • 已为 Microsoft 365 帐户启用自定义应用上传。
   • 支持安装 Node.js 版本。
   • 机器人应用所需的端口可用。

   2. 安装 npm 包。
   3. 启动开发隧道以创建 HTTP 隧道。
   4. 在 Microsoft Entra ID 中注册应用并配置应用。
   5. 在 Bot Framework SDK 中注册应用并配置应用。
   6. 在 Teams 开发人员门户中注册应用并配置应用。
   7. 启动应用。
   8. 在 Web 浏览器中启动 Teams 并上传应用。

   

   注意

   首次运行应用时，将下载所有依赖项并生成应用。 编译完成后，将自动打开浏览器窗口。 此过程可能需要 3 到 5 分钟才能完成。

   Teams 在 Web 浏览器中运行你的应用。

2. 如果出现提示，请使用 Microsoft 365 帐户登录。

3. 当系统提示将应用上传到本地计算机上的 Teams 时，选择“ 添加 ”。

   

   现在，自定义引擎代理已在 Teams 上成功运行！ 加载应用后，将打开与自定义引擎代理的聊天会话。

   

   可以键入 LightsOn 以开始与自定义引擎代理交互。

部署自定义引擎代理

• 剩余 2 分钟

你已了解如何创建、生成和运行自定义引擎代理。 最后一步是在 Azure 上部署应用。

让我们使用 Teams 工具包在 Azure 上部署自定义引擎代理。

登录到 Azure 帐户

使用此帐户访问Microsoft Azure 门户并预配新的云资源以支持你的应用。

将应用部署到 Azure。

部署包括两个步骤。 首先， (也称为预配) 创建必要的云资源。 然后，应用的代码将复制到创建的云资源中。 在本教程中，你将部署自定义引擎代理。

运行已部署的应用

完成预配和部署步骤后：

1. (Ctrl+Shift+D / ⌘⇧-D 或查看>Visual Studio Code的运行) ，打开调试面板。

2. 从启动配置下拉列表中选择“ 启动远程 (Edge) ”。

3. 选择“ 开始调试 (F5) 从 Azure 启动应用。

   

4. 选择“添加”。

   工具包显示一条消息，指示应用已添加到 Teams。

   

   你的应用在 Teams 客户端上加载。

   

部署之前，应用程序已在本地运行:

• 后端使用 Azure Functions Core Tools 运行。
• 应用程序 HTTP 终结点 (Microsoft Teams 在此加载应用程序) 在本地运行。

部署是一个两步过程。 在活动 Azure 订阅上预配资源，然后将应用程序的后端和前端代码部署或上传到 Azure。

• 后端（如果已配置）使用各种 Azure 服务，包括Azure 应用服务和 Azure 存储。
• 前端应用程序部署到为静态 Web 托管配置的 Azure 存储帐户。

恭喜！

• 100% 完成！

你做到了！

你已创建用于控制灯光的自定义引擎代理。

你已完成本教程。