使用 Microsoft Agent 365 SDK 测试代理

在部署之前，请使用 Agents Playground 在本地测试代理。 本指南介绍如何搭建开发环境、配置认证，以及通过使用 Agents Playground 测试工具验证代理的功能。

一旦代理在本地运行，请按照 Agent 365 开发生命周期 在 Microsoft 365 应用程序（如 Teams、Word 和 Outlook）中进行测试。

先决条件

开始之前，请确保已安装以下先决条件：

常见的先决条件

• 选择任意代码编辑器。 建议使用 Visual Studio Code。
• Agents Playground：通过以下方法 之一安装Agents Playground ：
  • Windows： winget install agentsplayground
  • npm：npm install -g @microsoft/m365agentsplayground
• A365 CLI：代理部署和管理所必需的。 安装Agent 365 CLI。
• LLM API 访问：根据代理的配置或首选模型提供程序选择适当的服务：
  • OpenAI API 密钥： 获取您的 OpenAI API 密钥。
  • Azure OpenAI：创建并部署 Azure OpenAI 资源以获取 API 密钥和终结点。
• 开发者门户配置：发布代理后，必须在开发者门户中配置代理蓝图，然后才能创建实例。 了解如何在开发者门户中配置代理蓝图

特定于语言的先决条件：

配置代理测试环境

本节介绍如何设置环境变量、认证开发环境，以及准备Agent 365驱动的代理进行测试。

按照以下顺序工作流设置代理测试环境：

1. 配置您的环境 ——创建或更新您的环境配置文件。

2. LLM 配置 - 获取 API 密钥并配置 OpenAI 或 Azure OpenAI 设置。

3. 配置认证 ——设置代理认证。

4. 环境变量参考 - 配置所需的环境变量：

   1. 身份验证变量
   2. MCP 终结点配置
   3. 可观测性变量
   4. 代理应用程序服务器配置

完成这些步骤后，即可开始在 Agents Playground 中测试代理。

步骤 1：配置环境

设置您的配置文件

cp .env.template .env

cp .env.template .env

步骤 2：LLM配置

配置 OpenAI 或 Azure OpenAI 设置进行本地测试。 将你的API密钥和服务端点从前置条件中添加到配置文件中，连同任何模型参数一起。

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

步骤3：为你的代理配置认证

为您的代理选择以下认证方法之一：

• 代理认证 ——用于生产场景中存在代理用户身份时的使用。
• （代表操作）OBO 身份验证 - 当在生产环境中需要没有代理用户标识的委派用户权限时使用。
• 持有令牌认证 ——仅用于早期开发和测试场景，生产认证尚未配置。

代理认证

在工作目录中打开 a365.generated.config.json 以检索您的代理凭据蓝图。 复制以下值：

使用这些值在代理中配置代理身份验证：

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

OBO 身份验证

通过使用 On-Behalf-Of （OBO） 身份验证，代理可以使用委派的用户权限访问 MCP 服务器工具，而无需代理用户标识。 在这个流程中，代理接收用户委派的令牌，并交换以代表用户执行作。

OBO认证适用于以下生产场景：

• 您的代理没有代理用户标识。
• 你需要访问具有用户特定权限的资源。
• 你希望代理代表被认证的用户行事。

有关OBO流程的工作原理，请参见 认证流程。 有关完整的实现示例，请参阅Microsoft 365 智能体 SDK中的 OBO 授权示例。

持有者令牌身份验证

在早期开发和测试场景中，如果生产认证未配置，可以使用承载令牌认证来测试你的代理。 该方法通过交互式浏览器认证获得委派的访问令牌。 通过使用该令牌，您的代理可以利用您的用户权限调用MCP服务器工具。 这种方法模拟了代理用户如何在生产环境中访问资源，而无需实际代理实例。

首先，使用该工具 a365 develop add-permissions 为你的应用程序添加所需的MCP服务器权限：

a365 develop add-permissions

然后，使用 a365 develop get-token 来检索和配置承载令牌。

a365 develop get-token

命令 get-token 会自动执行：

