← 返回首页

Agent Framework Orchestration 实测:六处静默与四个报错

agent-frameworkorchestrationmulti-agent

选择多 Agent 编排框架时,大家盯的通常是「支不支持交接」「能不能并行」。真正让我返工的是另一类问题:代码跑完了,退出码 0、日志不报错,但产物是错的,或者干脆是空的。

我用 Microsoft Agent Framework 1.25.0(编排子包 agent_framework_orchestrations 1.4.2)把四种编排各跑了一遍,全程不接任何大模型。本文不含任何联盟推广链接,所有数字都可以在你自己的机器上用文中的实验台复现。

四种编排不是四个 API,而是「控制权归谁」的四种答案

官方文档把内置编排列为五种:sequential、concurrent、handoff、group chat、magentic。前四种的差别,一句话能说清:

这个划分很重要,因为后面几个坑全部来自「控制权归谁」这个设计选择,不是实现缺陷。官方总览页 https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/ 只给了这一张对照表,没有说清默认行为,而默认行为恰恰是最容易踩的地方。

如果你还没接过 workflow 层,建议先看早前那篇 Agent Framework 1.25.0 工作流接线实测:它讲的是 executor 与 edge 的类型契约,本篇从编排器这一层往上讲,两层不重叠。

实验台:一个不调用模型的 client 就够了

要观察编排行为,不需要真模型。BaseChatClient 只有一个必须覆写的方法,返回固定文本即可。

import asyncio
from agent_framework import BaseChatClient, ChatResponse, Message

class ScriptedClient(BaseChatClient):
    def __init__(self, tag, delay=0.0):
        super().__init__()
        self.tag = tag
        self.delay = delay
        self.calls = 0

    async def _inner_get_response(self, *, messages, stream, options, **kwargs):
        self.calls += 1
        await asyncio.sleep(self.delay)
        return ChatResponse(messages=[Message('assistant', [f'{self.tag}#{self.calls}'])])

def agent(client, name):
    return client.as_agent(name=name, instructions=name)

calls 计数器是关键:它能告诉你「这个参与者到底被调了几次」,而这恰恰是多数失效现场唯一的证据。

复现环境写清楚:Windows 11、CPython 3.13.14、agent-framework==1.25.0、agent-framework-orchestrations==1.4.2。安装方式我用的是隔离目录,避免污染主环境:

pip install --target ./tmp/w46-af agent-framework-orchestrations

然后运行时把该目录放进 PYTHONPATH。注意 --target 不执行 .pth 文件,一旦某个子包靠 .pth 做路径注册,导入期就会失败,而这种失败和「上游包坏了」长得一模一样。

顺序编排:默认只交出最后一个参与者的话

三个参与者,各延迟 0.20 秒,跑三次:

SER 0.646s out=['Z#1']  calls=[1, 1, 1]
SER 0.645s out=['Z#1']  calls=[1, 1, 1]
SER 0.644s out=['Z#1']  calls=[1, 1, 1]

三个都调用了(calls 全 1),但 output 事件里只有 Z#1。也就是说,A 和 B 的回答在编排结果里不存在。

这不是 bug,是 output_from 的默认语义:只有最后一个参与者的响应被当作终态输出,前面的人说了什么只留在内部对话历史里。如果你打算把中间结果拿去做二次加工,就要显式打开中间输出:

from agent_framework_orchestrations import SequentialBuilder

wf = SequentialBuilder(
    participants=[a1, a2, a3],
    intermediate_output_from='all',
).build()

但这里有个反直觉的后果:把 intermediate_output_from 设成 'all' 之后,事件序列变成三个 intermediate、零个 output:

[('intermediate', 'A#1'), ('intermediate', 'B#1'), ('intermediate', 'C#1')]

全部被降级成中间产物,终态输出一个都不剩。这与 handoff 文档里那句「降级是静默且有意的」(the demotion is silent and intentional)是同一套逻辑,只套在顺序编排上更容易踩。判据很简单:事件流里 output 的数量必须等于你预期的终态条数,为 0 就说明写错了。

并发编排:并行是真的,拼接顺序不是完成顺序

同样是三个参与者、各 0.20 秒,跑三次取中位数:

PAR 0.207s / 0.213s / 0.214s
median parallel=0.213s serial=0.645s speedup=3.03x saving=67.0%

并发是真的:墙钟时间等于最慢那个,不是三者之和,加速比 3.03 倍与参与人数 3 个基本吻合。

真正的坑在拼接顺序。我把三个参与者的延迟故意设成 0.30 / 0.05 / 0.01 秒,完成顺序必然是 fast、mid、slow;但 output 事件的文本是:

