← 返回首页

Agent Framework 1.25.0 工作流接线:6 处不报错的失效与 4 个真实报错

AI Agent工作流编排Microsoft

我开始读 Microsoft Agent Framework 的 workflow 文档时,本以为这是一层很薄的图执行器:executor 是节点,edge 是边,send_message 往下传,yield_output 出结果。真正在本机把它跑起来之后,结论反过来了——这层的麻烦不在报错,而在不报错。同一份代码,改一个类型标注、改一个关键字参数,工作流照样 exit 0,照样返回一个「成功」的结果,只是结果里什么都没有。

需要先说清口径:本文所有数字都来自我实际跑出来的输出,不是从文档推断。环境是本机 Windows 11 + CPython 3.13.14,包版本按 PyPI 记录为 agent-framework 1.25.0(上传时间 2026-11-07 15:42 UTC,写这篇时是最新版),用 pip install --target 装到隔离目录,不动主环境。凡是我没跑到的,文末「本文的边界」里逐条列了。

先说版本:官方文档比包快了半步

这不是文风问题,而是你照抄文档会在第一行就崩。

learn.microsoft.com 的 WorkflowBuilder API 页列出了 13 个方法。我逐个 hasattr 检查 1.25.0 的实例,结果是只有 7 个存在,6 个不存在,缺失率 46.2%:

文档里列出但 1.25.0 没有文档与实际一致的
add_agent / register_agent / register_executoradd_edge / add_chain / build
set_max_iterations / set_start_executor / with_checkpointingadd_fan_in_edges / add_fan_out_edges / add_switch_case_edge_group / add_multi_selection_edge_group

更直接的一刀:文档里每一个示例的第一行都是无参的 WorkflowBuilder(),而 1.25.0 的构造函数签名是 WorkflowBuilder(*, max_iterations=100, name, description, start_executor, checkpoint_storage, output_from, intermediate_output_from, output_executors),其中 start_executor 是必填的 keyword-only 参数。照抄官方例子,第一句就是:

TypeError: WorkflowBuilder.__init__() missing 1 required keyword-only argument: 'start_executor'

能跑的写法只有这一种:

workflow = WorkflowBuilder(start_executor=upper, max_iterations=5).add_edge(upper, lower).build()

至于文档为什么超前,我只陈述实测差异,不去猜它对应哪个分支。发布节奏可以解释「为什么容易踩」:PyPI 上 1.20 是 10-02、1.21 是 10-08、1.22 是 10-15、1.23 是 10-22、1.24 是 10-30、1.25 是 11-07,基本一周一版,而文档站点的更新节奏不受包版本号约束。版本号以 PyPI 为准,方法存不存在以 hasattr 为准,这是我这次学到的第一条。

最小闭环:两个节点,九条事件

先建立一个能跑通的基线,否则后面所有「少了什么」都无从对比。

from typing import Never
from agent_framework import Executor, WorkflowBuilder, WorkflowContext, handler

class Upper(Executor):
    @handler
    async def process(self, text: str, ctx: WorkflowContext[str]) -> None:
        await ctx.send_message(text.upper())