• 读取ToolingManifest.json以发现所有配置的MCP服务器。
• 为每个目标受众获取一个令牌，每台 MCP 服务器接收与其特定应用 ID 关联的令牌；共享的 ATG 服务器接收与共享代理工具网关应用 ID 关联的令牌（ea9ffc3e-8a23-4a7d-836d-234d7c7565c1）。
• 将令牌写入项目配置文件：
  • 每服务器令牌： BEARER_TOKEN_<SERVER_NAME> （例如 BEARER_TOKEN_MCP_MAILTOOLS）
  • 共享 ATG 令牌： BEARER_TOKEN

在运行 get-token之前，请将占位符条目添加到项目配置文件：

• .NET：在 "BEARER_TOKEN": "" 中的每个配置文件内，将 "BEARER_TOKEN_<SERVER_NAME>": "" 和/或 environmentVariables 添加到 Properties/launchSettings.json。 该命令仅更新已定义这些密钥的配置文件。
• Python/Node.js：在运行前使用 .env 和/或 BEARER_TOKEN= 创建 BEARER_TOKEN_<SERVER_NAME>= 文件。 如果文件缺失，该命令将跳过保存并显示指导。

步骤 4：环境变量参考

通过配置以下必需的环境变量来完成环境设置：

• 身份验证变量 - 代理身份验证所需的设置
• MCP 终结点配置 - 指定代理 365 平台终结点
• 可观测性变量 - 启用日志记录和分布式跟踪
• 代理应用程序服务器配置 - 配置代理服务器运行位置的端口

身份验证变量

配置代理身份验证正常运行所需的身份验证处理程序设置。

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

持有者令牌变量（仅限本地开发）

MCP 终结点配置

指定你的代理连接的Agent 365平台端点。 当你生成定义代理 工具服务器 的工具清单时，指定MCP平台端点。 此终结点确定 MCP 工具服务器连接到哪个环境（预生产、测试或生产），以便实现 Microsoft 365 集成功能。

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

可观测性变量

配置这些必需的变量，以便为代理启用日志记录和分布式跟踪。 有关环境变量、配置选项和代码示例的完整列表，请参阅 代理可观测性。

代理应用程序服务器配置

配置运行代理应用程序服务器的端口。 此设置是可选的，适用于Python和 JavaScript 代理。

# Server Configuration
PORT=3978

# Server Configuration
PORT=3978

安装依赖项并启动代理应用程序服务器

配置好环境后，安装所需的依赖，并在本地启动代理应用服务器进行测试。

安装依赖项

uv pip install -e .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

你的代理服务器现在正在运行，已准备好接收来自 Agents Playground 或Microsoft 365应用程序的请求。

在Agents Playground中进行智能体测试。

Agents Playground 是一种本地测试工具，用于模拟Microsoft 365环境，而无需完整的租户设置。 这是验证代理的逻辑和工具调用的最快方法。 有关详细信息，请参阅 “使用代理场进行测试”。

配置Agents Playground以实现智能代理认证

使用代理身份验证时，请使用代理的详细信息配置 Agents Playground YAML 文件：

1. 设置配置文件：在运行Agents Playground的文件夹里创建或更新文件 .m365agentsplayground.yml 。 有关详细的设置说明，请参见 “自定义Teams上下文”。

2. 更新机器人配置：将以下机器人详细信息添加到你的 .m365agentsplayground.yml 文件中，将占位符值替换为你的实际代理凭证：

   bot:
     id: <your-agent-email>@<your-tenant>.onmicrosoft.com
     name: <Your Agent Name>
     role: agenticUser
     agenticUserId: <your-agentic-user-id>
     agenticAppId: <your-agentic-app-id>
   

   财产	Description	必选
   id	你的客服用户的电子邮件地址格式如下 agentusername@tenant.onmicrosoft.com	Yes
   name	代理用户的显示名称	Yes
   role	必须设置为agenticUser以用于Agent认证	Yes
   agenticUserId	代理用户的对象ID。 在代理用户的配置文件页上的Microsoft Entra管理中心中找到此值。	Yes
   agenticAppId	代理用户的代理ID。 在代理用户的配置文件页上的Microsoft Entra管理中心中找到此值。	Yes

打开新终端（Windows上的 PowerShell），并启动 Agents Playground：

agentsplayground

该命令会打开带有代理游乐场界面的网页浏览器。 该工具显示一个聊天界面，可在其中向代理发送消息。

基本测试

首先验证代理是否已正确配置。 向代理发送消息

