通过

使用 Microsoft Agent 365 SDK 测试代理

重要提示

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

在智能体操场中本地测试智能体 本指南介绍如何使用 Agents Playground 测试工具设置开发环境、配置身份验证和验证代理的功能。

代理在本地工作后，可以 部署并发布 它，以在 Microsoft 365 个应用程序（如 Teams）中进行测试。

先决条件

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

常见的先决条件

特定于语言的先决条件：

配置代理测试环境

本部分介绍如何设置环境变量、对开发环境进行身份验证，以及准备用于测试的 Agent 365 电源代理。

设置代理测试环境遵循顺序工作流：

  1. 配置环境 - 创建或更新环境配置文件

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

  3. 配置身份验证 - 设置代理身份验证

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

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

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

步骤 1：配置环境

设置配置文件

cp .env.template .env

备注

请参阅Microsoft代理 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：为代理标识身份验证配置身份验证值

使用 A365 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

备注

对于 .NET，还要确保 USE_AGENTIC_AUTH=true 已设置（ launchSettings.json 请参阅 步骤 4：环境变量参考）

步骤 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 终结点配置

需要 MCP（模型上下文协议）终结点配置来指定代理应连接到的代理 365 平台终结点。 生成定义 代理工具服务器 的工具清单时，必须指定 MCP 平台终结点。 此终结点确定 MCP 工具服务器连接到哪些环境（预生成、测试或生产），以便Microsoft 365 集成功能。

将 添加到 文件：

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

重要说明： MCP_PLATFORM_ENDPOINT 如果未指定，则默认为生产终结点。

可观测性变量

配置这些必需的变量，以便为代理启用日志记录和分布式跟踪。 详细了解可观测性特征和最佳做法

备注

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

变量 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：

uv run python <main.py>

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

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

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

备注

在使用代理认证时，Agents Playground 目前不支持直接消息。 你必须通过自定义活动来测试。 详情请参见 带通知活动的测试 。

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

agentsplayground

这会打开包含 Agents Playground 界面的 Web 浏览器。 该工具显示一个聊天界面，可在其中向代理发送消息。

基本测试

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

What can you do?

代理应根据代理的系统提示和功能，使用配置的说明进行回复。 确认 为

  • 代理正常运行
  • 代理可以处理消息和响应
  • 代理场与代理之间的通信正在工作

测试工具调用

在toolingManifest.json配置 MCP 工具服务器（请参阅安装说明的工具）中后，测试工具调用的示例如下：

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

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 中的自定义活动来测试通知方案。 这样，就可以在将代理的通知处理部署到生产环境之前对其进行验证。

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

通知需要适当的工具配置和通知设置才能正常工作。 可以使用自定义活动功能测试电子邮件通知或 Word 注释等方案。

发送自定义活动：

  1. 启动代理和代理场
  2. 在 Agents Playground 中，导航到 模拟活动>自定义活动
  3. conversationId复制活动中的内容（每次重启代理场时会话 ID 都会更改）
  4. 粘贴自定义活动 JSON，并使用复制的对话 ID 更新 personal-chat-id 字段。 请参阅电子邮件通知示例
  5. 选择添加活动。
  6. 在聊天对话和日志面板中查看结果

电子邮件通知

这会模拟发送到代理的电子邮件。 将此占位符值替换为实际详细信息。

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

查看可观测性日志

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

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

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

故障排除

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

连接和环境问题

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

代理场连接问题

症状：代理场无法连接到代理

解决方案：

  • 验证代理服务器是否正在运行
  • 检查代理和代理场之间的端口号是否匹配
  • 确保没有防火墙规则阻止对 Blob 容器的访问。
  • 尝试重启代理和代理场

过时的代理场版本

症状：代理场中出现意外错误或缺少功能

解决方案：卸载并重新安装代理场：

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 未经授权的响应

解决方案：持有者令牌在大约 1 小时后过期。 获取新令牌并更新配置。

Python 中的代理身份验证错误

症状：获取代理实例令牌时出错

解决方案：验证 ALT_BLUEPRINT_NAME 以下设置 .env：

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

已知问题和通知

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

未收到电子邮件

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

解决方案：

  • ✅ 请检查垃圾邮件文件夹。
  • 电子邮件传递可能会延迟几分钟 - 最多等待 5 分钟
  • 验证收件人电子邮件地址是否正确
  • 在发送电子邮件期间检查代理日志中是否存在任何错误

Word 注释响应不起作用

已知问题：通知服务当前无法直接响应 Word 注释。 此功能即将弃用。

获取帮助

如果遇到此故障排除部分中未涵盖的问题，请浏览以下资源：

Microsoft代理 365 SDK 存储库

更多支持

  • 查看 Microsoft Agent 365 SDK 存储库中的 示例代码和文档
  • 通过相关存储库中的 GitHub 问题提交问题

后续步骤

在本地成功测试代理后，即可将其部署到 Azure 并将其发布到 Microsoft 365：

  • 部署和发布代理：学习如何将代理部署到 Azure Web 应用并发布到 Microsoft 管理中心，使您的组织能够在 Microsoft 365 中发现并创建代理实例。
  • Last updated on