Microsoft Build 2027 前，Foundry Hosted Agents 部署如何验收？

本地能跑，云端却显示已部署、请求仍失败？
时间表｜本周先在本地验证协议和就绪探针，再发布；上线后还要确认会话、身份与真实调用链路。Microsoft Foundry 可以托管代码型 Agent，但部署成功不等于应用逻辑已经验收。

准备把本地 Agent 迁入 Microsoft Foundry Hosted Agents 的开发者，可以照着本文建立部署前后的验证流程。
负责容器、身份和发布的平台工程师，可以用检查项复核环境与版本状态。
计划在 Microsoft Build 2027 前梳理 Agent 基础设施的团队，也可以先验证现有应用；本文不预设该活动的日期或届时产品更新。

Microsoft Foundry Hosted Agents 部署验收：发布成功不等于应用可用

托管服务负责其文档列出的运行基础设施与部署流程；你的团队仍要确认代码遵守运行协议，正确处理请求、会话、身份和错误。建议把“部署状态”与“应用验收”分开记录，避免只看版本已发布，就直接放开真实流量。

部署前先判断适不适合托管：Agent 能打包为容器、通过规定协议接收请求，且不依赖无法提供的本机状态或特殊硬件时，可以纳入验证。若程序必须访问本地文件、私有网络资源或未授权的外部服务，先确认访问路径和权限；平台托管不代表这些依赖会自动打通。

Microsoft Learn 的 Hosted Agents 说明介绍了托管方式的适用场景；自有代码部署快速入门列出 Python 和 .NET 代码的接入流程。动手前准备好项目源码、依赖清单、启动配置、模型部署名称、项目端点，以及后续调用所需的身份凭据。不要把文档示例中的资源配置当作 Hashvps 提供的规格。

第一步：对照协议选项，再验证容器契约

先明确客户端和应用实际使用哪种请求协议。Responses 常用于对话式交互；Invocations 可用于非对话处理或自定义工作流。应用选择的协议必须与其处理端点一致，不能只在部署清单里改名。

具体协议和端点应以运行契约文档及你采用的库版本为准。官方适配库可以承担契约适配工作，但这不等于应用逻辑、输入校验和错误处理都已自动验证。

运行契约要求容器监听 8088 端口，并让 GET /readiness 返回 200 OK；同时至少实现 POST /responses 或 POST /invocations。本地逐项测试这些条件，并确认应用能读取平台注入的运行环境变量、在收到 SIGTERM 时妥善结束。容器镜像还须符合 x86_64（linux/amd64） 要求；如果开发机器是 ARM 架构，发布前应明确构建目标。以上均是平台契约要求，不是对 Agent 响应速度或业务正确性的保证。

本地测试别只发一条“正常请求”。至少准备有效输入、缺少必要字段的输入、触发应用错误的输入，以及需要流式返回的请求。逐项核对状态码、响应格式、日志和错误信息是否能帮助定位原因。会话也要单独测试：连续两次调用，确认上下文按设计延续；再换一个会话，确认先前内容不会意外混入。

第二步：本地通过后，再进入打包与发布流程

部署方式可按团队习惯选择：使用命令行或开发工具完成构建与发布，或根据官方指南通过 SDK、REST API 管理部署。不同方式的命令和参数可能随工具及文档更新而变；发布前请对照当前部署指南核对，不要照抄过期示例。

按发布生命周期逐步确认：

1. 构建并推送镜像。检查构建上下文、依赖安装结果和镜像架构，保存本次代码与镜像版本的对应关系。
2. 创建 Agent 版本。核对目标项目、协议配置和模型部署名称，确认发布的是预期代码。
3. 等待状态就绪。不要把“创建请求已提交”当作发布完成；按所选工具查询版本状态，等到文档所列的可用状态。
4. 调用专属端点。用与本地相同的测试输入发起请求，对照本地和云端的响应、错误与会话行为。
5. 保存发布记录。记录版本、配置变更、调用结果和回退方式，确保故障时能定位到一次具体发布。

平台会为托管 Agent 创建专用身份；调用模型等默认能力仍要通过对应项目配置。若应用还要访问你自己的外部资源，需按资源要求另行分配角色。发布者权限与运行中 Agent 的访问权限不是一回事，检查时不要只确认操作者能部署。