What can you do?

代理会根据配置中的指令，以及你的系统提示和能力进行回复。 这条回复证实了：

• 你的代理程序正在正常运行。
• 代理可以处理消息并进行响应。
• Agents Playground 与您的代理之间的沟通正常。

测试工具调用

在配置 MCP 工具服务器 toolingManifest.json （详见“ 工具 设置说明”）后，通过以下示例测试工具调用：

首先，验证哪些工具可用：

List all tools I have access to

然后，测试特定的工具调用：

邮件工具

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

预期回复：代理通过邮件MCP服务器发送邮件并确认消息已发送。

日历工具

List my calendar events for today

预期回复：智能助手会检索并显示您当天的日历活动。

SharePoint工具

List all SharePoint sites I have access to

预期响应：代理SharePoint查询，并返回有权访问的网站列表。

可以在以下环境中查看工具调用：

• 聊天窗口 - 查看代理的响应和任何工具调用。
• 日志面板 - 查看详细的活动信息，包括工具参数和响应。

使用通知活动进行测试

在本地开发过程中，使用Agents Playground内置的通知触发器测试通知场景。

在测试通知活动之前，请确保：

• 配置所需的MCP工具服务器到您的toolingManifest.json。 详细了解工具。
• 为你的代理人启用通知。 了解如何设置通知。
• 配置文件，包含代理认证详情，如中所述的配置代理操场以进行代理认证。

测试邮件通知

测试电子邮件通知处理：

1. 启动你的代理程序和代理测试环境。
2. 在Agents Playground中，选择 模拟活动>触发通知活动。
3. 选择发送电子邮件。
4. 在有效载荷对话框中，根据需要更新模拟邮件的详细信息，如发件人姓名和邮件正文内容。
5. 选择“ 发送活动”。
6. 在聊天对话和日志面板中查看结果。

代理会收到模拟邮件通知，并根据你的通知处理逻辑进行处理。 有关电子邮件通知负载结构的详细信息，请参见 电子邮件通知负载。

测试Word提及通知

若要测试Word文档中的提及通知：

1. 启动你的代理程序和代理测试环境。
2. 在Agents Playground中，选择 模拟活动>触发通知活动。
3. 选择 在 Word 中提及。
4. 在载荷对话框中，根据需要更新模拟评论详细信息，例如文档 ID 和评论文本。
5. 选择“ 发送活动”。
6. 在聊天对话和日志面板中查看结果。

代理收到模拟的Word提及通知，并根据预定的通知处理逻辑做出响应。 有关Word注释通知有效负载结构的详细信息，请参阅 Document 注释通知有效负载。

测试代理安装和卸载事件

当 Agents Playground 连接到代理时，它会自动发送一个包含InstallationUpdate并执行add操作的活动。 如果实现安装处理程序，则建立连接后，代理的欢迎消息会立即显示在聊天中。

要验证安装事件处理：

1. 启动代理服务器。
2. 打开代理工具尝试场。 操控台连接到您的代理并自动触发安装事件。
3. 确认欢迎消息在聊天窗口中显示。

有关实现处理程序的详细信息，请参阅 Handle 代理安装和卸载事件。

查看可观测性日志

若要在本地开发期间查看可观测性日志，请为代理添加可观测性代码（请参阅可观测性获取代码示例），并配置环境变量，如可观测性变量中所述。 有关分步验证说明和预期的日志输出，请参阅 本地验证。配置后，实时跟踪将显示在控制台中，显示：

• 代理调用追踪
• 工具执行详细信息
• LLM 推理调用
• 输入和输出消息
• 令牌使用情况
• 响应时间
• 错误信息

这些日志帮助你调试问题，理解代理行为，优化性能。 在发布之前，使用 用于存储发布的验证 以确认所有必需的属性都存在。

后续步骤

在本地测试代理后，将其部署到Azure并将其发布到Microsoft 365。

若要在 Teams、Word 和 Outlook 等Microsoft 365应用程序中测试代理，请参阅 Agent 365 开发生命周期。

故障排除

本节提供你在本地测试代理时可能遇到的常见问题解决方案。

连接与环境问题

这些问题与网络连接、端口冲突和环境设置问题有关，这些问题可防止代理正确通信。

代理工作环境连接问题

症状：Agents Playground 无法连接到您的代理。

