创建代理实例

发布代理并在 Microsoft 管理中心提供后，你可以创建代理实例和代理用户。这些实例和用户使用你创建的代理蓝图和代理代码。

本文将整个过程分为三个主要步骤：

在Teams开发者门户中配置代理
创建代理实例
测试你部署的代理

如果遇到挑战，请参阅 “故障排除 ”部分。

先决条件

代理蓝图已正确设置，如安装代理蓝图步骤中所述。
代理应用程序已正确发布，如将代理发布到Microsoft管理中心中所述。

1. 在 Teams 开发者门户中配置代理

发布后，在 Teams 开发人员门户中配置代理蓝图，将代理连接到Microsoft 365消息传送基础结构。如果没有此配置，代理不会从 Teams、电子邮件或其他Microsoft 365服务接收消息。

获取你的蓝图ID

在工作目录中打开 a365.generated.config.json 并复制 agentBlueprintId 该值。
进入开发者门户

打开浏览器，进入配置页面：
```
https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
```
用你复制的<your-blueprint-id>数值替换agentBlueprintId。

注释

如果您无法访问开发者门户，请联系租户管理员授权或代您完成此配置。
配置代理

在开发者门户中：
1. 将 代理类型 设置为 基于 API
2. 将 通知 URL 设置为代理的消息传送终结点。在messagingEndpoint中查找a365.generated.config.json的值。
3. 选择“保存”。

你需要先完成这个配置，才能在Teams中创建代理实例。

详细了解代理标识蓝图和开发人员门户配置。

2. 创建代理实例

现在你可以向 Microsoft Teams 请求代理蓝图实例。了解更多关于如何发现、创建和引入经纪人的信息。

当你请求代理实例时，Teams 会将请求发送给租户管理员进行批准。管理员可以从 Microsoft 管理中心 - 请求的代理页面审核并批准请求。

管理员批准你的请求后，Teams 会创建你的代理实例并让它在 Teams 中可用。

3. 测试您部署的代理程序

创建代理实例后，在Microsoft 365中对其进行测试，以确保它在生产环境中正常运行。

部署后，在代理 365 SDK 中启用了代理通知后，代理会与Microsoft 365服务集成。它支持 Teams 中的聊天、频道和会议；支持电子邮件和日历的发送、接收和安排；以及支持 SharePoint 和 OneDrive 的文档访问和文件共享。它还支持协作功能，如组织在线状态、Planner 任务和文档评论。

重要

与普通用户一样，代理用户还需要适当的Microsoft 365许可证才能访问服务。常见许可证包括 Microsoft 365 E5、Teams Enterprise 和智能 Microsoft 365 Copilot 副驾驶®。

在管理中心查看已部署的代理

发布代理后，它会出现在Microsoft管理中心的招聘页面。传播可能需要一些时间。

转到 Microsoft 365 管理中心 - 代理：

查看已发布的代理
管理代理设置
监视代理使用情况
配置权限

Teams 中的测试代理

部署、发布和配置代理蓝图并创建代理用户后，直接在 Microsoft Teams 中测试代理用户：

开始测试

在 Teams 中搜索你新的代理用户。

注释

代理用户创建过程是异步的。创建代理用户后，可能需要几分钟到几个小时才能被搜索到。
用你新创建的代理实例发起新聊天。
发送测试消息以验证代理功能。

测试消息示例

如果你用电子邮件配置了代理，发送此消息以测试邮件功能。更新收件人 recipient@contoso.com 的邮箱地址。

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

客服处理请求并发送邮件，无需额外确认。

核查清单

创建代理实例后，确认它在Teams中是否正常工作。

✅ 开发者门户配置已保存
✅ 代理出现在Teams应用搜索中
✅ 您可以创建实例代理以用于 Teams
✅ 创建代理实例
✅ 代理用户出现在组织中
✅ 代理响应消息
✅ 代理可以执行动作
✅ 应用日志显示无错误
✅ 管理中心中的可观察性功能

如果你的代理实例没有按预期工作，请参见“ 故障排除”部分，了解常见问题的详细解决方案。

确认开发者门户配置已保存

导航到：https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ 代理类型 显示：基于 API 的✅通知 URL 匹配你的代理的消息终结点，然后✅ 显示已成功保存消息

验证代理程序出现在Microsoft Teams中

打开 Teams >应用
搜索你的代理人姓名

✅ 代理会出现在搜索结果中 ✅ 显示您的代理图标和说明

确认你能为Teams创建实例代理

在 Teams 应用中选择您的代理

✅“请求实例/创建实例”按钮已启用✅“可以请求实例而不出错”

验证代理实例已创建

选择 请求实例后：

✅ 请求成功发送给管理员

验证代理用户是否存在于组织中

在Microsoft 365管理中心：

转到：https://admin.cloud.microsoft/#/agents/all
导航至“所有代理请求”选项卡

✅ 您的代理实例请求被列为待审核状态 ✅ 管理员可以批准代理实例以供使用 ✅ 用户可以从 Teams 创建实例并为其命名。

验证代理对消息的响应

在与客服的聊天中，发送测试消息：Hello!

✅ 代理显示键入指示器 ✅ 代理在几秒钟 ✅ 内响应响应是一致的且相关

验证代理是否能够执行操作

如果配置工具，测试工具功能。例如，如果添加邮件 MCP 服务器，请向自己发送测试电子邮件。

代理人应当：

✅ 确认请求 ✅ 执行工具调用 ✅ 确认成功完成

你应该确认邮件是否已到达你的收件箱。

验证功能

以下清单为您的代理提供了系统的测试方法：

基本功能：

