在 Microsoft Foundry 中发布代理 - Microsoft Foundry

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

发布将智能体从 Foundry 项目内的开发资产提升为受管 Azure 资源，外部使用者可以通过稳定终结点调用该资源。可以将其理解为这样一个步骤：将代理从“在我自己的项目中工作”提升到“准备好供他人使用”。

本文介绍如何发布代理、配置其身份验证和权限，以及在推出新代理版本时更新代理应用程序。发布后，请参阅以下文章以使用代理应用程序：

如果专门想要在 Agent 365 中生成代理并将其发布为数字辅助角色，请参阅在 Agent 365 中将代理发布为数字辅助角色。

什么是发布？

在开发过程中，可以在 Foundry 项目中生成和测试代理。该项目为你提供了一个共享工作区，但它并非专为广泛分发而设计，因为具有项目访问权限的每个人都可以与所有代理交互，并共享相同的聊天上下文和权限。发布是将代理移出该共享开发空间并进入生产就绪Azure资源的步骤。

发布代理版本时，Foundry 会创建一个 代理应用程序 资源，该资源使用自己的调用 URL、身份验证策略、唯一 Entra 代理标识和唯一 Entra 代理蓝图包装代理版本。部署还作为应用程序的子资源创建，引用要发布的特定代理版本，并支持启动/停止生命周期管理。

注释

Foundry 代理应用程序未在 Microsoft Entra 代理注册表中注册。

为什么发布？

发布可以提供项目级开发无法提供的功能。

外部共享 - 授予对团队成员或客户的访问权限，而无需授予他们访问 Foundry 项目的权限。
稳定终结点 - 即使推出新的代理版本，应用程序 URL 也保持不变。
不同的代理标识 - 已发布的代理拥有其自身的 Entra 代理标识和 Entra 代理蓝图，这些与项目的共享标识和蓝图是分开的。
独立的基于角色的访问控制 (RBAC) 和授权 — 代理应用程序是拥有其自己 RBAC 范围的独立 Azure 资源。可以直接在代理应用程序资源上分配Azure AI 用户等角色来控制谁可以调用它。
Azure Policy集成 - 作为Azure Resource Manager（ARM）资源，应用程序可以由Azure Policy管理。
与 Microsoft 365 Copilot 和 Teams 集成 — 将代理应用程序分发到 Microsoft 365 Copilot 和 Teams 等频道。

发布时会发生什么变化？

最重要的更改是身份。未发布的代理程序使用项目的共享代理标识。发布后，代理将收到其自己的专用代理标识。使用代理标识身份验证的任何工具都将从项目的共享标识切换到代理应用程序的唯一代理标识。

需要关注的内容

由于标识发生更改， 因此不会自动传输权限。发布智能体时，必须为智能体需要访问的所有资源，将 RBAC 权限重新分配给新的智能体标识。如果跳过此步骤，则发布代理后，在开发过程中工作的工具调用会失败，并出现授权错误。

先决条件

一个至少创建了一个智能体版本的 Foundry 项目
在 Foundry 资源范围中可用于发布智能体的 Azure AI 项目经理角色
在智能体应用程序范围上分配 Azure AI 用户角色，以使用响应 API 协议与已发布的智能体聊天
熟悉Azure基于角色的访问控制（RBAC）的权限配置
熟悉 Foundry 中的代理标识概念
按照准备开发环境中所述安装所需的语言运行时、全局工具和Visual Studio Code扩展

重要

本文中的代码使用当前处于预览状态的包。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版的使用条款。

了解代理应用程序和部署

发布之前，请务必了解项目、代理版本、应用程序和部署之间的关系。

此图说明了 Foundry 项目如何组织智能体版本、应用程序和部署，突出显示了治理和 RBAC 角色。

Foundry 项目是一个工作组织概念，用于对相关资源（如代理、文件和索引）进行分组。代理表示一个可组合单元，由其说明、模型和工具定义。 代理版本捕获一个代理的特定不可变快照。每次对代理进行更改（例如更新提示或添加工具）时，都会创建新的代理版本。每个代理版本在 Foundry 项目下公开，其中具有项目访问权限的开发人员可以创建、运行和测试它。

代理应用程序将一个或多个代理投影为服务，独立可寻址、可管理，并配备了生命周期和内容管理功能。它提供了一个持久接口，用于为使用者建立身份验证、标识和稳定的入口点。部署是应用程序内代理版本的运行实例，可以启动、停止和更新以引用新的代理版本。

路由和版本管理