第三步：用失败请求和连续会话验收线上行为

上线后至少走一遍三类场景：一条有效请求、一条预期会失败的请求，以及同一会话的连续调用。检查端点是否返回预期结构，错误是否可辨认，会话上下文是否延续；再用不同会话确认数据隔离。测试结果要来自你实际部署的应用，不能以平台支持会话或日志能力替代应用验收。

遇到调用失败，按层定位更省时间：

• 端点无响应：先查版本状态、就绪探针和容器启动日志。
• 协议或响应异常：核对配置声明的协议与代码实际处理的端点，并检查流式处理是否正确。
• 模型或资源访问被拒绝：核对项目端点、模型部署名称和 Agent 身份的角色分配。
• 多轮对话断开：确认客户端有没有按协议传递会话或前序响应标识。
• 部署后频繁重启：检查未处理异常、依赖缺失和系统事件，再判断是否需要调整资源配置。

官方调试指南按症状提供排查方向；使用 Azure Developer CLI 时，可参考托管 Agent 日志指南查看控制台、系统事件和会话日志。若需要追踪应用调用链，可评估Agent 追踪配置说明；能否看到遥测还取决于资源连接和查询权限。

首周观察：先定义团队自己的复核项

“首周”是团队安排观察的时间段，不是平台承诺的服务指标。建议你在试点开始前，先确定记录方式，再比较不同版本，避免把偶发故障和持续性问题混为一谈。可在Hashvps 帮助中心了解相关服务与使用流程；这里列出的观察项仍需由你的团队自行建立。

✅ 发布复核清单：

• [ ] 每次调用是否记录成功或失败，以及失败类别？
• [ ] 重试是否产生重复操作，或掩盖了原始错误？
• [ ] 连续会话是否按协议保留上下文，独立会话是否隔离？
• [ ] 身份或权限变更后，模型和外部资源访问是否仍符合预期？
• [ ] 每次发布的版本、配置、日志和回退方法是否可对应？

如果调用失败类别可定位、连续会话与隔离测试符合预期、权限范围经过复核，可以继续扩大试点；如果仍出现身份拒绝、探针失败、协议不匹配或无法回退，先修复再扩流量。版本管理和端点状态操作应按你所用发布方式的当前官方文档核对。

常见问题

部署前，除了代码和依赖还要核对什么？

确认协议、端点、启动方式、镜像架构、模型部署名称和身份访问范围。若 Agent 需要访问外部存储或服务，要先验证网络路径及对应授权。将检查结果与发布版本一起保存，后续出现连接失败时才能分辨是代码、配置还是权限问题。

就绪探针返回成功，为什么请求还是失败？

探针只验证容器是否按契约报告就绪，不会替你验证业务处理器、模型访问权限、会话逻辑或错误映射。若探针正常而请求失败，继续核对请求协议与代码端点是否一致，再查模型名称、身份授权和运行日志。用同一请求在本地与云端对照，能缩小排查范围。

如何排查部署成功但连续调用没有上下文？

先确认两次请求是否落在同一会话，再检查客户端是否传递协议要求的前序响应或会话标识。不同协议的状态处理方式并不相同；Invocations 协议不会替应用管理对话历史。用独立会话重复测试，排除上下文串用。

发布失败时，先看构建、身份还是调用日志？

按故障出现的阶段查：镜像构建失败，检查依赖、构建上下文和架构；版本未就绪，查发布状态与系统事件；端点可调用但访问模型失败，再核对项目端点、模型名称和身份权限。每次改变一个因素，并重放同一测试请求，避免多个配置同时变化而难以定位。

如果你的目标是运行生产级 Foundry Agent，优先把协议、权限和发布流程验收到位；不要把 Mac 当作托管端点的替代品。反过来，Foundry 环境受指定协议、云端身份和项目配置约束，也不等同于一台可用于 macOS 专项开发或本地工具验证的 Mac。若你确实需要临时远程 Mac 环境，可先按本文核对 Agent，再查看 Hashvps 服务说明，判断它是否适合你的测试任务。