Microsoft 365 代理演练

2025-06-02

注意

Microsoft 365 Agents Playground (以前称为 Teams 应用测试工具) 的最新预发行版Microsoft 365 Agents Toolkit (以前称为 Teams 工具包) 。确保安装代理工具包的最新预发行版。

代理 Playground 使调试机器人或基于代理的应用变得轻松。你可以与机器人聊天，并查看其消息和自适应卡片，因为它们出现在不同的通道中。无需Microsoft 365 开发人员帐户、隧道或真实的客户端应用和应用程序注册即可使用 Agents Playground。

下图显示了一个示例应用，其中显示了一个自适应卡片，其中包含代理场中的命令列表。它还提供命令的说明，以便你无需手动搜索代码即可测试应用：

屏幕截图显示“代理”场自适应卡。

以下是代理场的优点：

沙盒环境：代理场的沙盒环境模拟真实环境的行为、外观和用户体验。
隧道：不需要外部隧道服务，因为 Agents Playground 在机器人可以与之通信的本地服务器上运行。
减少帐户依赖项：Microsoft 365 开发人员租户和应用上传权限不需要调试应用程序。
快速内部循环迭代：优化更改应用设计和应用程序逻辑的过程，而无需将应用程序重新部署到云。
模拟数据和活动：使用模拟数据和活动触发器，代理 Playground 可以轻松测试复杂的方案，例如，在新成员加入通道时发送欢迎消息。
可靠：代理 Playground 是可靠的，因为应用程序的自适应卡片使用与 Teams 或 WebChat 中的相同呈现技术。
与现有应用程序的集成：Agents Playground 与使用代理 SDK 或 Teams AI 库构建的现有应用程序轻松集成。
对不同范围的支持：Agents Playground 支持在个人、团队和群聊范围内进行测试。

先决条件

确保在 Agents Playground 中安装以下工具来生成和部署应用程序：

	安装	用于使用...
	代理工具包	一个Microsoft Visual Studio Code扩展，用于为应用创建项目基架。使用最新的预发行版。
	Node.js	后端 JavaScript 运行时环境。有关详细信息，请参阅项目类型的Node.js 版本兼容性表。
	Visual Studio Code	JavaScript、TypeScript 或 SharePoint 框架 (SPFx) 生成环境。使用最新版本。

了解代理演练

Agents Playground 是具有名为的 teamsapptesterCLI 命令的 npm 包。运行 teamsapptester start时，它会在本地计算机上打开一个模拟 Teams 或 WebChat 客户端和 Bot Framework 服务的 Web 应用。此 Web 应用不需要任何云资源，因为它使用模拟数据来模拟上下文信息。

若要在 Agents Playground 上使用应用程序，需要提供：

消息终结点：消息终结点是链接代理 Playground 和应用程序的 URL。可以使用环境变量更新终结点 BOT_ENDPOINT ，使用选项 --app-endpoint启动 Agents Playground，或者仅使用默认值 http://localhost:3978/api/messages。
配置文件 (可选) ：配置文件告知 Agents Playground 有关 Teams 中的自定义上下文信息。该文件在项目的根 文件夹中.m365agentsplayground.yml命名 。如果 Teams 找不到此文件，它将使用默认配置。有关详细信息，请参阅自定义 Teams 上下文。

代理工具包中的代理演练体验

与实际环境相比，Agents Playground 为应用程序提供了更快的调试体验。

Visual Studio Code
命令行

打开 Visual Studio Code。
在Visual Studio Code活动栏中选择“Microsoft 365 代理工具包”图标。
选择“ 创建新的代理/应用>Teams 应用”。
选择 “Teams 代理”。
选择“ Teams 的基本代理”。如果需要为代理提供其他功能，请选择其他选项。
选择“ Azure OpenAI ”并输入服务密钥。如果使用 OpenAI，请选择其他选项。
选择 “JavaScript”。
选择“ 默认文件夹”。

若要更改默认位置，请执行以下步骤：
1. 选择“ 浏览”。
2. 选择项目工作区的位置。
3. 选择 “选择文件夹”。
为应用输入合适的 名称，然后选择 Enter 键。

