创建代理实例

重要

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

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

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

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

遇到困难，请参阅 故障排除 部分。

先决条件

• 代理蓝图按照设置代理蓝图步骤正确设置。
• 代理应用程序已按照发布代理到 Microsoft 管理中心的要求正确发布。

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

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

1. 获取你的蓝图ID

   运行 a365 配置显示 -g 命令 来显示你的配置：

   a365 config display -g
   

   从输出中复制agentBlueprintId值。

2. 进入开发者门户

   打开浏览器，进入配置页面：

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

   用你复制的<your-blueprint-id>数值替换agentBlueprintId。

   注释

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

3. 配置代理

   在开发者门户中：

   1. 将 代理类型 设置为 基于机器人
   2. 将 机器人ID 设置为你的 agentBlueprintId 数值
   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中测试代理用户：

注释

需要启用 Frontier： 确保你的租户启用了 Microsoft Agent 365 Frontier，并且管理员需授予你访问权限。 在代理 365 处于预览状态时，需要此访问权限才能在 Microsoft Teams 中创建代理实例并与代理交互。 了解更多关于Frontier的信息 如果你无法访问，请联系你的租户管理员。

开始测试

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

   注释

   代理用户创建过程是异步的，创建后代理用户可能需要几分钟到几小时才能被搜索。

2. 用你新创建的代理实例发起新聊天。

3. 发送测试消息以验证代理功能。

测试消息示例

如果你用电子邮件配置了代理，发送此消息以测试邮件功能。 更新收件人 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

✅ 代理类型 显示： 基于机器人
✅ 机器人ID 与您的相匹配 agentBlueprintId
✅显示已保存成功的信息

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

1. 打开 Teams >应用

2. 搜索你的代理人姓名

   ✅ 代理出现在搜索结果中
   ✅ 显示你的代理人图标和描述

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

在 Teams 应用中选择您的代理

✅请求实例/创建实例按钮已启用
✅ 可以请求实例而无错误

验证代理实例已创建

选择 请求实例后：

✅ 请求成功发送给管理员

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

在Microsoft 365管理中心：

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

✅ 你的代理实例请求当前状态为待审核
✅ 管理员可以批准代理实例的使用权限
✅ 用户可以从 Teams 创建实例并命名。

验证代理对消息的响应

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

✅ 代理显示输入状态指示器
✅ 客服几秒钟内就回应了
✅ 回应连贯且相关

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

如果工具已配置好，测试工具功能。 例如，如果你添加了Mail 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 的请求
✅ 认证成功
✅ 执行中的工具调用
✅ 回复正在发送
❌ 错误消息或异常

在管理中心验证可观察性

代理人开始跑后：

1. 转到：https://admin.cloud.microsoft/#/agents/all

2. 选择您的代理人并打开 活动 标签。

   你应该会看到：

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

后续步骤

你的代理现在位于云中，可以与团队一起在 Microsoft 365 工作。 最初作为本地代码的系统，现在已经变成了一个可发现、企业级的助手，用户可以在组织内创建代理实例。

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

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

Troubleshooting

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

小窍门

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

Agent 不会出现在 Teams 中

症状： 代理出现在管理中心，但在Teams应用里找不到。

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

Solution:

1. 获取你的蓝图ID：

   a365 config display -g
   # Copy the agentBlueprintId value
   

2. 在开发者门户中配置：

   1. 转到：https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   2. 将 代理类型 设置为 基于机器人
   3. 将 机器人ID 设置为你的 agentBlueprintId
   4. 选择“保存”

3. 等5-10分钟让它繁殖。

验证：

• 打开 Teams > 应用 > 搜索您的代理
• 代理已上线并可供添加

无法在Teams中创建代理实例

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

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

解决方案： 请联系你的租户管理员，确认租户已启用 Microsoft Agent 365 Frontier。

了解更多关于Frontier的信息

验证：

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

代理未回复消息

症状： 创建了代理实例，但它不回复消息;应用里没有日志。

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

基本故障排除

1. 确认网页应用正在运行：

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

2. 检查消息端点：

   • 应该是： https://<your-app-root-url>/api/messages
   • 在 a365.config.json 和 a365.generated.config.json 中验证

3. 直接测试终点：

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

4. 查看申请日志：

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

高级诊断

1. 验证身份验证：

   • 检查代币是否过期。 如果需要，可以更新。
   • 在网页应用配置中进行凭证验证。

2. 检查工具/MCP配置：

   • 确认MCP服务器已配置。
   • 请检查权限是否已被授予。

3. 本地测试：

   • 本地运行代理，配置相同。
   • 在 Agents Playground 中进行测试。
   • 本地运行正常但云端部署存在 > 问题

常见解决方法

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

验证

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

你也可以尝试：

• 排查部署代理到亚马逊网络服务时的故障
• 部署代理到 Google Cloud Platform 的故障排查

工具调用失败

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

根本原因： 缺少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调用测试工具，并检查日志以确认成功执行。

你也可以尝试以下步骤：

• 工具故障排除
• 故障排查模拟工具服务器

许可证转让失败

症状： 无法将许可分配给代理用户;管理中心的许可错误。

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

解决方案

当许可证转让失败时，请尝试以下解决方案：

1. 核实许可证的可用性：

   • 检查 Microsoft 365 管理中心 >计费>许可证
   • 确保租户启用了 Microsoft Agent 365 Frontier

2. 手动分配许可：

   • 转到 Microsoft 365 管理中心 >Users
   • 找到智能用户
   • 分配适当的许可

3. 完整功能所需的许可：

   • Microsoft 365 E5 （或等效）
   • Teams Enterprise
   • Microsoft 365 Copilot（适用于Copilot功能）

验证

查看管理员中心的用户资料，显示已分配的许可证。