ORDER slow#1mid#1fast#1 [0, 6, 11] decl-order
declaration-order stable 3/3

输出按参与者声明顺序拼接,与完成先后无关,3 次全中。这个结论对下游的影响很直接:如果你把并发结果按 output 顺序喂给汇总提示词,汇总看到的是一个稳定的、和实际耗时无关的排列;如果下游依赖「谁先返回谁优先」,必须自己带时间戳,不能靠事件顺序。

顺带说一句,这条和 11-08 那篇测到的 fan-in 行为是同一套机制的两种表现:框架在超步(superstep)级别做 barrier,同一批结果统一 flush,所以顺序由声明决定。

交接编排:不写路由等于全员互通

交接编排的第一道坎不在运行时,在 build():

from agent_framework_orchestrations import HandoffBuilder

wf = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .build()
)

这段代码会直接抛:

ValueError: Handoff workflows require all participant agents to have
'require_per_service_call_history_persistence=True'. The following agents are
missing this setting: triage, specialist. Set this flag when constructing each
Agent to ensure local history stays consistent with the service across handoff
tool-call short-circuits.

原因写得很清楚:交接是用「工具调用短路」实现的,本地历史必须与服务侧逐步对齐,所以每个参与者建 Agent 时都要带上这个开关:

triage = triage_client.as_agent(
    name='triage',
    instructions='triage',
    require_per_service_call_history_persistence=True,
)

第二道坎是路由。官方 handoff 页原文是「By default, all agents can handoff to each other」,同一页还有一句更关键的:「Even with custom handoff rules, all agents are still connected in a mesh topology... The handoff rules only govern which agents can take over the conversation next.」

我实测确认了这个默认:完全不写 add_handoff 时,triage 发出的 handoff_to_specialist 依然成功,HandoffSentEvent(source='triage', target='specialist') 正常出现,specialist 被调用 1 次。所以「没配路由」不等于「不能转交」,而是等于「谁都能转给谁」。真正要收敛拓扑,得显式写:

wf = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .add_handoff(triage, [specialist], description='升级到专家')
    .build()
)

而一旦只配了单向(triage 转 specialist,specialist 不回 triage),日志会提示:

No handoff configuration found for agent 'specialist'. This agent will not be
able to hand off to any other agents and your workflow may get stuck.

这条 warning 是唯一提示,它不阻断执行。

群聊编排:max_rounds 数的是发言次数

GroupChatBuilder 要求参与者之外再给一个「谁来挑下一位」的东西,缺了会抛:

ValueError: No orchestrator has been configured. Pass orchestrator_agent,
orchestrator, or selection_func to the constructor.

给它一个恒返回同一个人的选择函数,并把 max_rounds 设为 3:

from agent_framework_orchestrations import GroupChatBuilder

wf = GroupChatBuilder(
    participants=[x, y],
    selection_func=lambda state: 'x',
    max_rounds=3,
).build()

结果是 x 被调用 3 次、y 被调用 0 次,日志同时打出 GroupChatOrchestrator reached max_rounds=3; forcing completion.

结论:max_rounds 数的是发言次数,不是「所有人都说过一轮」。所以「两个 Agent 各说三轮」这种直觉写法(max_rounds=3)在只讨论一个议题时其实是 3 次发言总量;如果选择函数有偏,某个参与者可能永远轮不到,而工作流只打一行 warning 就正常结束。

六个不报错但会错的细节

按危害排序,六个现场:

1. 不写 add_handoff 得到的是全互通,不是「不能转交」。想做收敛拓扑必须显式声明。

2. 纯 BaseChatClient 无法执行交接工具。我第一版实验台就是纯 BaseChatClient:triage 调用 1 次、specialist 0 次、handoff 事件 0 个、output 事件的 data 是空字符串,随后工作流停在 request_info 等用户输入。全程只有一个 logger.warning,没有异常。原因是框架在执行工具前会检查 isinstance(client, FunctionInvocationLayer),不满足就直接跳过。让 client 同时继承 FunctionInvocationLayer 后,同一份脚本里 specialist 立刻被调用 1 次、handoff 事件 1 个。

3. 交接工具名会静默截断到 64 字符。官方 handoff 页明说工具名「limits the result to 64 characters. The resulting name must be unique」。我用两个只在第 80 个字符处不同的 agent id 测试:

   from agent_framework_orchestrations._handoff import get_handoff_tool_name
   long_id = 'specialist-' + 'x' * 80
   get_handoff_tool_name(long_id) == get_handoff_tool_name(long_id + 'A')  # True

两个不同目标映射到同一个工具名,框架不做冲突校验。名字长的 agent id(例如带租户前缀的 id)要自己先缩短。

