从代理应用程序迁移到新的代理终结点和发布体验

本指南介绍如何在 Microsoft Foundry 中更改代理发布体验。 它将旧模型（创建了单独的代理应用程序资源）与新的代理对象模型进行比较，并指导你迁移现有代理和已发布的应用程序。

更改概述

新的代理对象模型将代理应用程序和代理部署折叠到代理对象本身中。 以前，发布操作会创建一个具有自身标识、终结点和部署的单独智能体应用程序资源。 现在，每个代理都从创建它的那一刻起就拥有这些功能。

之前（旧模型）

1. 资源模型：代理（数据平面）、代理应用程序（控制平面）和部署（控制平面）是单独的对象。
2. 代理对象属性： id （代理的唯一标识符）， name以及 versions （最新代理版本）。
3. 标识：Foundry 项目中的未发布智能体共享一个 Entra 智能体标识和一个 Entra 智能体蓝图。 发布后，智能体会收到一个范围限定为智能体应用程序资源的唯一标识和蓝图。
4. 发布：两个手势。 首先，发布代理会创建代理应用程序资源和部署，其中部署引用已发布的代理版本。 代理应用程序公开一个稳健的终结点，将 100% 的流量路由到该版本。 部署支持启动/停止生命周期管理。 第二种手势是，代理应用程序随后可以发布到 Microsoft 365 和 Teams。

之后（新模型）

1. 资源模型：仅存在代理对象（数据平面和控制平面）。 它们承担了以前由代理应用程序与部署负责的职责。
2. 代理对象属性：id、、 nameversionsagent_endpoint（稳定终结点）、protocol_configuration、authorization_schemes、、version_selectorblueprint、和 instance_identityagent_card （向使用者和 A2A 呈现代理详细信息和功能）。
3. 标识：新创建的代理默认接收唯一的 Entra 代理蓝图和 Entra 代理标识。 支持自带 Entra 智能体蓝图，但不是默认选项。
4. 发布：两个等效手势。 首先，选择要通过稳定终结点公开的代理版本。 其次，将代理程序的稳定端点发布到 M365/Teams。

关键转变： 创建代理是 获取稳定终结点和唯一代理标识的唯一步骤。 该终结点不需要单独的发布步骤。 现在的发布特指通过 M365 和 Teams 渠道分发智能体。

转换期间的代理类型

在过渡期间，可能会遇到三种类型的代理：

类型	agent.identity	描述
新代理	非 null 值	在对象模型更新后创建。 具有唯一的标识和蓝图。 所有新功能都可用。
旧智能体	空值	在对象模型更新之前创建。 使用共享项目标识和蓝图。 使用新的智能体属性（例如 protocol_configuration、agent_endpoint 和 agent_card）回填，但除非具有唯一的智能体标识，否则无法通过其稳定终结点发布到 Teams/M365。
已发布的代理（即代理应用程序）	N/A （单独的资源）	旧发布流程中的遗留资源。 包装了一个指向智能体版本的部署。

该值 agent.identity 将新代理与旧代理区分开来： null 表示旧代理，非 null 表示新代理。

继续有效的内容

• 现有代理应用程序 继续通过其终结点为流量提供服务。
• 通过代理应用程序发布到 M365/Teams 的代理将继续工作。
• 项目终结点 仍可用于向后兼容性（尽管它不再是建议的路径）。
• 旧智能体在 Foundry 项目中保持完全正常运行，用于开发和测试。

迁移路径

路径 1：新代理（无需执行任何操作）

如果在对象模型更新后创建代理，它们会自动获取具有唯一标识、稳定终结点和所有新功能的新模型。 无需迁移。

路径 2：升级旧代理

旧代理（在更新之前创建）使用共享项目标识，无法通过新模型发布。 升级：

1. 检查智能体是否为旧智能体：

   GET {endpoint}/agents/{agent_name}?api-version=2025-11-15-preview
   Authorization: Bearer {{token}}
   Foundry-Features: AgentEndpoints=V1Preview
   

   如果 instance_identity 响应中为 null，则为旧代理。