解决方法：

• 确认你的代理服务器是否在运行。
• 检查你的代理和代理Playground之间的端口号是否匹配。
• 确保没有防火墙规则阻止本地连接。
• 试着重启 Agent 和 Agents Playground。

过时的Agents Playground版本

症状：Agents Playground中出现意外错误或缺失功能。

解决方案：卸载并重新安装Agents Playground。

winget uninstall agentsplayground
winget install agentsplayground

端口冲突

症状：错误提示端口已在使用中。

解决方案；

• 停止你的代理的其他任何实例。
• 在你的配置中更改端口。
• 关闭所有使用该端口的进程。

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

无法添加 DeveloperMCPServer

症状：尝试在 Visual Studio Code 中添加 DeveloperMCPServer 时出错。

解决方案：关闭并重新打开 Visual Studio Code，然后再次尝试添加服务器。

认证与令牌问题

当代理无法使用Microsoft 365服务正确进行身份验证或凭据过期或配置错误时，会出现这些问题。

症状：

• 401 未经授权的错误
• “持有令牌过期”消息
• 代理身份验证失败

根本原因：

• 代币大约一小时后过期
• 错误的认证配置
• 凭据缺失或无效

解决方案：

• 关于承载令牌的过期

  刷新你的令牌并更新环境变量。

  # Get a new token
  a365 develop get-token
  
  # Update your .env file with the new token
  

• 对于每个服务器的持票者令牌失败

  验证配置文件是否具有每个服务器的占位符条目（BEARER_TOKEN_<SERVER_NAME>），然后重新运行 a365 develop get-token 以填充它们。 SDK 通过将mcpServerName中的ToolingManifest.json大写并用下划线替换连字符来生成变量名称（例如，mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS）。

• 代理身份验证错误（Python）

  请检查您的 .env 文件：

  # Should be (with underscore):
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION
  
  # Not:
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection
  

• 关于缺少凭证

  考试前确认是否具备所需资质。

  确保 .env 或 appsettings.json 包含：

  • API 密钥与秘密
  • 租户 ID
  • 客户端 ID
  • 蓝图ID（如果使用代理认证）

  验证：

  在Agents Playground中用一个简单的请求测试。 你应该会收到没有401错误的回复。

• 工具与通知问题

  这些问题涉及工具调用、MCP服务器交互以及通知传递等问题。

未收到电子邮件

症状：代理指示已发送电子邮件，但你未收到它

解决方法：

• 检查你的垃圾邮件或垃圾文件夹。
• 邮件的送达可能会延迟几分钟。 等五分钟。
• 请确认收件人邮箱地址是否正确。
• 检查代理日志，检查发送邮件时的任何错误。

Word注释响应不起作用

已知的问题：通知服务当前无法直接响应Microsoft Word中的批注。 此功能正在开发中。

消息无法传达到客服

症状：你的代理应用没有收到发送给代理的 Teams 消息。

可能原因：

• 开发者门户未配置代理模板。
• Azure Web 应用问题（部署失败、应用未运行、配置错误）。
• Teams里的代理实例创建得不正确。

解决方法：

• 验证开发者门户配置：

  确保你在开发者门户中完成了代理蓝图配置。 学习如何在开发者门户中配置代理蓝图。

• 检查 Azure Web 应用运行状况：

  如果将代理部署到Azure，请验证 Web 应用是否正常运行：

  1. 转到 Azure 门户。
  2. 访问你的网页应用资源。
  3. 检查 概览>状态 （应显示“运行中”）。
  4. 在监控下检查日志流是否有运行时错误。
  5. 请查看 部署中心 日志以确认部署成功。
  6. 验证 配置>应用设置 包含所有必要的环境变量。

• 验证代理实例创建：

  确保在Microsoft Teams中正确创建代理实例：

  1. 打开Microsoft Teams。
  2. 去 应用 里搜索你的经纪人。
  3. 请确认该代理是否出现在搜索结果中。
  4. 如果未找到，请验证是否已在 Microsoft 365 管理中心 - 代理中发布。
  5. 通过在代理中选择添加来创建新实例。
  6. 详细说明请参见 机载代理。

排查可观测性日志问题

如果代理的可观测性日志未按预期显示，请参阅可观测性指南中的 故障排除 。