4. 顺序编排默认只返回最后一个参与者的回答,中间人的回答不进 output。

5. intermediate_output_from='all' 会让终态输出归零,事件里只剩 intermediate。

6. 并发结果的拼接顺序是声明顺序,与完成先后无关;依赖「先到先得」的下游必须自带时间戳。

四个真实报错:现象、原因、修法

下面四条全部是本机现场抛出的原文,不是拼出来的「典型报错」。

报错一:交接工作流构建期要求历史持久化开关

现象:HandoffBuilder(...).build() 抛上面那段 ValueError: Handoff workflows require all participant agents to have 'require_per_service_call_history_persistence=True',报错会逐个列出缺失的参与者名字。

原因:交接靠工具调用短路实现,框架要求本地历史与服务侧逐轮一致。

修法:每个参与者 as_agent(..., require_per_service_call_history_persistence=True)。

报错二:add_handoff 第二参数要 Agent 列表,不是配置对象

现象:

TypeError: 'HandoffConfiguration' object is not iterable

原因:签名就是 add_handoff(self, source, targets, *, description=None),targets 收 Agent 序列;HandoffConfiguration 是内部结构,不是入参。

修法:add_handoff(triage_agent, [specialist_agent], description='...')。

报错三:交接源必须是 Agent 实例

现象:

TypeError: Invalid starting agent reference: HandoffConfiguration

原因:把 HandoffConfiguration 当成源传进去,解析器只认字符串或 Agent 两种类型,找不到就抛这句。

修法:源和目标都给 Agent 实例,路由关系用第二个参数表达。

报错四:群聊编排两类必填项缺失

现象一,参与者为空:

ValueError: Either participants or participant_factories must be provided.

现象二,没有挑选机制:

ValueError: No orchestrator has been configured. Pass orchestrator_agent,
orchestrator, or selection_func to the constructor.

原因:群聊的「下一轮谁说话」必须外部决定,框架不提供默认策略。

修法:需要每次重建参与者的场景(例如带状态的 Agent)用 participant_factories,否则直接给 participants;挑选机制三选一,最省事的是 selection_func。

和 LangGraph 的语义差,只有三条

站内已经写过 LangGraph 的 supervisor 与 swarm 拓扑(supervisor 与 swarm 的 6 个差异),内部机制不重复,只讲换框架后语义层面的三条差:

选型决策树:先问「谁来定下一步」

不用比较特性表,问四个问题就够:

1. 下一步是固定次序吗? 是 → 顺序编排。每一步都确定,日志最容易读。

2. 下一步需要看完全部前序结果才能定吗? 是 → 并发跑完再汇总,但记住拼接顺序是声明顺序,别依赖完成顺序。

3. 下一步该由当前处理人自己判断吗? 是 → 交接。同时接受一个事实:交接是交互式的,Agent 不转交时工作流会把控制权交回给人(或由 autonomous mode 自动续跑,默认上限 50 轮)。

4. 需要多方围绕一个议题反复发言吗? 是 → 群聊。此时 max_rounds 是发言总量上限,选择函数的质量直接决定公平性。

还有一个容易被忽略的前置问题:参与者超过 4 个时,交接模式的全互通默认就很危险。每多一个参与者,可转交组合是平方级增长,而默认拓扑不会提醒你。

FAQ

Q:不接大模型能测出这些行为吗?

能,本文全部结论都来自脚本化 client。编排层的行为由框架代码决定,与模型质量无关;模型只影响「工具调用会不会被发出」,所以要用脚本精确控制它发什么。

Q:为什么我的 output 事件是空字符串?

先看 client 有没有继承 FunctionInvocationLayer。纯 BaseChatClient 下,agent 的响应里只有工具调用没有文本,output 的 data 就是空串,而工作流会停在 request_info 等输入。

Q:max_rounds 到底怎么算?

按发言次数算,不按「轮」算。给两个参与者设 max_rounds=3,最多只有 3 次发言,可能全被同一个人占掉。

Q:交接模式和 LangGraph 的 handoff 是一回事吗?

名字一样,语义不同:Agent Framework 的交接是「Agent 调工具把控制权交出去」,默认全互通;LangGraph 的 handoff 更像状态迁移,落点由你定义的节点决定。

落地清单

上线前对着这张表核一遍,能省掉本文六个坑里的五个:

如果你正在比对不同框架的编排语义,可以把这几条当成一张对拍表:同样的业务流程,四种模式各跑一遍,看谁在默认值上悄悄替你做了决定。那一层,才是换框架时真正会返工的地方。想看同一系列里「子包与版本层」的坑,可以接着读 31 个子包怎么读。

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

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

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

🔗 精选推荐工具

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

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

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