每个代理应用程序用作特定代理部署的路由表。目前，代理应用程序仅支持一个活动部署，所有应用程序终结点接收到的流量都被100%定向到该部署。将新代理版本发布到现有应用程序时，会将应用程序终结点收到的流量 100% 定向到引用新代理版本的部署。

代理应用程序将流量路由到运行特定代理版本的部署的示意图，其中显示了稳定的入口点和流量流。

调用代理应用程序

代理应用程序资源公开具有多个协议和身份验证选项的稳定终结点。

注释

目前，一次只能为代理应用程序启用一个协议（响应或活动协议）。

协议

响应协议

Foundry 代理默认公开一种围绕“Responses”进行的 OpenAI 兼容协议，用于与代理交互。

对于应用程序，此终结点在以下位置公开：

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/openai

已修改通过应用程序公开的 OpenAI 兼容 API，以确保用户的对话保持私密。此限制是暂时性的，一旦支持最终用户隔离，将被删除。因此，API 比项目终结点提供的 OpenAI API 更有限。具体而言：

仅支持无状态响应 API （POST /responses）。
其他 API（包括/conversations、/files/vector_stores和/containers）不可访问。

此限制意味着客户端必须存储多轮次对话的会话历史记录。

活动协议

Foundry 代理还可以公开 Azure Bot Service 使用的 Activity Protocol。

对于应用程序，此终结点在以下位置公开：

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/activityprotocol

Authentication

可以在应用程序上配置入站最终用户身份验证。可使用以下选项：

Default （RBAC）：调用方必须具有代理应用程序资源的 Azure AI 用户角色（或具有 /applications/invoke/action 权限的自定义角色）。如果要使用响应 API 协议调用代理应用程序，请选择此选项。有关 Foundry RBAC 角色的详细信息，请参阅 Microsoft Foundry 的基于角色的访问控制。
通道（Azure 机器人服务）：当你作为数字工作者发布到 M365/Teams 或 A365 时，通道是所使用的身份验证方式。通过 M365/Teams 发布流在 UI 中自动选择此项。

调用代理应用程序不支持 API 密钥身份验证。使用 Microsoft Entra ID（Azure RBAC）来授权调用方。

发布智能体

铸造门户

本部分介绍如何使用 Foundry 门户界面发布代理。

在代理生成器中，创建或选择要发布的代理版本。
选择 “发布代理 ”以创建代理应用程序和部署。

预期结果：发布完成，代理版本显示已发布状态。

为代理应用程序配置身份验证：
- 默认情况下，身份验证类型设置为 RBAC （Role-Based Access Control）。
- 通过Responses协议调用代理应用程序的用户必须被授予代理应用程序资源上的Azure AI 用户内置Azure RBAC角色（或等效的自定义角色）。
分配工具身份验证的权限：
- 如果代理包含使用代理标识进行身份验证的工具，则新创建的代理标识必须具有适当的权限
- 导航到你的智能体访问的每个 Azure 资源，并为新的智能体标识分配所需的 RBAC 角色：
发布后，可以：
- 与外部使用者共享已发布的终结点，或将其集成到现有应用程序中。
- 在 Teams/M365 Copilot等频道中与应用程序共享和聊天。

REST API

若要发布代理版本，必须创建引用代理版本的应用程序和部署。

重要

代理应用程序是Azure资源。调用管理终结点时，请使用可用于订阅和帐户的最新 API 版本。

在您开始之前

登录并获取Azure Resource Manager访问令牌：

az login
az account get-access-token --resource https://management.azure.com

将 accessToken 值用作 Authorization: Bearer <token> 在以下请求中的标头。

如果只想捕获令牌值（例如，用于脚本），请使用：

az account get-access-token --resource https://management.azure.com --query accessToken -o tsv

收集请求 URL 所需的值。
- subscription_id：使用包含 Foundry 资源的订阅服务。可以在Azure门户中（Subscriptions）或运行 az account show --query id -o tsv 找到它。
- resource_group：包含 Foundry 资源的资源组。可以在 Azure 门户中的 Foundry 资源 Overview 页上找到它。
- account_name：Foundry 资源的名称（Azure资源名称）。
- project_name：Foundry 项目名称。
- application_name 和 deployment_name：选择要创建的代理应用程序和部署的名称。
选择一个 api-version。

1.创建代理应用程序。

有关代理应用程序的完整属性参考和基础设施即代码（Bicep）示例，请参阅 Azure Resource Manager 模板参考中的 Microsoft.CognitiveServices/accounts/projects/applications。

