几周前，我和几个朋友一起聊天，他们正在使用 Microsoft Agent Framework（简称 MAF） 构建代理程序。MAF 是微软推出的开源、跨平台框架，专用于构建基于大语言模型的智能代理应用，支持 C#、Python 等多种语言，提供工具调用、记忆管理、多代理协作等核心能力。他们的演示效果非常棒，代理程序表现得相当智能，能够准确回答复杂问题、调用外部工具，大家都对成果非常满意。然而，饭局进行到一半时，其中一位朋友突然抛出了一个让全场沉默的问题：

“好了，代理程序已经完成了……现在，我该如何部署它呢？”

餐桌上顿时鸦雀无声，因为在此之前，诚实的答案往往是一长串让人头皮发麻的任务清单：编写 Dockerfile、配置 Web 服务器（比如 Nginx 或 IIS）、实现身份验证机制（通常是 OAuth2 或 JWT）、设置会话存储（Redis 或数据库）、编写扩展规则（Kubernetes HPA 或 Azure Scale Sets）、配置遥测日志（Application Insights 或 ELK），以及处理生命周期管理（滚动更新、健康检查、回滚策略）……基本上，仅仅为了让你的代理程序脱离本地机器，就需要额外开发一个完整的独立项目，工作量甚至比写代理逻辑本身还要大。这还只是起步，后续还要考虑安全加固、性能调优和成本控制，想想就让人望而却步。

好消息是：Foundry Hosted Agents 为控制台应用程序提供了一个托管在 Azure 中的一站式运行环境。 你可以完整保留使用 Agent Framework 编写的代理逻辑——包括所有工具定义、提示词模板和对话策略——然后将其作为容器化应用程序部署到 Microsoft 管理的基础架构中，完全不用自己搭建服务器集群。Foundry 会自动为你的代理生成一个标准化的 HTTP 端点，并全权负责计算资源分配、自动扩缩容、身份认证、会话状态持久化、可观测性监控和版本生命周期管理等繁琐事项。平台按会话分配计算资源，空闲时自动缩容至零，真正做到“用多少付多少”。

所以，与其自己从零构建和运行整个第二套项目（包括前端、网关、数据库等），如今的解决方案只需要 一个 NuGet 包、三行 C# 代码和两条命令 。让我一步步来演示整个过程，让你也能在半小时内完成从本地到云端的跨越。

你将建造什么

我们将基于一个现有的 Agent Framework 控制台应用程序，并执行以下操作：

• 将其注册到 Foundry Responses 协议中——这是 Foundry 平台定义的标准化对话交互协议，兼容 OpenAI 的 Responses API 规范。
• 使用 Azure 开发人员 CLI（azd）在本地运行并调用它，验证功能正确性。
• 配置其所需的 Azure 资源（包括 AI 项目、容器注册表、应用服务等）。
• 将其部署为 Foundry 托管代理，正式发布到云端。
• 在 Foundry 门户中检查对话记录、分布式追踪链路、版本历史以及自动化评估结果。

（示意图：从控制台应用 → 添加托管支持 → 部署到 Foundry 的完整流程）

起点：最小 MAF 代理

这很可能就是你现在所处的环境。一个使用 Microsoft Agent Framework 构建的简单代理，运行在控制台应用程序中，代码通常像下面这样简洁：

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT environment variable");
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5-mini";
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "HelloAgent");
Console.WriteLine(await agent.RunAsync("Hello! Tell me a fun fact about .NET."));

（示例代码：一个简单的 AIAgent 实例，调用模型并输出回复）

就是这样。无需服务器，无需任何网络协议，一切逻辑都运行在你的终端里。你只需执行 dotnet run，代理程序就会响应你的输入，完美实现代理版的 Hello World。（如果你还没开始学习 MAF，可以先参考官方教程《你的第一个 C# 代理程序》，只需 5 分钟就能上手。）

但是，这个代理程序目前只存在于你的终端会话中，其他人无法通过网络与它对话，也无法持久化记忆或扩展并发能力。这就引出了我朋友那个扎心的问题。

那么……我该如何部署它呢？这就需要用到 Foundry Hosted Agents 了。

托管代理（Hosted Agents） 是 Microsoft Foundry Agent Service 中的一个托管层，专门为 AI 代理提供生产级运行环境。该平台负责以下核心能力：

