创建代理实例

重要

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

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

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

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

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

先决条件

• Agent Blueprint 按照 Setup Agent Blueprint 步骤正确设置。
• 代理应用按照发布代理程序正确发布 到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. 创建代理实例

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

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

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

3. 测试你部署的特工

创建代理实例后，在 Microsoft 365 中测试，确保其在生产环境中正常工作。

部署完成后，在 Agent 365 SDK 中启用代理通知后，您的代理将与 Microsoft 365 服务集成。 它支持Teams的聊天、频道和会议;配备电子邮件和日历，用于发送、接收和安排;以及通过SharePoint和OneDrive实现文档访问和文件共享。 它还支持协作功能，如组织存在感、规划工具任务和文档注释。

重要

与普通用户一样，代理用户也需要相应的 Microsoft 365 许可证才能访问服务。 常见许可证包括Microsoft 365 E5、Teams Enterprise 和 Microsoft 365 Copilot。

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

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

前往 Microsoft 365 管理中心 - 代理 访问：

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

Teams 中的测试代理

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

注释

需要边境： 确保你的租户启用了 Microsoft Agent 365 Frontier，并且管理员需要授权你访问。 在 Agent 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
✅显示已保存成功的信息

验证代理出现在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中协作。 最初作为本地代码的系统，现在已经变成了一个可发现、企业级的助手，用户可以在组织内创建代理实例。

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

• Agent 365 Samples：有有趣又有趣的样品特工吗？ 在这里与开源社区分享你的代理代码！
• Node.js SDK：Node.js 中的 Agent 365 SDK
• Python SDK：Agent 365 Python SDK
• .NET SDK：C# （.NET） 中的 Agent 365 SDK。
• 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的信息

验证：

一旦许可和管理员设置允许，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. 本地测试：

   • 本地运行代理，配置相同。
   • 用特工游乐场测试。
   • 本地运行但云端部署不 > 行

常见解决方法

• 消息端点错误： Azure 门户和开发者门户更新
• 网页应用停止了： 用 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
  

• 检查管理身份

  验证你的网页应用已启用托管身份：

  # 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 管理中心 >用户
   • 找到智能用户
   • 分配适当的许可

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

   • Microsoft 365 E5（或同等型号）
   • Teams Enterprise
   • Microsoft 365 Copilot（用于 Copilot 功能）

验证

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