通过

通过使用 Microsoft Agent 365 SDK 测试代理

重要

需要成为 Frontier 预览计划的一部分，才能获得 抢先体验Microsoft Agent 365。 边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。 由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

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

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

先决条件

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

常见的先决条件

特定于语言的先决条件：

  • Python 3.11 或更高版本：从 python.org 或 Microsoft Store 下载
  • uv package manager：使用安装 uv
  • 验证安装：python --version

配置代理测试环境

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

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

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

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

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

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

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

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

步骤 1：配置环境

设置您的配置文件

cp .env.template .env

备注

关于显示所需字段的配置模板，请参见 Microsoft Agent 365 SDK 示例。

步骤 2：LLM配置

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

将.env添加到文件中：

# 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=

Python LLM 环境变量

变量 描述 必需的 示例
OPENAI_API_KEY OpenAI 服务的 API 密钥。 对于 OpenAI： sk-proj-...
AZURE_OPENAI_API_KEY Azure OpenAI 服务的 API 密钥 对于 Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI 服务终结点 URL 对于 Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Azure OpenAI 中的部署名称 对于 Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Azure OpenAI 的 API 版本 对于 Azure OpenAI 2024-02-15-preview

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

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

  • 代理认证 ——用于生产场景中存在代理用户身份时的使用。
  • OBO 认证 ——用于生产场景，当你需要委派用户权限但没有代理用户身份时。
  • 持有令牌认证 ——仅用于早期开发和测试场景，生产认证尚未配置。

代理认证

使用Agent 365的CLI a365 config display 命令获取您的代理蓝图凭证。

a365 config display -g

此命令显示代理蓝图配置。 复制以下值：

值 描述
agentBlueprintId 您的代理客户端 ID
agentBlueprintClientSecret 代理的客户端密钥
tenantId Microsoft Entra租户标识

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

将以下设置添加到 .env 文件中，替换占位符为你的实际凭证信息：

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 代理蓝图客户端 ID 来自 a365 config display -g 可以 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET 代理蓝图客户端密钥 a365 config display -g 可以 abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID 从 a365 config display -g 中 Microsoft Entra 租户 ID 可以 adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

OBO 身份验证

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

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

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

有关OBO流程的工作原理，请参见 认证流程。 有关完整的实现示例，请参阅Microsoft 365 Agents 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 服务器的承载令牌。
  • 使用 BEARER_TOKEN 环境变量更新项目配置文件。

在运行 get-token之前，请设置项目配置文件，以便命令知道在何处保存令牌：

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

备注

如果运行a365 develop get-token --app-id <id>时没有a365.config.json文件，令牌不会自动保存。 将它手动复制并粘贴到 Properties/launchSettings.json（.NET）或 .env 文件（Python/Node.js）。

持有人代币大约一小时后过期。 用 a365 develop get-token 来刷新过期的代币。

步骤 4：环境变量参考

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

身份验证变量

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

将.env添加到文件中：

# 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
变量 描述 必需的
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE 身份验证处理程序类型 可以
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Microsoft Graph的身份验证范围 可以
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME 备用蓝图连接名称 可以
CONNECTIONSMAP_0_SERVICEURL 连接映射的服务 URL 模式 可以
CONNECTIONSMAP_0_CONNECTION 映射的连接名称 可以

MCP 终结点配置

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

将.env添加到文件中：

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
变量 描述 必需的 默认 示例
MCP_PLATFORM_ENDPOINT MCP 平台端点 URL （预生产、测试或生产） 否 生产终结点

重要提示：如果你没有指定 MCP_PLATFORM_ENDPOINT，应用将使用生产端点。

备注

如果你使用 来自 CLI 的模拟工具服务器，请使用你所用的端口号将端点设置为 http://localhost:<port>。 默认端口是5309。

可观测性变量

配置这些必需的变量，以便为代理启用日志记录和分布式跟踪。 了解更多关于可观察性特征和最佳实践的信息。

备注

可观测性配置在所有语言中都是相同的。

变量 描述 默认 示例
ENABLE_A365_OBSERVABILITY 启用或禁用可观测性 false true
ENABLE_A365_OBSERVABILITY_EXPORTER 将跟踪输出到可观测性服务 false true
OBSERVABILITY_SERVICE_NAME 用于跟踪的服务名称 代理名称 my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE 服务命名空间。 agent365-samples my-company-agents

代理应用程序服务器配置

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

将.env添加到文件中：

# Server Configuration
PORT=3978
变量 描述 必需的 默认 示例
PORT 运行代理服务器的端口号 否 3978 3978

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

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

安装依赖项

uv pip install -e .

此命令读取在其中 pyproject.toml 定义的包依赖项，并从 PyPI 安装它们。 从零开始创建代理应用时，创建一个 pyproject.toml 文件来定义你的依赖关系。 示例存储库中的示例代理已定义这些包。 可以根据需要添加或更新它们。

启动代理应用程序服务器

python <main.py>

将 <main.py> 替换为包含代理应用程序的入口点的主Python文件的名称（例如，start_with_generic_host.py、app.py 或 main.py）。

或者用紫外线：

uv run python <main.py>

你的代理服务器现在正在运行，已准备好接收来自 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>
    资产 描述 必需的
    id 你的客服用户的电子邮件地址格式如下 agentusername@tenant.onmicrosoft.com 可以
    name 代理用户的显示名称 可以
    role 必须设置为agenticUser以用于Agent认证 可以
    agenticUserId 代理用户的对象ID。 在代理用户的配置文件页上的Microsoft Entra管理中心中找到此值。 可以
    agenticAppId 代理用户的代理ID。 在代理用户的配置文件页上的Microsoft Entra管理中心中找到此值。 可以

打开新终端（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内置的通知触发器测试通知场景。

Screenshot 显示扩展了“模拟活动”菜单的 Agents Playground 界面，显示触发通知活动选项，包括发送电子邮件和在 Word 中提及。

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

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

测试邮件通知

测试电子邮件通知处理：

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

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

测试Word提及通知

要测试Word文档提及通知：

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

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

测试代理安装和卸载事件

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

要验证安装事件处理：

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

显示 Agents Playground 界面的屏幕截图，其中在安装事件自动触发后，聊天对话和日志面板中出现了代理的欢迎消息：“谢谢雇用我！期待在您的职业旅程中协助您！”

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

查看可观测性日志

若要在本地开发期间查看可观测性日志，请为代理添加可观测性代码（请参阅可观测性获取代码示例），并配置环境变量，如可观测性变量中所述。 配置完成后，控制台中会出现实时追踪，显示：

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

这些日志帮助你调试问题，理解代理行为，优化性能。

后续步骤

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

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

故障排除

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

小窍门

Agent 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

  • 代理身份验证错误（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注释响应不起作用

Known 问题：通知服务当前无法直接对Word评论作出响应。 此功能正在开发中。

消息无法传达到客服

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

可能原因：

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

解决方法：

  • 验证开发者门户配置：

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

  • 检查 Azure Web App 健康状态：

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

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

  • 验证代理实例创建：

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

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