重要提示： 托管代理目前已经 正式可用（Generally Available） ，可以放心用于生产环境。微软承诺 SLA 99.9% 可用性，并提供企业级技术支持。

Responses 还是 Completions？
这里需要注意的是，Foundry 托管代理采用的是较新的 Responses 协议，它比传统的 Completions 协议更丰富，支持多轮对话、工具调用、流式输出和结构化输出等特性。如果你的客户端原本用的是旧版 Completions SDK，建议升级到支持 Responses 的版本（如 OpenAI .NET SDK 2.0+），以获得最佳体验。

现在，让我们开始动手，让控制台代理做好托管准备。

差异：1 个包 + 3 行代码

你的现有代理项目已经引用了 Azure.AI.Projects 包（这是 MAF 与 Azure AI 项目集成的核心库）。要使其支持 Foundry 托管，只需额外添加一个新的 NuGet 包：

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease

关于预发布包：--prerelease 参数表示允许安装预发布版本。目前该包处于稳定预览阶段，功能完整且经过充分测试，可以直接用于托管部署。正式版（非预览）将很快发布，届时可以移除该参数。

添加完成后，在你的 Program.cs 中仅需添加 3 行核心代码，改造后的代码大致如下：

[[PRE_PLACEHOLDER_2]]

（改造后的 Program.cs，含三行新增代码）

每行代码的作用详解：

• AgentHost.CreateBuilder(args) —— 这是 Foundry 提供的应用主机构建器，内部基于 ASP.NET Core 的 WebApplication.CreateBuilder 进行了增强。它已经预置了 Foundry 所需的所有基础组件：健康检查端点（用于 Azure 探测）、OpenTelemetry 遥测采集、会话上下文注入、配置绑定等。你不需要再手动调用 AddControllers 或 AddSwagger。

• AddFoundryResponses(agent) —— 这一步将你原有的 AIAgent 实例（即你的代理逻辑）注册到托管宿主中。AIAgent 对象本身完全不需要修改，你的工具定义、系统提示、模型参数都保持原样。框架会自动将其适配为 Responses 协议的处理程序。

• RegisterProtocol(...) —— 这一行将 Responses 协议绑定到 HTTP 端点，自动生成 /responses 路由，并支持 JSON 请求/响应、流式 SSE（Server-Sent Events）以及多模态输入（文本、图像、音频等）。所有协议序列化、反序列化和错误处理都由框架完成。

现在，请你回头看看你 没有 写的代码：
- 没有配置 Kestrel 服务器端口和证书；
- 没有实现会话存储和检索逻辑；
- 没有编写流式传输的 chunk 分割逻辑；
- 没有管理对话历史的截断和裁剪策略；
- 没有处理并发请求的排队和限流。

AIAgent 还是原来那个 AIAgent，但现在它被包装成一个生产级的 HTTP 服务，可以直接响应外部请求。

先在本地运行。

在正式发布到 Azure 之前，强烈建议先在本地进行完整测试。Azure 开发人员 CLI（azd）提供了一个专门的 AI 代理扩展，可以极大简化本地和云端的切换：

azd ext install azure.ai.agents

安装扩展后，使用以下命令为当前项目搭建部署框架，准备将其作为托管代理发布：

azd ai agent init

该命令会交互式地询问你的 Azure 订阅、资源组、区域等信息，并在项目根目录生成 azure.yaml 和 infra/ 文件夹，包含所有基础设施即代码（IaC）模板。

接下来，设置本地运行所需的环境变量（注意：不同操作系统命令略有不同）：

使用 PowerShell 时：

$env:FOUNDRY_PROJECT_ENDPOINT = "https://.services.ai.azure.com/api/projects/"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME = "gpt-5-mini"

使用 Bash / Zsh 时：

export FOUNDRY_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5-mini"

注意：FOUNDRY_PROJECT_ENDPOINT 需要替换为你 Azure AI 项目的实际端点，可以在 Azure 门户的 AI 项目概览页找到。AZURE_AI_MODEL_DEPLOYMENT_NAME 则对应你已部署的模型名称（例如 gpt-4o、gpt-5-mini 或自定义微调模型）。

设置完成后，就可以启动本地托管实例了：

运行代理主机：