class Reverse(Executor):
    @handler
    async def process(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
        await ctx.yield_output(text[::-1])

up, rv = Upper(id="upper"), Reverse(id="reverse")
wf = WorkflowBuilder(start_executor=up).add_edge(up, rv).build()
result = await wf.run("hello")
print(result.get_outputs())     # ['OLLEH']

WorkflowContext[Send, Yield] 这两个类型参数就是这一层的全部契约:第一个是往下游发的类型,第二个是变成工作流结果的类型。Never 表示「这个方向什么都不发」,不是装饰。

一次运行产出 9 条事件,按执行顺序是两个 superstep:

superstep_started → executor_invoked('hello') → executor_completed(['HELLO']) → superstep_completed
superstep_started → executor_invoked('HELLO') → output('OLLEH') → executor_completed(['OLLEH']) → superstep_completed

两点值得记:yield_output 产生的事件类型是 output,get_outputs() 里的顺序是节点完成顺序;而每条 executor_completed 的 data 始终是 list,哪怕你只发了一条消息。

六处不报错的失效

下面六条,全部 build() 通过、run() 正常返回、get_outputs() 给你一个空列表或者半截结果。我在每一条上都跑了对照,确认不是我的写法问题。

其一,没有输出类型标注,类型校验会被静默跳过。 如果源 executor 的 handler 只写 WorkflowContext 而不写泛型,构建期的类型兼容校验直接跳过,只在日志里留一句 warning:

Executor 'S' has no output type annotations. Type compatibility validation will be skipped for edges from this executor.

跳过之后,类型不匹配的消息会在运行期被吞掉。我让源节点发一个 float,目标节点只声明了 str 和 int 两个 handler,结果目标节点一次都没被调用,get_outputs() 返回 [],全程无异常。

其二,联合类型能让 build() 过,但运行期照样丢。 源节点声明 WorkflowContext[str | int],目标节点 handler 只接受 str。构建期的判据是「源的输出类型集合里有没有任何一个能和目标兼容」——str 在,所以通过。但我实际发出去的是 7,目标节点收到的是 []:

build: OK(联合类型含 str,校验通过)
run: OK  T 收到=[] outputs=[]

这是我认为最危险的一条。静态检查给了你「通过」的信号,而实际的运行期分支完全可能走到联合里的另一支。

其三,fan-in 少一路,整个工作流「成功」返回空。 fan-out 到两个分支、fan-in 汇到一个聚合节点,如果其中一个分支这次不发消息(条件不满足、或者 handler 里 return 了),聚合节点一次都不会被调用,run() 正常返回,outputs=[],没有任何提示:

两路都发         OK  J被调用=1次 batches=[['A(fan:go)', 'B(fan:go)']] out=["batch=..."]
A 不发(只 B 发) OK  J被调用=0次 batches=[]                        out=[]
两路都不发       OK  J被调用=0次 batches=[]                        out=[]

官方文档对这个行为的描述是「target executor will only be executed once all source executors have completed」。它没说后半句:永远不 complete 的那一路会让聚合器永远不执行,而工作流认为这算正常结束。如果你的聚合节点负责写库或发通知,这就是一次静默的数据丢失。

其四,一旦写了 output_from,未列出的节点 yield 就被藏起来。 三个节点串成 A→B→C,每个都 yield_output,七种写法实测如下:

写法get_outputs()get_intermediate_outputs()
两个参数都不传['A-out','B-out','C-out'][]
output_from="all"['A-out','B-out','C-out'][]
output_from=[C]['C-out'][]
output_from=[C] + intermediate="all_other"['C-out']['A-out','B-out']
intermediate_output_from="all_other"[]['A-out','B-out','C-out']
output_from=[] + intermediate="all_other"[]['A-out','B-out','C-out']
output_from=[C] + intermediate=[B]['C-out']['B-out']

七种写法里有 2 种(28.6%)输出恒为空。规则是二值的:两个参数都不传,所有 yield 都是 output;只要写了其中任何一个,就进入显式模式,没被列出的节点 yield 既不进 output 也不进 intermediate,直接消失。想「只把最后那个节点当结果」,正确写法是 output_from=[C],不是只写 intermediate_output_from="all_other"。

其五,edge 条件恒为假,等于这条边不存在。 add_edge(a, b, condition=lambda msg: False) 能构建、能运行、返回 []。条件是普通 Python 函数,返回假值就丢弃消息,没有 fallback 告警。分支路由一定要给 else 分支,或者至少明确约定「没有匹配时输出是什么」。

其六,没接进图的 executor 根本不在图里。 你 new 了一个 executor 但没给它加边,它不会报「孤立节点」,因为它压根没被注册进图——get_executors_list() 里只有从 start_executor 出发能到达的节点。这一点和「图里有孤立节点」不同,后者才会抛 GraphConnectivityError。

四个真实异常(原文可抄)

报错不是没有,只是集中在结构层。以下四条我都在 1.25.0 上复现过,报文原样贴出。

一,TypeCompatibilityError,在 build() 期抛,这是好消息。 源发 int、目标只收 str 时:

[TYPE_COMPATIBILITY] Type incompatibility between executors 'src' -> 'sink'.
Source executor outputs types ["<class 'int'>"] but target executor can only handle types ["<class 'str'>"].

但同一条异常在 fan-in 场景会给出自相矛盾的报文。fan-in 的目标节点 handler 必须声明成 list[T](官方文档原话是「must be compatible with a list of the output types of the source executors」),如果你按普通节点的习惯写成 str,报错长这样:

[TYPE_COMPATIBILITY] Type incompatibility between executors 'A' -> 'J'.
Source executor outputs types ["<class 'str'>"] but target executor can only handle types ["<class 'str'>"].

源是 str、目标也是 str,还说「不兼容」。真实原因是校验器对 fan-in 组用的是「源类型的 list 能否被目标接受」,也就是目标必须能吃 list[str]。看到这条报文先别改数据类型,先看这个目标是不是 fan-in 的汇合点。

二,EdgeDuplicationError。 同一条边加两次:

[EDGE_DUPLICATION] Duplicate edge detected: src->sink. Each edge in the workflow must be unique.

三,GraphConnectivityError。 fan-in 的所有 source 都必须能从起点到达,否则:

[GRAPH_CONNECTIVITY] The following executors are unreachable from the start executor 'A': ['B'].

也就是说 fan-in 不能凭空引入一个新起点,必须先用 fan-out(或普通边)把每个 source 接进来。

四,WorkflowConvergenceException,默认上限 100。 环不设终止条件时,100 次之后抛:

Runner did not converge after 100 iterations.

max_iterations 到底数什么,我做了边界实测(自环,每轮 +1)。结论是没有 off-by-one,上限就是调用次数:

max_iterations实际调用次数结果
11抛异常
22抛异常
33抛异常
55抛异常
5(第 5 次恰好终止)5成功,['stopped@5']
3(第 3 次恰好终止)3成功,['stopped@3']

所以「最多跑 N 步」是可以精确算出来的:把 N 设成你期望的最大节点调用数,正好在第 N 次收尾就不会抛。另外自环在 build() 时只会打印一句提示,不阻断:

Self-loop detected: Executor 'bump' connects to itself. This may cause infinite recursion if not properly handled with conditions.

fan-in 的顺序:两个教程互相矛盾,实测是第三种

这一点必须写清楚,因为我在两篇第三方教程里读到了两个相反的答案:一篇说汇合收到的列表「反映并发完成顺序,可能每次都不同」,另一篇说「按 source-id 顺序」。我实测都不是。

实验设计:三个 worker(id 分别是 Z、A、M),声明为 fan-in 的 [Z, A, M],只把其中一个延迟 30–60 毫秒,看汇合节点收到的列表顺序。

声明顺序=[Z, A, M] 延迟={Z:0, A:0.06} -> J 收到 ['Z', 'A', 'M']
声明顺序=[Z, A, M] 延迟={Z:0.06, A:0} -> J 收到 ['Z', 'A', 'M']
声明顺序=[M, Z, A] 延迟={全 0}        -> J 收到 ['M', 'Z', 'A']

延迟加在中间、加在开头,输出都不动;把声明顺序改成 [M, Z, A],输出立刻跟着变成 [M, Z, A]。连跑 5 次全部稳定,合计 8 次运行 8/8 一致。结论是:顺序由 add_fan_in_edges(sources, target) 的 sources 声明顺序决定,既不是完成顺序,也不是 id 的字典序(那样应该是 A, M, Z)。

原因在模型上:fan-in 是一个 superstep 级别的 barrier,所有 source 在同一个 superstep 跑完,运行时再按声明顺序一次性 flush。两篇教程让你「自己 sort 一下」的建议是对的,但理由不是「并发不确定」——是这个顺序本来就不是你应该依赖的语义。我在正文里给聚合结果排序,纯粹是为了让日志可读。

接线检查清单

把上面这些压成一份可在 code review 时逐条过的清单:

1. 每个 handler 写全 WorkflowContext[Send, Yield],不需要发就用 Never。没有泛型 = 类型校验被跳过 = 运行期消息可能被吞。

2. fan-in 的目标必须声明 list[T],不能声明 T;并且汇合节点不能同时接单条边和 fan-in 组,混用会在构建期报类型不兼容。

3. fan-in 的每个 source 都要有入边,否则 GraphConnectivityError。

4. 输出模式只用一种:要么两个参数全不传(所有 yield 都是结果),要么显式列出全部节点。混着写就会出现「我明明 yield 了但结果里没有」。

5. 有环就显式设 max_iterations,并算出期望的最大调用数(实测与调用次数 1:1)。

6. 条件边要有兜底:条件不满足时消息被丢弃,下游可能永远收不到。

7. 自查三个只读接口:wf.input_types / wf.output_types / wf.get_output_executors()。前两个告诉你起点的入口类型和全图的产出类型集合,第三个列出「谁的 yield 会变成结果」——这一条能在发布前抓出第四类失效。

Troubleshooting:三条抄文档必踩的报错

报错一,TypeError: object NoneType can't be used in 'await' expression。 类式 executor 的 handler 写成同步函数(不加 async)时,@handler 不会拦,build() 也不拦,直到运行期才炸。坑在于函数式 @executor 装饰器是支持同步函数的(文档写明同步函数会被放进线程池执行),所以「同步函数能不能用」这件事在这层有两种答案,取决于你用的是类式还是函数式节点。修法:类式 handler 一律 async def。

报错二,TypeError: WorkflowBuilder expected designation entries to be Executor or SupportsAgentRun instances; got str. output_from 只吃 executor 实例,不吃 id 字符串。你以为可以像某些框架那样写 output_from=["C"],实际要写 output_from=[c]。

报错三,RuntimeError: Start executor 'a' cannot handle input of type 'str'. Expected input types: [<class 'int'>]。 wf.run(...) 的入参类型必须匹配起点 handler 的第一个位置参数。这个报错至少是明确的——比本文那六条失效好得多。

本文的边界

顺带说一句:这一层和 LangGraph 的 superstep 模型很像,两者都按 superstep 推进、都在环上设迭代上限,但类型校验的严格程度相反——LangGraph 基本不管边上的类型,Agent Framework 管得很死,然后在「标注缺失」和「联合类型」两处漏掉。如果你之前读过我在 LangGraph 流式三口径 里做的实测,可以把这篇当成同一套执行模型下的另一个实现对照。

本文不含任何联盟推广链接,也没有推荐任何商品。文中所有代码都在本机跑过,异常报文逐字来自终端输出;如果你的环境复现不了,大概率是版本不同,先核对 agent_framework.__version__。同类的实测还有 gRPC 四个默认值 与 unittest.mock 的七个静默失效,前者讲协议层的默认值,后者讲测试替身层「绿灯但没测到」,和本篇的「接线层不报错」是同一类问题的三个面。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页