你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用开源框架生成代理应用程序时，通常会管理许多交叉问题：容器化、Web 服务器设置、安全性、内存持久性、缩放、检测和版本回滚。 在异类云环境中，这些任务变得更加具有挑战性。
Foundry 代理服务中的托管代理为 Microsoft Foundry 用户解决了这些难题。 托管代理从 Foundry 模型目录调用模型，以在自定义代码处理业务流程时执行推理。 使用此托管平台，可以安全地大规模部署和操作 AI 代理。 可以通过简化的部署和管理使用自定义代理代码或首选代理框架。
何时使用托管代理
当您需要执行以下操作时，请选择托管代理而非基于提示的代理：
- 创建自己的代码 - 使用任何框架（Agent Framework、LangGraph、语义内核 或自定义代码），而不是仅提示定义。
- 使用自定义协议 - 通过 Invocations 协议接受 Webhook 或非 OpenAI 的有效负载。
- 控制计算资源 - 为代理的沙盒指定 CPU 和内存。
- 运行有状态工作负荷 - 通过$HOME和 /files 终结点跨轮次保留文件和状态。
工作原理
将代理打包为容器映像，并将其推送到Azure 容器注册表。 部署时，智能体服务会拉取映像、预配计算资源、分配专用的 Microsoft Entra ID（智能体标识），并公开专用终结点。 在运行时，代理代码处理来自客户端的请求，并可以使用其代理标识调用 Foundry 模型、工具箱工具和下游Azure服务。 平台处理缩放、会话状态持久性、可观测性和生命周期管理。
重要
将托管代理与其他Microsoft产品和服务配合使用时，必须阅读此类产品和服务的所有相关文档，并了解相关的风险和合规性注意事项。 如果将托管代理与未Azure直接模型（“第三方系统”）的任何第三方服务器、代理、代码或模型一起使用，则需自行承担风险。 第三方系统是Microsoft产品条款下的非Microsoft产品，受其自己的第三方许可条款的约束。 您负责任何使用及相关费用。 查看与第三方系统共享和接收的所有数据。 请注意处理、共享、保留和数据位置的第三方做法。 你需自行负责管理数据是否流出组织的 Azure 合规性和地理边界，以及任何相关影响。 微软对你或他人使用第三方系统不承担责任，并且你负责实施自己的负责任的 AI 缓解措施，例如元提示、内容筛选器或其他安全系统。
关键概念
托管代理
托管代理是在代理服务上运行的容器化代理 AI 应用程序。 与基于提示词的代理（它们完全通过 Foundry 门户中的提示词和工具配置来定义）不同，托管代理是由你自己的代码打包成容器映像的。 选择框架、控制运行时行为，并将映像部署到Microsoft托管的基础结构。
平台根据活动自动管理容器生命周期，在创建版本时预配资源，并在达到空闲超时时取消预配。
隔离模型
托管代理在每个会话的 VM 隔离沙盒中运行。 每个会话都会获得一个拥有持久文件系统（$HOME 和 /files）的专用沙盒，从而能够实现缩放至零，同时具备状态恢复能力和可预测的冷启动。 会话彼此隔离，当会话在空闲后恢复时，状态会自动还原。
协议：响应和调用
托管代理容器公开两种协议中的一个或两种协议。 每个协议由处理 HTTP 服务器、运行状况检查和 OpenTelemetry 集成的轻型库提供。 这两种协议在 支持托管代理的区域都可用。
我应使用哪种协议？
| 场景 | 协议 | 为什么 |
|---|---|---|
| 对话聊天机器人或助理 | 反应 | 平台管理会话历史记录、流式处理事件和会话生命周期 - 使用任何与 OpenAI 兼容的 SDK 作为客户端。 |
| 具有 RAG 或工具的多轮问答。 | 反应 | 内置的会话 ID 线程处理和工具结果处理。 |
| 后台/异步处理 | 反应 | background: true，配合平台管理的轮询和取消 — 无需自定义代码。 |
| 发布到 Teams 或 M365 的代理 | 反应 + 活动 | 响应协议为代理逻辑提供支持;平台会自动将响应桥接到用于通道传递的活动协议。 |
| Webhook 接收器（GitHub、Stripe、Jira 等） | 调用 | 外部系统会发送自己的有效负载格式 - 你无法更改它以匹配 /response。 |
| 非聊天处理（分类、提取、批处理） | 调用 | 输入是结构化数据，而不是聊天消息。 输入任意 JSON，输出任意 JSON。 |
| 自定义流媒体协议（AG-UI 等） | 调用 | AG-UI 和其他代理 UI 协议与 OpenAI 不兼容——您需要使用原始 SSE 控制。 |
| 协议桥 (GitHub Copilot，专有系统) | 调用 | 调用方有自己的协议，该协议不映射到 /responses。 |
提示
不确定？ 从 响应开始。 以后始终可以添加调用终结点 ， 托管代理可以同时支持这两种协议。
协议比较
| 反应 | 调用 | |
|---|---|---|
| 最适合 | 大多数代理：平台负责管理聊天历史记录、流式处理生命周期以及后台运行。 | 需要完全 HTTP 控制、自定义有效负载或长时间运行的异步工作流的代理 |
| 有效负载 | OpenAI 兼容的 /responses 协定 | 任意 JSON（通过 /invocations）- 由你定义架构 |
| 客户端 SDK | 任何与 OpenAI 兼容的 SDK（Python、JS、C#）都可以直接使用。 | 自定义客户端，您定义协议 |
| 会话历史记录 | 通过对话 ID 进行平台管理 | 你管理会话（内存、Cosmos DB 等） |
| 流媒体 | 平台管理的 ResponseEventStream 及其生命周期事件 | 原始 SSE——直接对事件进行格式化和写入 |
| 后台/持续运行 | 内置（background: true + 平台管理的轮询） | 手动任务跟踪和自定义轮询终结点 |
其他协议
托管代理还支持 Activity 协议以用于 Teams 和 Microsoft 365 频道集成。 使用 Responses 协议来处理代理逻辑并发布到 Microsoft 365 通道（如 Teams）时，平台会自动将 Responses 桥接到用于通道传输的 Activity 协议，无需其他单独的配置连接。 A2A 协议支持代理到代理委派。 所有四种协议（响应、调用、活动和 A2A）都可以在单个代理中组合。
代理标识和终结点
部署到 Foundry 项目的每个托管代理都获取其自己的 专用Microsoft Entra ID（代理标识）和 专用终结点-这两者都是在部署时自动创建的。 无需手动配置托管标识或路由。
部署后终端节点立即可用，无需发布即可进行编程访问。
- 响应：{project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses
- 调用：{project_endpoint}/agents/{name}/endpoint/protocols/invocations
- A2A（预览版）：{project_endpoint}/agents/{name}/endpoint/protocols/a2a
哪些终结点处于活动状态取决于代理版本定义中声明的协议（在使用 azd 时在 agent.yaml 中设置），或使用 SDK 时通过container_protocol_versions设置）。
涉及两个身份：
| 身份 | Scope | 目的 |
|---|---|---|
| Microsoft Entra ID （代理标识，每个代理） | 在部署时自动创建 | 智能体容器在运行时用于身份验证的标识。 用于模型调用、工具访问和下游Azure服务。 |
| 项目托管身份（项目范围） | Foundry 项目上由系统分配的标识 | 由平台用于基础结构操作（例如，容器注册表上的“容器注册表存储库读取者”角色）。 不是代理的运行时标识。 |
使用 azd 进行部署时，会自动将所需的 RBAC 角色（Azure帐户范围内的 AI 用户）分配给代理的Microsoft Entra ID。 对于外部资源（例如，你自己的Azure 存储），请手动将 RBAC 分配给代理的Microsoft Entra ID。
通过 Microsoft 365 通道（例如 Teams）集成时，托管代理还可以以代表用户身份（OBO）运行。 代理的Microsoft Entra ID可以交换用户令牌，以用户身份调用下游服务，需遵循租户策略。 有关详细信息，请参阅代理应用程序和代理标识概念。
会话和对话
托管代理使用 会话 和 对话 来管理状态。 工作原理取决于协议。
会话
会话 ID 标识具有持久状态的逻辑会话，包括$HOME和通过 /files 终结点上传的文件。 此平台按需预配计算资源，并对其还原持久状态。
- 状态持久性：$HOME和 /files 内容跨轮次和空闲时段持久保存。 当计算资源处于空闲状态并重新启动时，无论是在新的还是现有的基础设施上，会话的状态都会自动恢复。
- 隔离：每个会话与其他会话隔离。
- 自动生命周期：会话在首次使用时创建。 平台会自动预配和释放计算资源。
- 会话生存期：会话最长保留 30 天。 空闲超时为 15 分钟 - 如果该时段内没有任何请求到达，则平台会取消预配计算并保持会话状态。
- 会话管理 API：列出会话、终止会话以及每个会话上传或下载文件。
对话
聊天 ID 是存储在 Foundry 中的聊天历史记录（消息、工具调用和响应）的持久记录。
- 持久性：对话历史记录存储在 Foundry 中，独立于计算状态保留。
- 跨频道访问：用户可以从操场、API、Teams 或其他已发布频道访问同一对话。
每个协议中的会话和对话如何运作
响应协议：会话 ID 是主要概念。 平台自动管理会话历史记录，并将会话 ID 与每个会话相关联。 平台将会话 ID 返回到客户端，该 ID 可用于通过 /files 终结点上传文件，使这些文件可用于聊天的计算。
调用协议：会话 ID 是主要概念。 客户端直接管理会话 ID，以跨交互维护状态。 客户端可以使用会话 ID 通过 /files 终结点上传内容，使其可用于会话。 没有平台管理的聊天历史记录 - 你可在自己的代码中管理状态。
会话计算生命周期
| 状态 | 发生的情况 |
|---|---|
| 积极 | 计算正在运行。 请求被路由到它。 $HOME和 /files 内容可用。 |
| 闲置 | 15 分钟没有请求。 计算资源已取消预配。 会话状态（$HOME，/files）将持久保存。 |
| 恢复 | 再次引用同一会话 ID。 平台预配新的计算和还原持久状态。 |
安全性和数据处理
像生产应用程序代码一样处理托管代理。
重要
如果使用 Foundry 代理服务来托管与第三方模型、服务器或代理交互的代理，则自行承担此风险。 建议查看与第三方模型、服务器或代理共享的所有数据，并了解第三方数据保留和位置的做法。 你需自行负责管理数据是否流出组织的 Azure 合规性和地理边界，以及任何相关影响。
- 不要将机密放入容器映像或环境变量中。 使用托管标识和连接，并将机密存储在托管机密存储中。 有关指南，请参阅 设置密钥保管库连接。
- 请谨慎使用非Microsoft工具和服务器。 如果代理调用由非Microsoft 服务支持的工具，则某些数据可能会流向这些服务。 查看连接的任何非Microsoft服务的数据共享、保留和位置策略。
平台详细信息
版本
每次调用创建版本都会生成 不可变的代理版本，即容器映像、资源分配、环境变量和协议配置的快照。 部署引用特定版本。 若要更新代理，请创建新版本，平台会部署它。 请注意，创建代理版本的请求不会对代理版本参数（如容器映像、环境变量等）进行更改，因此不会创建新版本。 你可以通过加权发布的方式在不同版本之间分配流量，从而支持 canary 部署和蓝绿部署。
环境变量是用于在运行时将配置传递给容器的主要机制（例如，项目终结点、模型部署名称和自定义设置）。 它们按版本设置，创建版本后是不可变的。
可观测性
托管代理提供内置的可观测性。 平台通过环境变量自动将 Application Insights 连接字符串注入代理容器。 默认情况下，使用协议库的代理会发出 OpenTelemetry 跟踪，这些跟踪显示在 “调查>事务搜索 ”或 “性能”下链接的 Application Insights 资源中。
有关配置和分析指南，请参阅 在项目中启用跟踪。
Foundry 中的工具箱
托管代理可以通过您在 Foundry 项目中预配的 Toolbox MCP 端点访问 Foundry 管理的工具（代码解释器、Web 搜索、Azure AI 搜索、OpenAPI、自定义 MCP 连接和 A2A）。 代理代码使用标准 MCP 客户端库连接到此终结点， 平台不会自动注入工具。 有关详细信息，请参阅在 Foundry 中策划基于意图的工具箱。 我们建议客户使用 Foundry 中的工具箱来连接 Hosted agent 中的工具，并支持 OAuth 身份直通、代理身份、基于密钥等多种统一身份验证方式。
语言支持
托管代理支持 Python 和 C#。 可以使用任何代理框架 - 协议库与框架无关。 有关使用 Microsoft Agent Framework、LangGraph 和自定义代码的示例，请参阅 foundry-samples 存储库。
沙盒大小
托管代理沙盒支持从 0.25 vCPU/0.5 GiB 到 2 vCPU/4 GiB 的 CPU 和内存分配。
专用网络
托管智能体支持在网络隔离的 Foundry 资源内部署，并可使用客户提供的 Azure 虚拟网络进行出站流量。 这使网络隔离的 Foundry 部署中的代理能够访问专用资源，例如数据库或内部 API。 有关详细信息，请参阅 配置虚拟网络。
注意
托管智能体映像的 Azure 容器注册表当前必须保持可通过其公共终结点访问。 目前不支持受专用网络保护的 ACR。
限制、定价和可用性（预览版）
托管代理目前以预览版提供。
预览期间的限制
| 限制 | Scope | 默认值 | 可调节的 |
|---|---|---|---|
| 最大活动并发会话数 | 每个区域每个订阅 | 50 | 是的，可以向微软支持提交配额申请。 |
定价
托管运行时的计费基于活动会话期间 CPU 和内存资源的消耗。 有关当前费率，请参阅 Foundry 定价页。
区域可用性
托管代理目前在以下区域中可用：
- 美国东部 2
- 美国中北部
- 瑞典中部
- 加拿大中部
- 东南亚
- 波兰中部
- 南非北部
- 韩国中部
- 印度南部
- 巴西南部
- 美国西部
- 美国西部 3
- 挪威东部
- 日本东部
- 法国中部
- 瑞士北部
- 西班牙中部
- 澳大利亚东部
注意
随着其他区域可用，此列表将更新。
后续步骤
| 任务 | 链接 |
|---|---|
| 生成并部署第一个托管代理 | 快速入门：部署第一个托管代理 |
| 使用 Foundry SDK 进行部署 | 使用 Foundry SDK 部署托管代理 |
| 更新、删除、调用或流日志 | 管理托管代理 |
| 设置跟踪和监视 | 在项目中启用跟踪 |
| 评估代理性能 | 代理评估者 |
| 发布到 Teams、M365 或自定义应用 | 代理应用程序 |
| 浏览代码示例 | Python samples • C# samples |
相关内容
- 代理运行时组件
- 代理开发生命周期
- Microsoft Foundry 中的代理标识概念
- 在 Foundry 工具中发现工具
- Azure 容器注册表 文档