2. 使用相同的定义创建新代理：

   注意

   目前无法将旧版智能体升级到唯一标识。 若要获取唯一标识，请使用相同的定义创建新的代理（说明、工具、模型配置）。 新代理会自动接收唯一标识和稳定终结点。 计划在未来的更新中提供就地升级路径。

3. 创建新代理后，它具有唯一的标识，可以使用所有新功能，包括使用代理终结点的新发布体验。

路径 3：迁移现有代理应用程序

如果代理应用程序已发布到 M365/Teams 并想要迁移到新模型，请执行以下步骤：

1. 使用与代理应用程序后面的代理相同的定义创建新代理（说明、工具、模型配置）。 新代理会自动接收唯一标识和稳定终结点。 有关详细信息，请参阅 路径 2 。

2. 从 Foundry 门户将新代理发布到 Microsoft 365 和 Teams。 仅可通过 Foundry 门户进行发布 - 没有公共发布 API。 有关步骤，请参阅 将代理发布到 智能 Microsoft 365 Copilot 副驾驶® 和 Microsoft Teams。

3. 使用新的稳定终结点，在 M365/Teams 中验证新代理是否正常工作。

4. 确认新代理正常工作后停用旧代理应用程序：

   • 删除代理应用程序 Azure 资源。 删除资源不会删除代理版本。
   • 若要使现有集成正常工作，请更新引用旧应用程序终结点 URL 的任何代码，以使用新的代理稳定终结点 URL。

端点 URL 更改

迁移时，更新引用旧终结点格式的任何代码或集成：

方面	旧版终结点	新建终结点
反应	https://{account}.../projects/{project}/applications/{app}/protocols/openai	https://{account}.../projects/{project}/agents/{agent}/endpoint/protocols/openai/responses
活动	https://{account}.../projects/{project}/applications/{app}/protocols/activityprotocol	https://{account}.../projects/{project}/agents/{agent}/endpoint/protocols/activityprotocol

在过渡期间发布用户体验

在转换期间，可能会看到不同的发布体验，具体取决于代理类型：

• 新智能体 (agent.identity != null)：可以看到新的发布用户体验，其中包含稳定的终结点选择、版本路由和直接发布到 M365/Teams。
• 旧版智能体 (agent.identity == null)：你将看到旧版智能体应用程序发布用户体验。 横幅可能表明新体验已上线，并提供升级的链接。

时间线和弃用

阶段	地位
可用的新代理对象模型	✅ 可用
旧代理应用程序继续工作	✅ 支持
旧智能体标识升级手势	🔄 即将推出
智能体应用程序已宣布弃用	📅 已在规划中。
代理应用程序终止支持	📅 待定

常见问题 解答

是否需要立即迁移？

不。 现有代理应用程序将继续工作。 但是，诸如多个协议、禁用/启用和 A2A 等功能仅在新的代理模型中可用。

代理应用程序是否会停止工作？

不立即。 智能体应用程序会提前通知并给出迁移期后弃用。 在终止支持日期之前，它们将继续正常运行。

是否可以为同一基础代理同时拥有代理应用程序和新模型代理？

在过渡期间，是的。 代理应用程序和新的代理终结点可以共存。 但是，它们是具有单独标识和终结点的单独资源。

我之前在智能体应用程序资源上分配的 Azure 基于角色的访问控制 (RBAC) 角色会发生什么？

针对“代理应用程序”资源的代理标识的角色分配不会转移到代理对象。 你需要将任何必需的角色分配给新代理端点的代理标识。 与你一样，请考虑最小特权原则，并删除任何不必要的权限。

请记得同时更新分配给客户端的所有角色，这些角色允许客户端与您的代理进行交互。 在旧模型中，这些分配的范围可能限定为代理应用程序资源。 在新模型中，在项目范围内分配相应的角色。

我的代理使用通过代理标识进行身份验证的工具。 哪些更改？

在新模型下，代理从创建阶段起就具有唯一的标识，因此在发布阶段不会有标识更改。 但是，如果从旧代理迁移，代理将获取与共享项目标识和任何代理应用程序标识不同的新标识。 需要为下游资源重新分配 RBAC。

相关内容

• Microsoft Foundry 中的代理应用程序
• 将代理发布到 智能 Microsoft 365 Copilot 副驾驶® 和 Teams
• Foundry 中的代理标识概念