`azd ai agent run`您的代理现已上线`http://localhost:8088`。让我们和它聊聊：

**保持本地端点在本地**

`azd ai agent invoke --local "Hello!"`或者，如果你喜欢卷发：

（运行命令启动本地服务）

默认情况下，服务会监听 http://localhost:8088。你可以用 curl 快速测试：

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello! 请介绍一下你自己"}'

![终端显示 azd ai 代理运行和本地调用响应](https://devblogs.microsoft.com/dotnet/wp-content/uploads/sites/10/2026/08/terminal-azd-agent-run-console.webp)


*本地主机监听 8088 端口，同时 azd ai agent invoke通过 Responses 协议发送请求。*

本地能用？太好了。该发货了。

## 部署：两个命令

这部分我通常要花好几个小时。以下是全部内容：

（返回的 JSON 响应示例）

如果一切正常，你会看到代理返回的完整响应内容，包括消息、工具调用记录和元数据。这表明本地托管模式已生效。

正式部署：两条命令上 Azure

本地测试通过后，部署到 Azure 仅需两条命令：

azd provision
azd deploy

命令详解：

关于 Azure 资源和成本：azd provision 会创建标准定价层的资源，按使用量计费。建议开发测试阶段选择 B1 或 F1 免费层（需在 Bicep 模板中手动调整）。如果不再需要该环境，务必执行 azd down 以删除所有资源，避免产生持续费用。删除前请先确认没有重要数据，因为此操作不可逆。

部署成功后，你的代理会自动获得以下企业级能力（无需任何额外配置）：

• 专用端点：格式为 {project_endpoint}/agents/{name}/endpoint/protocols/openai/responses，可通过任意 HTTP 客户端访问。
• 专用 Microsoft Entra 代理身份：平台为你的代理分配了一个服务主体，该主体已自动授予调用 Azure OpenAI 模型和其他配置工具的必要权限。你无需手动管理密钥或证书。

您的代理，在 Foundry 门户中尽情发挥其最佳功能

部署完成后，打开 Foundry 门户（网址通常是 https://.foundry.azure.ai），你会看到你的代理已经出现在“代理列表”中，并带有“已部署”状态标签。这就是“为什么选择 Foundry”的价值所在——全套生产工具唾手可得。

在 Playground 中与它聊天。
无需编写任何客户端代码，直接在门户的 Playground 界面中输入消息，就能实时与你的已部署代理对话。你可以测试不同场景、调整参数、查看原始 JSON 请求和响应，非常适合验收和演示。

（Foundry playground 界面，允许您测试已部署的代理而无需构建单独的客户端应用程序）

开箱即用的追踪功能。
平台会自动将 Application Insights 连接字符串注入到你的容器环境变量中，协议库默认会发出 OpenTelemetry 标准追踪信息。每个请求、每个模型调用、每次工具执行都会记录详细的耗时、输入输出和错误信息。你可以在门户的“事务搜索”面板中直接查看调用链路瀑布图，快速定位性能瓶颈。全程无需编写任何遥测代码，真正实现“零侵入”可观测性。

（对话追踪图，显示代理响应的请求、模型调用和子操作，每个节点的耗时一目了然）

评估与测试。
Foundry 内置了代理评估器（Evaluator），你可以定义一组测试用例（包含预期答案），系统会自动运行并对比实际输出与期望值的差异，计算准确率、相关性、完整性等指标。这改变了以往“凭感觉优化”的窘境，让代理迭代有数据支撑。

版本和会话管理。
每次执行 azd deploy 都会创建一个不可变的代理版本（以时间戳命名），因此回滚到任意历史版本只需在门户中点击“切换版本”即可，零停机时间。会话则由平台全权管理：空闲 15 分钟后，计算资源将被自动取消配置（缩容至零），但会话状态（包括文件上传、对话历史）会被持久化保存；当用户再次发起请求时，系统会快速恢复会话上下文，做到无缝衔接。

（版本列表页面，每次部署生成一个不可变版本，可一键回滚）

更多内置工具（Toolbox）。
托管代理可以通过一个统一身份认证的 MCP（Model Context Protocol）端点访问 Foundry Toolbox，其中包含：
- 代码解释器：支持 Python 和 R 代码执行，适用于数据分析任务；
- Web 搜索：集成 Bing 搜索，让代理获取实时信息；
- Azure AI 搜索：对接企业私有知识库，实现 RAG（检索增强生成）；
- MCP 协议：连接外部 MCP 兼容工具和数据集；
- A2A 协议：实现代理与代理之间的协作通信。

这些工具都经过身份预配，你的代理无需额外授权即可调用。想想我朋友们原本计划亲手搭建的一切——认证服务、存储引擎、追踪系统、评估管线——现在 Foundry 已经全部为你准备好了。

额外福利：VS Code 体验

如果你和我一样是 Visual Studio Code 的重度用户，那么还有一个更高效的开发循环。Microsoft 官方提供的 Foundry Toolkit 扩展（可在 VS Code 扩展市场免费安装）可以将整个流程简化为命令面板中的三个命令：

1. Foundry Toolkit: Create new Hosted Agent —— 自动生成标准的项目结构，包含 agent.yaml 配置文件（定义代理名称、模型、工具等元数据）和最小化的 Program.cs 模板，省去手动创建文件的麻烦。

2. 按下 F5 键 —— 这会在本地启动代理进程，并自动附加 .NET 调试器，同时打开一个内置的 代理检查器（Agent Inspector） 面板。你可以一边与代理进行交互式聊天，一边在代码中设置断点并逐步调试。这种“聊天即调试”的体验非常直观，大幅缩短了问题定位时间。

3. Foundry Toolkit: Deploy Hosted Agent —— 一键触发 azd provision + azd deploy 流程，并在部署完成后自动在门户中打开新版本的详情页。

特别提示：如果你完全不想碰 Docker，也可以选择 代码 ZIP 部署方式。在 azure.yaml 中设置 deploymentType: zip，然后执行 azd deploy，平台会自动将你的 .NET 源代码打包上传，并在 Azure 端自动完成编译、构建和托管，无需本地安装 Docker Desktop。这对于快速验证或轻量级应用尤为方便。

注意事项与专家建议

为了让你在生产环境中更加稳健地使用 Foundry Hosted Agents，这里整理了一些来自微软工程师和社区专家的实操建议：

未来趋势：Foundry 代理生态展望

随着生成式 AI 的飞速发展，Foundry Hosted Agents 所在的 Agent Service 平台也在持续进化。根据微软 Build 2026 大会的最新发布，以下趋势值得关注：

• 多代理编排（Multi-Agent Orchestration）：未来将支持将多个托管代理组合成工作流，通过声明式配置定义代理之间的调用顺序和数据传递，实现复杂业务自动化。
• 边缘部署支持：除了 Azure 公有云，Foundry 将拓展到 Azure Stack HCI 和边缘设备，满足数据驻留和低延迟场景需求。
• 自适应模型路由：平台将根据请求的复杂度和成本目标，自动在多个模型之间路由（如简单问题走轻量模型，复杂推理走旗舰模型），进一步优化成本。
• 合规审计增强：内置更细粒度的操作日志和访问控制，满足金融、医疗等行业的严格合规要求（如 HIPAA、GDPR）。
• IDE 深度集成：VS Code 和 Visual Studio 2026 将原生嵌入代理调试面板，支持热重载、实时变量查看等功能，进一步提升开发效率。

总结

让我们来做最后的计算。从控制台代理迁移到部署在微软管理的基础架构上的生产环境托管代理，你需要做的全部工作：

• 1 个 NuGet 包：Microsoft.Agents.AI.Foundry.Hosting --prerelease
• 3 行 C# 代码：AgentHost.CreateBuilder，AddFoundryResponses，RegisterProtocol
• 2 条命令：azd provision，azd deploy

而作为回报，你将立即获得以下完整能力矩阵：

• 自动扩缩容的托管计算环境（空闲缩至零）
• 持久化的会话状态存储（无需额外数据库）
• 专用 Microsoft Entra 身份认证（零密钥管理）
• OpenAI 兼容的 /responses 标准端点（兼容任何语言 SDK）
• 全链路分布式追踪（Application Insights 开箱即用）
• 自动化评估和质量看板
• 不可变版本管理与一键回滚

曾经让整个餐桌沉默的问题，如今已经有了轻量、优雅且强大的答案。现在就动手试试吧，将你的 MAF 代理送上云端，享受真正的生产级 Agent 体验。