此时会显示一个对话框，你需要选择“是”或“否”来信任此文件夹中文件的作者。
在左窗格中，选择“ 运行”和“调试 (Ctrl+Shift+D) ”，然后在下拉列表 中选择“在 Microsoft 365 代理演练 (预览) 调试”。
Agents Playground 在网页中打开应用程序。

我遇到了问题

可以使用 JavaScript 和 TypeScript 或 C# 的命令行在 Agents Playground 中调试应用。若要开始，请选择以下语言：
- JavaScript/TypeScript
- C#
1. 运行以下命令，从 npm安装 Agents Playground CLI：
```
npm install -g @microsoft/microsoft-365-agents-playground
```
2. atk使用 Microsoft 365 Agents Toolkit CLI (以前称为 Teams 工具包 CLI) 的命令创建第一个项目。从要创建项目文件夹的文件夹开始。
```
atk new   
```
  可以使用 CLI 创建新的 Teams 应用。 CLI 将引导你完成一系列问题。使用箭头键选择一个选项。做出选择后 ，选择 Enter 进行确认。为应用输入合适的名称后，将创建项目。
3. 运行以下命令以部署应用并安装所需的依赖项和 npm 包：
```
atk deploy --env=playground
```
4. 运行以下命令以启动应用：
```
npm run dev:atk:playground
```
5. 在单独的终端中运行以下命令以启动 Agents Playground：
```
npm run dev:atk:launch-playground
```
1. 创建新应用。
2. 从 GitHub 版本下载 Agents Playground CLI。
3. 将下载的包解压缩到文件夹。你将找到可执行的二进制文件 teamsapptester.exe。
4. 将 teamsapptester.exe 文件复制到创建应用的文件夹。
5. 打开命令提示符并转到已在其中创建应用的文件夹。
6. 运行以下命令以启动配置文件：
```
dotnet run --launch-profile "Microsoft 365 Agents Playground (browser)"
```
7. 在单独的终端中运行以下命令，以定义机器人消息终结点：
  1. 对于命令提示符：
    
    set BOT_ENDPOINT=http://127.0.0.1:5130/api/messages
  2. 对于 PowerShell：
    
    $env:BOT_ENDPOINT = "http://127.0.0.1:5130/api/messages"
8. 运行以下命令以启动代理场：
  1. 对于命令提示符：
    
    teamsapptester.exe start
  2. 对于 PowerShell：
    
    teamsapptester.exe start
  如果 C# 的 Agents Playground 由于端口冲突而未启动，请在运行 teamsapptester.exe start的环境变量中TEAMSAPPTESTER_PORT更改 Agents Playground 的端口号。
1. 代理场在网页中打开应用。

我遇到了问题

活动触发器

可以使用活动触发器在 Agents Playground 中模拟活动。有两种类型的活动触发器：

预定义的活动触发器
自定义活动触发器

预定义的活动触发器

Agents Playground 提供预定义的活动触发器来测试应用的功能。

类别	活动	处理程序
触发安装更新活动	安装应用程序卸载应用程序	`onInstallationUpdate` `onInstallationUpdateAdded` `onInstallationUpdate` `onInstallationUpdateRemove`
触发对话更新活动	添加用户添加应用程序添加通道	`onMembersAdded` `onTeamsMembersAddedEvent` `onTeamsChannelRenamedEvent`
	删除用户删除应用程序删除频道删除团队	`onMembersRemoved` `onTeamsMembersRemovedEvent` `onMembersRemoved` `onTeamsMembersRemovedEvent` `onTeamsChannelDeletedEvent` `onTeamsTeamDeletedEvent`
	重命名通道重命名团队	`onTeamsChannelRenamedEvent` `onTeamsTeamRenamedEvent`

注意

并非所有范围都提供所有类型的活动。例如，不能在个人聊天或群组聊天中添加或删除频道。

预定义的活动触发器可在代理场的 “模拟活动 ”菜单中使用。

若要模拟 “添加用户” 活动，请执行以下步骤：

在“代理演练”中，转到 模拟活动 ，然后选择“ 添加用户”。

此时将显示一个弹出窗口，用于预览活动处理程序。
选择“ 发送活动”。

应用发送响应。

自定义活动触发器

可以使用 自定义活动 来自定义活动触发器，例如， reactionsAdded以满足机器人应用的要求。 Agents Playground 会自动填充活动的必需属性。还可以修改活动类型并添加更多属性。

