通过

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

重要提示

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

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

一旦你的代理本地运行，你可以按照 Agent 365 开发生命周期 ，在 Teams、Word 和 Outlook 等 Microsoft 365 应用中进行测试。

先决条件

开始之前，请确保具备以下先决条件：

常见的先决条件

特定于语言的先决条件：

  • Python 3.11 或更高版本： 可从 python.org 或 Microsoft 商店下载
  • uv package manager： 通过 使用 pip install uv
  • 验证安装：

配置代理测试环境

本节介绍如何设置环境变量、认证开发环境，以及准备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：配置

为本地测试配置 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=

Python LLM 环境变量

变量 Description 必须 示例
OPENAI_API_KEY OpenAI 服务的 API 密钥。 对于 OpenAI： sk-proj-...
AZURE_OPENAI_API_KEY Azure OpenAI 服务的 API 密钥。 对于 Azure OpenAI： a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI 服务终结点 对于 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

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

值 Description
agentBlueprintId 代理的客户端 ID
agentBlueprintClientSecret 代理的客户端密码
tenantId 你的 Microsoft Entra 租户 ID

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

将以下设置添加到 .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>
变量 Description 必须 示例
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 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

备注

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

步骤 2：环境变量

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

身份验证变量

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

将 添加到 文件：

# 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
变量 Description 必须
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 集成功能。

将 添加到 文件：

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
变量 Description 必须 默认 示例
MCP_PLATFORM_ENDPOINT MCP 平台终结点 URL （预生成、测试或生产） 否 对于生产终结点：

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

备注

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

可观测性变量

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

备注

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

变量 Description 默认 示例
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 代理。

将 添加到 文件：

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

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

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

安装依赖项

uv pip install -e .

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

启动应用程序服务器

python <main.py>

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

或者用紫外线：

uv run python <main.py>

您的代理服务器现在已运行，准备接收来自代理Playground或Microsoft 365应用的请求。

在智能体操场中测试智能体。

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

配置代理游乐场以实现代理认证

备注

该配置仅在使用 代理认证时要求。 如果你使用 持有令牌认证，可以跳过这一部分，直接进入 基础测试。

使用代理认证时，请配置代理的 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 可以
    name 代理用户的显示名称 可以
    role 必须设置为 以 agenticUser 实现代理认证 可以
    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内置的通知触发器测试通知场景。

截图显示了Agents Playground界面，并展开了模拟活动菜单，显示了触发通知活动选项，包括发送邮件和Word中提及。

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

  • 在你的 toolingManifest.json. 详细了解 工具
  • 为你的代理人启用通知。 了解如何设置通知
  • 按照.m365agentsplayground.yml中的描述，配置该文件，包含代理的代理认证详情。

测试邮件通知

测试电子邮件通知处理：

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

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

测试词提及通知

测试Word文档提及通知：

  1. 启动你的经纪人和代理游乐场。
  2. 在Agents Playground中，选择 模拟活动>触发通知活动。
  3. 选择在 Word中提及。
  4. 在有效载荷对话框中，根据需要更新模拟注释细节，如文档ID和注释文本。
  5. 选择“ 发送活动”。
  6. 在聊天对话和日志面板中查看结果。

代理会收到模拟的 Word 提及通知，并根据你的通知处理逻辑进行响应。 有关 Word 评论通知负载结构的详细信息，请参见 文档注释通知负载。

查看可观测性日志

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

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

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

后续步骤

成功本地测试代理后，你就可以部署到 Azure，并发布到 Microsoft 365。

遵循 Agent 365 开发生命周期 ，测试 Microsoft 365 应用程序，如 Teams、Word 和 Outlook。

故障排除

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

小窍门

Agent 365 故障排除指南包含了高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

连接与环境问题

这些问题涉及网络连接、端口冲突以及环境设置问题，可能阻碍你的代理正常通信。

代理游乐场连接问题

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

解决方案：

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

过时的代理场版本

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

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

winget uninstall agentsplayground
winget install agentsplayground

端口冲突

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

解决方案：

  • 停止你代理人的其他任何情况。
  • 在你的配置中更改端口。
  • 关闭所有使用该端口的进程。
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

无法添加 DeveloperMCPServer

症状：在VS 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 注释响应不起作用

已知问题：通知服务目前无法直接回复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