✅ 特工回应简单的问候。 ✅ 代理处理多步对话。 ✅ 代理人提供相关回应。

工具功能：

这取决于MCP服务器配置

✅ 可以发送邮件。 ✅ 可以访问日历。 ✅ 可以搜索文件。 ✅ 可以执行配置好的动作。

错误处理：

✅ 优雅地处理无效请求。 ✅ 提供有用的错误信息。 ✅ 不会因为突发输入而崩溃。

性能：

✅ 几秒钟内回复。 ✅ 没有超时错误。 ✅ 响应时间稳定。

核实应用日志

若要查看代理正在执行的操作，请使用 az webapp log tail 命令检查应用程序日志。

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

日志中应注意的事项：

✅ Teams 的传入请求 ✅ 成功的身份验证 ✅ 工具调用正在执行 ✅ 发送响应 ❌ 错误消息或异常

在管理中心验证可观察性

代理人开始跑后：

转到：https://admin.cloud.microsoft/#/agents/all。
选择您的代理人并打开活动标签。

你应该会看到：

✅ 会话出现。 ✅ 每次会话都会显示触发器和动作。 ✅ 工具调用会有时间戳记录。

后续步骤

你的代理现在位于云中，可以与团队一起在 Microsoft 365 工作。最初是本地代码的项目，现在已成为一个注册的、企业就绪的助手，用户可以在整个组织中创建智能代理实例。

您的代理开发生命周期已经完成，但其影响才刚刚开始。代理 365 开发人员生命周期中构建的大部分内容都是开放源代码，欢迎社区贡献。提出错误、功能需求和合并请求：

Agent 365 Samples：有没有有趣和好玩的示例特工？在此处与开放源代码社区共享代理代码！
Node.js SDK：Node.js中的代理 365 SDK。
Python SDK：Python 中的代理 365 SDK。
.NET SDK：C# 中的代理 365 SDK（.NET）。
代理 365 DevTools CLI：一个 CLI，可帮助你完成整个代理 365 开发生命周期。

故障排除

本节包含创建和测试代理实例时的常见问题。

小窍门

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

Agent 不会出现在 Teams 中

症状： 代理显示在管理中心，但无法在 Teams 应用中找到它。

根本原因： 缺少开发者门户配置。

Solution:

从 a365.generated.config.json 中获取蓝图 ID，然后查找 agentBlueprintId。
在开发者门户中配置：
1. 转到：https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
2. 将 代理类型 设置为 基于 API
3. 将 通知 URL 设置为代理的消息传送终结点。在messagingEndpoint中查找a365.generated.config.json的值。
4. 选择“保存”。
等5-10分钟让它繁殖。

验证：

打开 Teams > 应用 > 搜索代理人。
此时会显示代理，可供添加。

无法在Teams中创建代理实例

症状： 代理显示在 Teams 中，但无法添加或创建实例; “请求实例 ”按钮不起作用。

根本原因： 租户未启用 Microsoft Agent 365 Frontier。

解决方案： 请与租户管理员联系，验证是否为租户启用了代理 365 Frontier Microsoft。

详细了解 Frontier。

验证：

许可证和管理员设置允许后，前沿功能会显示在智能 Microsoft 365 Copilot 副驾驶® 和 Microsoft 365 应用中。

代理未回复消息

症状： 创建代理实例，但它不会响应消息。在应用程序中看不到任何日志。

根本原因： 多种可能原因——消息端点问题、认证问题或配置错误。

基本故障排除

确认网页应用正在运行：

az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

检查消息端点：
- 应该是： https://<your-app-root-url>/api/messages
- 在 a365.config.json 和 a365.generated.config.json 中验证

直接测试终点：

curl https://<your-app-root-url>/api/messages
# Should not return 404

查看申请日志：

az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

高级诊断

验证身份验证：
- 检查代币是否过期。如果需要，可以更新。
- 在网页应用配置中进行凭证验证。
检查工具/MCP配置：
- 确认MCP服务器已配置。
- 请检查权限是否已被授予。
本地测试：
- 本地运行代理，配置相同。
- 在 Agents Playground 中进行测试。
- 本地运行正常但云端部署存在 > 问题

常见解决方法

消息终结点不正确：请在 Azure 门户和开发人员门户中更新。
Web 应用已停止： 使用 Azure 门户或 CLI 启动它。
令牌已过期： 更新 Web 应用环境变量中的令牌。
缺少环境变量： 在 Azure 门户中检查应用设置。
MCP 服务器问题： 验证服务主体和权限。
代码错误： 检查应用程序日志是否有异常。

验证

在Teams里给你的客服发消息，查看申请日志是否有收到的请求。

你也可以尝试：

工具调用失败

症状： 代理会响应消息，但工具调用失败。你会看到权限被拒或超时错误。

根本原因： 缺少MCP服务器权限、服务主体未配置、网络连接问题或工具配置错误。

解决方案

当工具调用失败时，尝试以下解决方案：

在管理中心验证权限

审核并批准所需的MCP服务器权限：
- 转到：https://admin.cloud.microsoft/#/agents/all
- 选择您的代理 > 权限
- 确保列表包含并批准了所需的MCP服务器

检查服务主体

如果你之前没运行过一次性设置脚本，请执行：

# Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

验证MCP端点配置

确保您使用的是生产环境的MCP端点。

# Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft

检查管理身份

验证你的 Web 应用已启用托管标识：

# Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

验证

使用Teams调用测试工具，并检查日志以确认成功执行。

可能还需要尝试以下步骤：

许可证转让失败

症状： 无法向代理用户分配许可证。在管理中心看到许可错误。

根本原因： 可用的许可证数量不足、许可证类型错误或权限问题。