选择模拟活动>自定义活动。

添加 messageReaction 以在属性 type 下自定义活动并调用自定义活动。

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

选择“ 发送活动”。

机器人在响应中发送 onReactionsAdded 处理程序。

配置用于身份验证的代理场

调试需要身份验证的应用程序时，可以使用可选的租户 ID 配置Microsoft Entra客户端 ID 和客户端密码。如果已使用 Azure AI 机器人服务创建机器人，则可在机器人的“设置配置”>下的App 服务获取凭据。如果不确定这些值，可以从本地运行的应用程序的配置文件中删除它们，然后在 Agents Playground 中运行该应用程序。如果应用程序不需要这些设置来运行，则无需配置它们。

环境变量/命令行

在启动 Agents Playground 之前，可以设置以下环境变量： AUTH_CLIENT_ID、 AUTH_CLIENT_SECRET和 AUTH_TENANT_ID。这些值用于默认身份验证配置。

从命令行运行 Agents Playground 时，还可以使用选项： --client-id、 --client-secret和 --tenant-id。这些选项将替代默认环境变量设置。

客户端接口

启动代理 Playground 后，仍可以通过客户端接口配置身份验证，如下所示：

选择 “配置身份验证”。
在窗体中填写字段，然后选择“ 保存”。

如果成功设置配置，则日志面板会显示消息。

屏幕截图显示已成功配置身份验证设置的日志面板消息。

身份验证逻辑

Agents Playground 使用提供的身份验证设置获取 JWT 令牌，并在与应用程序通信时将其包含在授权标头中。应用程序响应标头中的 JWT 令牌也由 Agents Playground 进行验证。有关身份验证过程的更多详细信息，请参阅使用机器人连接器 API 进行身份验证。

多通道支持

Teams 是用于调试应用程序的默认通道，但也支持其他通道。可以通过设置 DEFAULT_CHANNEL_ID 环境变量或在从命令行启动 Agents Playground 时使用 --channel-id 选项来更改通道。

目前，接受的通道 ID 为： msteams、 directline、 webchat和 emulator。设置通道 ID 时，发送到应用程序的消息的属性会相应地更改，以模拟真实环境。 directline对于和 webchat 通道，将显示相应的客户端，并且卡呈现与 Teams 通道的呈现不同。

屏幕截图显示了使用不同通道时的卡呈现结果。

自定义 Teams 上下文

项目根文件夹中的配置文件允许你自定义 Teams 上下文信息，例如聊天、团队和用户。它提供模拟数据，用于测试代理 SDK 或 Teams AI 库中的 Bot Framework API 或方法，例如 TeamsInfo.getTeamMembers。

默认配置

Agents Playground 在项目的根文件夹中包含一个内置配置文件。

# 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: alexw@example.com
  aadObjectId: 00000000-0000-0000-0000-0000000000020
  givenName: Alex
  surname: Wilber
  email: alexw@example.com
users:
  - id: user-id-1
    name: Megan Bowen
    userPrincipleName: meganb@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000021
    givenName: Megan
    surname: Bowen
    email: meganb@example.com
  - id: user-id-2
    name: Adele Vance
    userPrincipleName: adelev@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000022
    givenName: Adele
    surname: Vance
    email: adelev@example.com
  - id: user-id-3
    name: Isaiah Langer
    userPrincipleName: isaiah@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000023
    givenName: Isaiah
    surname: Langer
    email: isaiahl@example.com
  - id: user-id-4
    name: Patti Fernandez
    userPrincipleName: pattif@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000024
    givenName: Patti
    surname: Fernandez
    email: pattif@example.com
  - id: user-id-5
    name: Lynne Robbins
    userPrincipleName: lynner@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000025
    givenName: Lynne
    surname: Robbins
    email: lynner@example.com
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

更新配置文件

如果机器人代码使用 Bot Framework API，则可以修改配置文件以自定义 API 响应。例如，假设团队中安装了一个从 Azure DevOps 提取非活动 bug 的 Azure DevOps 通知机器人。它标识非活动 bug 的所有者，检索其电子邮件地址，并将每日通知发送到其个人聊天。

若要在 Agents Playground 中全面测试此机器人，请确保使用非活动 bug 所有者的正确电子邮件地址更新配置文件。

