别再把 Agent 当成一段 Prompt：Microsoft Agent Framework 如何把多代理工作流推进生产环境

如果你最近在做 AI 应用，很容易把 Agent 理解成一个更会呼叫工具的 chatbot：收进一段 prompt，交给模型决定下一步，再把结果印出来。这个模型在 demo 阶段很顺，但一旦任务需要多步骤执行、跨服务协作、人工核准、失败后恢复，问题就会从「模型答得好不好」变成「整个系统能不能被控制」。

这也是我这次挑 Microsoft Agent Framework 的原因。它不是只提供另一个聊天封装，而是试图把 Agent 与 workflow 放进同一个工程边界：Agent 负责理解与行动，workflow 负责明确的执行路径，状态与 checkpoint 负责中断后恢复，middleware 和 OpenTelemetry 负责治理与观测。官方定位是用 Python 与 .NET 建构 production-grade AI agents 和 multi-agent workflows，另外也提供 Go SDK 的公开预览版本。[1][2]

先讲结论：我认为 Microsoft Agent Framework 适合已经跨过「做一个会聊天的原型」阶段，开始在意可重跑、可观测、可审核的团队。它不适合拿来替每个简单的问答 API 增加一层抽象，也不适合在还没有清楚任务边界时，先建立一个十几个代理互相转交工作的系统。

我为什么现在注意它

截至 2026 年 8 月 28 日，microsoft/agent-framework 在 GitHub 约有 1.3 万颗 stars，且 repository 在最近 180 天内持续更新。[3] 星数本身不是技术品质证明，但它至少代表这个专案已经有足够的公开讨论与实作材料可以检验。更重要的是，官方 repository 并不是只有一个 SDK 目录，而是把 Python、.NET、Go、宣告式 Agent、workflow samples、hosting samples 和文件集中在同一个工程入口。[3]

我觉得它值得看的核心，不是「能不能叫模型」，而是它把以下几个问题明确化：

1. 一个 Agent 和一个 workflow 到底谁负责决策。

1. 多个 Agent 的协作路径是否能被程式码重播与测试。

1. 工具呼叫、人工介入和外部服务失败时，系统如何停下来而不是继续猜。

1. 一次执行的上下文、状态和观测资料要放在哪里。

1. 原型要如何逐步接到本机、云端或托管环境。

先分清楚四个层次：Agent、workflow、工具与部署

很多 multi-agent 文章会把所有东西都叫成「代理协作」，结果读者只记得可以同时启动很多模型，却不知道每个模型的责任边界。我的建议是先用四层来看 Microsoft Agent Framework。

Agent：处理需要语意判断的单位

Agent 通常有模型 client、名称、指令和工具。它适合做需要语意理解的工作，例如把使用者要求转成查询条件、判读文件、提出下一步，或根据工具结果组织回复。Agent 的强项是弹性，代价是决策路径不一定稳定，所以不应该让它单独决定所有不可逆的副作用。

工具与 MCP：把能力接到系统边界

工具是 Agent 可以呼叫的外部能力，MCP 则提供一种连接工具与 MCP server 的方式。这里最重要的不是「工具越多越好」，而是权限、输入验证、逾时、重试和输出格式都要被当成产品设计的一部分。官方文件也提醒，只能连接信任的 MCP server，因为它们可能在本机执行命令或暴露敏感资料。[3]

Workflow：把协调逻辑移到可重跑的程式码

Workflow 的角色是把执行路径写清楚。官方文件列出的能力包含 sequential、concurrent、handoff、group collaboration，以及 checkpoint、streaming、human-in-the-loop 和 time-travel 等模式。[4] 这些名词不应被当成勋章，而应该回到一个实际问题：这次任务失败后，我能不能知道卡在哪个节点，修正输入后再从合理位置继续？

Hosting：把「能跑」变成「有人能用」

当 Agent 或 workflow 要被其他应用程式呼叫，就会碰到 Responses client、Telegram、A2A、MCP client 或其他通道。官方部落格近期也把 channels、agent harness 和 production readiness 当成主题，这说明问题已经从单纯的 prompt 组合，移到介面、权限、状态与营运。[5]

第一个可验证入口：先跑一个单一 Agent

不要一开始就建立多代理团队。先让一个最小 Agent 在你的环境中成功回应，确认认证、模型部署、套件版本与网路都没有问题，再把工具和 workflow 加进来。以下范例取自官方 repository 的 Python quickstart，使用 Microsoft Foundry 与 Azure CLI credential。[3]