必需字段：将 agentName 字段设置为要发布的代理的名称。

以下示例仅显示最小必填字段。默认情况下，authorizationPolicy 设置为 Default （Azure RBAC），trafficRoutingPolicy将所有流量路由到第一个部署。

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "agents": [{"agentName": "Publishing Agent"}]
  }
}

2.创建代理部署。

若要获得有关代理部署的完整属性参考和基础设施即代码（Bicep）示例，请参阅 Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments 的 Azure Resource Manager 模板参考。

必填字段：

deploymentType：部署模式。使用 Managed 提示和工作流代理。使用 Hosted 托管代理。
agents：要部署的代理名称和版本。
protocols：部署公开的协议。对于响应，将protocol设置为Responses，并将version设置为1.0。

仅限托管的更多必填字段：

minReplicas：设置最小副本数
maxReplicas：设置最大副本数

提示和工作流智能体

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "1"
        }
    ]
  }
}

托管代理

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json
{
  "properties": {
    "displayName": "Test Hosted Deployment",
    "deploymentType": "Hosted",
    "minReplicas": 1,
    "maxReplicas": 1,
    "protocols": [
        {
            "protocol": "Responses",
            "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "ContainerAgent",
            "agentVersion": "1"
        }
    ]
  }
}

3.验证部署是否正在运行

工作流和提示代理的部署通常会自动运行。托管代理部署继承已发布代理版本的状态 - 如果版本已停止，则部署也会停止。

若要检查当前状态，请获取部署资源并检查属性 state：

GET https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}

要启动已停止的部署，请使用以下调用：

POST https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}/start?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

验证发布是否成功

与使用者共享终结点之前，确认你的智能体已成功发布。发布后，请验证：

代理应用程序资源存在。
部署正在运行。
可以调用应用程序终结点。

通过调用端点快速验证

若要运行以下命令，需要 Azure CLI。

获取呼叫用户的访问令牌。

az account get-access-token --resource https://ai.azure.com

调用代理应用程序终结点（响应协议）。

curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

如果收到 403 Forbidden，请确认调用方在代理应用程序资源上具有Azure AI 用户角色。

更新已发布的代理应用程序

如果需要推出新版本的代理，请更新现有应用程序和部署以引用新的代理版本。

铸造门户

在代理生成器中，导航到要发布的特定代理版本。
选择“ 发布更新”。
确认更新。代理应用程序会自动将 100% 流量定向到新的代理版本。

稳定终结点 URL 保持不变，确保下游使用者不会因更新中断。

REST API

如果代理名称保持不变，并且只想推出新的代理版本，请更新部署以引用新的代理版本。

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "description": "This is a managed deployment",
     "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "<updated-agent-version>"
        }
    ]
  }
}

若要推出具有不同名称的代理，必须：

更新代理应用程序以允许新的代理名称。
创建或更新部署以引用新的代理版本。
如果创建新的部署，请更新代理应用程序的流量路由策略，以便 100% 流量转到新部署。

调用代理应用程序

注释

代理应用程序目前一次支持一个协议，但可以更改此协议。在 Foundry UI 中创建代理应用程序时，默认为响应 API 协议。如果以后发布到 Microsoft 365 或 Teams，发布流将配置活动协议。

发布后，你可以通过其终结点使用响应 API 协议或活动协议调用你的智能体。将代理发布到 Microsoft 365 和 Teams 时，将使用活动协议。

若要将代理应用程序与响应 API 协议配合使用，请参阅使用响应 API 协议调用代理应用程序

若要在 Microsoft 365 Copilot 和 Teams 中使用代理应用程序，请参阅将代理发布到 Microsoft 365 Copilot 和 Microsoft Teams。

若要将代理发布为数字辅助角色，请参阅在 Agent 365 中将代理发布为数字辅助角色

安全和隐私注意事项

使用最小特权。向用户授予所需的最低角色（例如，将发布权限与调用权限分开）。
只需共享代理时，请避免共享项目访问权限。在应用程序资源上使用代理应用程序终结点和 RBAC。
不要在源代码、脚本或客户端应用程序中嵌入访问令牌。使用适用于应用的Microsoft Entra身份验证流。
发布时规划标识更改。由代理标识进行身份验证的工具调用在发布后使用应用程序标识，而不是项目标识。
如果需要多轮次体验，请将对话历史记录存储在客户端中。代理应用程序当前限制 API，不存储响应。

局限性

作为智能体应用程序发布的智能体有以下限制：