转到 .m365agentsplayground.yml 项目的根文件夹中的文件。

转到 users 部分并更新 name所需用户的、 userPrincipleName和 email 。

users:
    - id: user-id-1
      name: Megan Bowen
      userPrincipleName: meganb@example.com
      aadObjectId: 00000000-0000-0000-0000-0000000000021
      givenName: Megan
      surname: Bowen
      email: some-real-user@real-domain.onmicrosoft.com

保存文件，然后选择 F5 以在代理场中进行调试。

注意

在 Visual Studio Code 中编辑配置文件时，Intellisense 会自动更新属性名称，并在输入无效值时发出警告。

请务必了解更新配置文件有三个主要影响：

它会影响 Bot Framework 连接器 API 返回的响应。例如，TeamsInfo.getPagedMembers()。
它会修改活动有效负载中的详细信息。例如，activity.recipient。
它会影响 Agents Playground 中的用户界面。例如，群聊名称。

限制

通过 Teams 应用清单启用的机器人或代理功能不可用，因为 Agents Playground 不会处理它。
代理场不支持除自适应卡以外的所有类型的卡片。
Agents Playground 不支持以下自适应卡片功能：
Agents Playground 不支持以下体验：
- 移动设备
- 会议

代理场可以模拟以下体验：

功能	在代理场中调试	在本地调试应用
基本发送/接收消息	可用	可用
Bot Framework API (TeamsInfo.getPagedMembers () ...)	可用 (使用模拟数据) 进行响应	可用
发送 Teams 事件	可用的 (模拟活动)	可用
键入指示器	不可用	可用
选项卡、消息扩展、对话 (TeamsJS v1.x) 中称为任务模块、单一登录 (SSO) 和非自适应卡	不可用	可用

使用 Agents Playground 调试现有应用

确保已使用代理工具包创建现有应用。若要使用 Agents Playground 调试应用，请执行以下步骤：

在 Agents Toolkit 中打开现有机器人的项目文件夹。
转到 EXPLORER.vscode>。

选择 “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 
        }, 
    ] 
}

转到 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" 
      } 
    }, 
  ],
}

在 “资源管理器”下，创建 .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

转到 资源管理器>env。

创建 .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

如果有自定义环境变量，请在 .env.playground 或 .env.playground.user 中设置其值。

在 .env.playground.user 中添加 OpenAI 密钥或 Azure OpenAI 密钥和终结点。

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

转到 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", 
    ... 
},

在左窗格中，选择“ 运行”和“调试 (Ctrl+Shift+D) 并在下拉列表 中选择”在 Microsoft 365 代理场中调试 ”。

Agents Playground 已成功调试现有机器人。

我遇到了问题

禁用数据收集

如果你决定不希望允许代理 Playground 收集使用情况数据，可以通过命令行在启动 Agents Playground 时添加选项 --disable-telemetry 来轻松禁用数据收集。

常见问题

如果 Agents Playground 不支持其功能，如何测试我的应用？

你始终可以使用 Teams 客户端来测试代理 Playground 不支持的功能。选择“ 在 Teams (Edge) 中调试”或“ 在 Teams (Chrome) 中调试 ”选项，在 Teams 客户端中测试应用程序。

如何知道代理 Playground 是否不支持我的应用中的功能？

当代理场检测到不受支持的功能时，它会在对话和日志面板中显示警告消息。

屏幕截图显示了不受支持的功能的警告消息。

Microsoft是否建议仅使用 Agents Playground 来测试应用程序？

不正确。我们始终建议用户在将应用程序移动到生产环境之前在 Teams 客户端中测试其应用程序。

代码示例

示例名称	Description	Node.js
代理演练示例应用	用于浏览代理场的示例应用。	View

分步指南

按照分步指南使用 Agents Playground 调试 AI 聊天机器人。

通过

Microsoft 365 代理演练

先决条件

了解代理演练

代理工具包中的代理演练体验

活动触发器

预定义的活动触发器

自定义活动触发器

配置用于身份验证的代理场

环境变量/命令行

客户端接口

身份验证逻辑

多通道支持

自定义 Teams 上下文

默认配置

更新配置文件

限制

使用 Agents Playground 调试现有应用

禁用数据收集

常见问题

代码示例

分步指南

另请参阅

其他资源