import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
async def main():
    agent = Agent(
        client=FoundryChatClient(
            credential=AzureCliCredential(),
        ),
        name="HaikuAgent",
        instructions="You are an upbeat assistant that writes beautifully.",
    )
    print(await agent.run("Write a haiku about Microsoft Agent Framework."))
if __name__ == "__main__":
    asyncio.run(main())

上手前的前置条件

官方 README 的安装入口是：

pip install agent-framework
az login

在正式专案里，我会改用专案隔离的环境管理方式，例如 uv add agent-framework azure-identity，避免把依赖直接洒在全域 Python。接着确认 Foundry project endpoint、模型部署名称和 Azure 身分都已经准备好；如果你的团队不是使用 Foundry，应该依官方 provider samples 改用相容的 model client，而不是把 Foundry credential 硬塞进所有环境。

第一个验证任务不要用复杂 prompt。只要能稳定印出一段回应，就代表四件事已经通了：Python 套件可载入、Azure credential 可取得、模型部署可连线、Agent 的基本执行回圈正常。若失败，先分辨是套件安装、az login、endpoint、deployment name 或模型权限问题，不要立刻把错误归因给 workflow。

下一步可以沿着 repository 的 python/samples/01-get-started、python/samples/02-agents 和 python/samples/03-workflows 前进；这比直接复制一段网路上的 multi-agent prompt 更容易保持 API 与版本一致。[3]

从单一 Agent 走到 workflow 的实作顺序

我会按照下面五步扩充，而不是同时引入所有能力。

第一步：把任务输出变成结构化资料

先定义 Agent 要交付什么，不要只要求「请完成任务」。例如客服分类可以输出意图、优先级、需要查询的资料与是否需要人工接手。结构化输出让下一个节点不必从自然语言猜测上一个节点的意思，也让测试可以比较栏位而不是比较整段文字。

第二步：只加入一个真实工具

选一个能证明价值的工具，例如查询订单或读取内部文件。为工具加上明确 schema、权限和逾时；先记录模型提出的参数，再执行副作用。若工具会修改资料、寄信或交易，先插入人工核准，不要因为模型在测试中表现稳定就跳过这一层。

第三步：把固定顺序写成 workflow

如果任务永远是「分类 → 查资料 → 产生草稿 → 审核」，就不要把这个顺序藏在一个超长 system prompt 里。用 workflow 的节点和边表达它，让每个节点都能独立测试，让执行纪录能回答「哪一步花了多久」与「哪一步失败」。

第四步：只在必要时加入平行与 handoff

平行适合互相独立的查询，例如同时查产品资料与政策文件；handoff 适合责任真的从一个专业角色转给另一个角色。若两个 Agent 只是交换同一份上下文，平行化未必会提高品质，反而会增加 token、整合和除错成本。

第五步：补上 checkpoint、人工介入与 observability

当任务可能超过一次请求的生命周期，就要保存状态。checkpoint 不是单纯把 prompt 写进资料库，而是要能辨认目前执行到哪个节点、哪些输入已经消费、哪些副作用已经完成。人工介入也要有明确的 pause 和 resume 边界。官方 workflow 文件将 checkpoint、恢复执行、human-in-the-loop、OpenTelemetry 和 topology visualization 都列为工作流能力的一部分。[4]

什么时候该用子代理、skills、代理团队或 workflow

这四个概念很容易混在一起，我会用「是否需要独立生命周期」来分辨。

子代理：主 Agent 临时委派一个窄任务，结果回来后通常不需要独立营运。
Skills：可重用的领域知识或操作能力，重点是如何被发现与套用，不等于另一个具有完整责任的 Agent。
代理团队：多个 Agent 各自扮演角色，适合需要不同专长或明确交接的任务。
Workflow：把节点、执行顺序、事件、状态和恢复规则固定下来，适合要测试、审计和重跑的流程。

如果只是让模型查一份资料，我会用单一 Agent 加一个工具。如果需要研究与审稿两种角色，我才会考虑代理团队。如果流程还要支援重试、核准、恢复和观测，最后一定要把协调逻辑提升成 workflow。不要因为「multi-agent」听起来比较先进，就把所有问题都拆成代理。

我会特别留意的限制

1. 官方定位很广，但云端依赖仍然真实存在

README 同时涵盖 Python、.NET、Go、Foundry、Azure OpenAI、OpenAI、GitHub Copilot SDK 与 hosting patterns，选择很多，但这不代表每条路径都具有相同成熟度。Go SDK 目前是 public preview，官方 overview 也明确说明部分能力尚未提供。[2][3] 评估时要针对你要用的语言、provider 和部署方式做小型 proof of concept。