限度	Description
无 UI 或 CLI 管理	高级管理操作没有专用的 UI/CLI。将 REST API 用于在 Foundry 门户发布流程中无法实现的管理操作。

故障排除

問题	可能的原因	决议
发布代理已禁用	在 Foundry 资源范围内缺少 Azure AI 项目经理角色	请在 Foundry 资源（帐户）范围内，而不仅仅是在项目层面，分配 Azure AI 项目经理角色。
`403 Forbidden` 调用终结点时	调用方缺少对代理应用程序资源的调用权限	将代理应用程序资源上的 Azure AI 用户角色分配给调用方。
`401 Unauthorized` 调用终结点时	访问令牌缺失、过期或资源错误	重新进行身份验证并请求`https://ai.azure.com`的令牌。
发布后工具调用失败	代理应用程序标识没有与项目标识相同的访问权限	针对其必须访问的任何下游 Azure 资源，将所需的 RBAC 角色重新分配给已发布的代理标识。
多轮次对话无法按预期工作	代理应用程序不会为你存储聊天状态	将对话历史记录存储在客户端中，并将上下文作为请求的一部分发送。

清理资源

如果不再需要已发布的终结点，请删除代理应用程序Azure资源（及其部署）。删除应用程序不会删除 Foundry 项目中的代理版本。

参考：代理应用程序和部署属性

构造 REST API 请求或需要了解响应中返回的字段时，请使用下表。

代理应用程序属性

姓名	Description	价值	是否可以在请求正文中指定？
`displayName`	代理应用程序的显示名称	字符串	✅
`baseUrl`	代理应用程序的专用终结点	字符串	❌ （只读）
`agents`	应用程序公开的代理。	对象数组	✅
`agentIdentityBlueprint`	与智能体应用程序关联的智能体标识蓝图。	对象	❌ （只读）
`defaultInstanceIdentity`	与代理应用程序关联的代理标识	对象	❌ （只读）
`authorizationPolicy`	定义用户如何向应用进行身份验证。如果未指定，则默认设置此字段	对象	✅
`trafficRoutingPolicy`	定义智能体将流量发送到什么部署。目前，所有网络流量只能路由到一个部署。	对象	✅
`provisioningState`	获取调用操作时的代理应用程序状态。	字符串	❌ （只读）
`isEnabled`	指定是启用或禁用代理应用程序。	布尔	✅

部署属性

姓名	Description	价值	是否可以在请求正文中指定？
`displayName`	部署的显示名称。	字符串	✅
`deploymentId`	具有给定资源标识符的部署的每个不同生命周期的系统生成唯一标识符。	字符串	❌ （只读）
`state`	部署的状态。	enum (`Starting`, `Running`, `Stopping`, `Failed`, `Deleting`, `Deleted`, `Updating`)	❌ （只读）有显式 API，例如启动/停止来控制状态
`protocols`	部署支持的协议	对象数组	✅
`agents`	附加到特定部署的代理版本。	对象数组	✅
`provisioningState`	获取在操作被调用时的部署状态。	enum (`Succeeded`, `Failed`, `Canceled`, `Creating`, `Updating`, `Deleting`)	❌ （只读）
`deploymentType`	附加到部署的代理的类型	枚举（`Hosted` 或 `Managed`）	✅
`minReplicas`	始终运行的最小副本数。	整数	✅（仅当 deploymentType：`Hosted`）
`maxReplicas`	可以运行的最大副本数。	整数	✅（仅当 deploymentType：`Hosted`）

了解 Foundry 中的代理标识概念
了解托管代理
了解如何将智能体发布到 Microsoft 365 Copilot 和 Microsoft Teams

后续步骤

大规模管理代理

反馈

此页面是否有帮助？

Last updated on 2026-03-16

通过

在 Microsoft Foundry 中发布和共享代理

什么是发布？

为什么发布？

发布时会发生什么变化？

需要关注的内容

先决条件

了解代理应用程序和部署

路由和版本管理

调用代理应用程序

协议

响应协议

活动协议

Authentication

发布智能体

铸造门户

REST API

在您开始之前

1.创建代理应用程序。

2.创建代理部署。

提示和工作流智能体

托管代理

3.验证部署是否正在运行

验证发布是否成功

通过调用端点快速验证

更新已发布的代理应用程序

铸造门户

REST API

调用代理应用程序

安全和隐私注意事项

局限性

故障排除

清理资源

参考：代理应用程序和部署属性

相关内容

后续步骤

反馈

其他资源