2. Agent 的弹性不能取代系统边界

Agent 可以自己决定下一个工具，但不应自己决定所有权限。生产环境至少要把工具白名单、参数验证、敏感资料遮罩、逾时、重试上限和人工核准分开设计。尤其是 MCP，便利性越高，越需要清楚知道 server 会做什么。

3. 可观测性不是最后才加的 dashboard

如果没有记录 workflow run、节点输入输出摘要、模型呼叫延迟、工具错误和 token 成本，你很难分辨是 prompt、模型、工具还是协调逻辑造成失败。OpenTelemetry 应该在第一个可重跑的流程就接入，至少先让每次执行有 correlation id 和节点级别的时间线。

4. 多代理的成本可能比收益更快上升

每增加一个 Agent，就增加上下文传递、模型呼叫、失败组合和结果整合。并行也不等于免费：它可能缩短墙上时间，却提高同时请求量和 provider 成本。先量测单一 Agent 的基线，再以任务品质、延迟、可恢复性和总成本判断要不要拆分。

5. 从 AutoGen 迁移不是改几个 import 就完成

Microsoft 提供 AutoGen 到 Agent Framework 的官方 migration guide，内容涵盖 model client、AgentSession、tool、MCP、Agent-as-a-Tool、middleware、multi-agent workflow、human-in-the-loop、checkpoint 和 observability。[6] 这代表迁移真正需要重新检查的是执行模型与责任边界，不只是把类别名称换掉。

如果你已有 AutoGen 应用，我会先挑一条最小但完整的流程迁移：一个 Agent、一个工具、一次人工核准和一个可恢复的失败案例。等行为、日志和成本都对得上，再处理更复杂的 group chat 或多代理编排。

适合哪些团队先试

我会把第一批试用者分成三类。

第一类是已经有明确流程的产品团队，例如客服分流、研究报告、内部营运或文件审核。这些流程通常有节点、权限和人工作业，最能验证 workflow、checkpoint 和 human-in-the-loop 的价值。

第二类是需要同时支援 Python 与 .NET 的企业团队。Microsoft Agent Framework 的跨语言定位，可以让团队在相近的概念下分别整合既有服务；但仍应以实际 SDK 功能和 provider 支援矩阵做验证，不要把「跨语言」当成 API 完全相同。

第三类是已经遇到 Agent 原型治理问题的开发团队：工具越加越多、错误难以重现、长任务常常中断，或产品开始要求审核与稽核。这时候框架的价值不是让 demo 更快，而是让系统的失败方式更可预期。

反过来说，如果你的需求只是一个 FAQ endpoint、一个固定的 RAG 查询，或一个没有外部副作用的文字生成器，我会先使用更小的 SDK 组合。框架越完整，学习与维运成本也越高；不要为了贴上 Agent 标签而引入 workflow。

我的导入检查表

在真正接资料与权限之前，我会要求团队回答以下问题：

任务的成功条件能不能写成可测试的栏位或事件？
哪些步骤必须固定，哪些步骤才值得交给模型决策？
哪些工具是 read-only，哪些工具会造成不可逆副作用？
Agent 失败、工具逾时或人工拒绝时，流程要停在哪里？
重新执行会不会重复寄信、扣款、写入或发布？
每一次 run 是否都有状态、trace、成本和版本资讯？
目前真的需要多代理，还是单一 Agent 加 workflow 已经足够？

这份清单看起来不像 AI demo，但它才是把 demo 变成产品时最常缺的部分。

结语：先把路径写清楚，再让模型保持弹性

我对 Microsoft Agent Framework 的判断是：它最有价值的地方，不是替你自动生成一个很会聊天的 Agent，而是提供一条从 Agent、工具到 workflow 和 hosting 的连续工程路径。你可以先用几行 Python 验证模型呼叫，再逐步加入结构化输出、工具、人工核准、checkpoint、observability 和部署通道。

这条路径也提醒我们，multi-agent 不是产品目标，可靠的任务完成才是。能用固定程式码表达的协调逻辑，就不要藏进 prompt；需要模型判断的地方才保留弹性；会造成副作用的地方，一定要有权限与人工边界。

如果你正在评估它，我建议的第一个实验很小：选一个有清楚输入与输出的任务，建立单一 Agent，接一个 read-only 工具，记录完整 trace，再故意注入一次工具失败。只有当团队能回答「失败发生在哪里、如何恢复、成本是多少」，才值得把它扩成多代理 workflow。

参考资料