多Agent协作架构：分离数据流与控制流的可复用设计

上周帮一个朋友排查他的多Agent项目，五个Agent负责从抓取、清洗、总结到发布的完整链路，单看每个Agent都挺正常，但一跑起来就出鬼：天气源挂了，负责总结的Agent还在傻等数据；新增一个审核Agent，编辑流程的代码要改一版；最后想把其中一个Agent拆出去给别的项目复用，结果发现它和上下游的调用关系缠成一团，根本拎不出来。

这种场面我见得太多了。很多Agent开发团队一开始都把Agent当成普通函数调来调去，A处理完直接调B的方法，B再调C的方法，数据在一个个调用帧里传递，流程顺序散落在无数个函数体里。前期两三个Agent时确实爽，一个Agent就是一段代码，跑通就行。等Agent数量奔着五个十个去，你会发现最大的成本根本不是模型效果，而是Agent间的协作方式——数据流和控制流全拧在一起，改一处崩一片。

这篇文章就围绕Agent、数据流、控制流这三个核心概念，聊聊怎么把协作架构设计成可复用的，而不是每次加需求就推倒重来。内容主要来自我自己的重构经历，踩过的坑和最终沉淀下来的方案都会写出来，适合正在从单Agent转向多Agent协作、觉得系统越来越难维护的开发者。

1. 先拆清概念：Agent协作里的数据流与控制流到底指什么

1.1 数据流：Agent之间传来的业务内容

数据流，简单说就是Agent之间传递的业务数据。比如一个内容生产系统里，采集Agent把网页HTML传给清洗Agent，清洗Agent把正文文本传给总结Agent，总结Agent把摘要传给发布Agent。这些HTML、正文、摘要、排版参数，就是你系统里的数据流。

数据流的特征是它不带“目的性”，只是描述“现在有什么”。一段文本不会说“我接下来该被谁处理、处理完该给谁”，它只是一个被传递的载荷。你在设计数据流时真正要关心的，是载荷的结构、格式、完整性和可追溯性。

我见过很多项目里数据流是隐性的——A Agent处理的中间结果直接写在A的实例变量里，然后B Agent去A的实例上取值。这种方式在单体应用里很常见，但放到Agent协作里就是灾难：你无法并行、无法重试、无法审计，更无法把某个Agent拆出去独立部署。

1.2 控制流：谁来决定Agent的执行顺序和分支

控制流，是系统里决定“下一步做什么”的逻辑。同样一个内容生产系统，采集成功之后是直接进清洗，还是先做去重；清洗结果太短是不是要回到采集重新抓；总结超时了要不要跳过还是降级成摘要截断——这些都是控制流要回答的问题。

控制流和数据流的本质区别在于：数据流是被搬运的货物，控制流是交通规则和调度计划。货物本身不知道自己该走哪条路，也不知道前面堵车时该换哪条路，这些都是调度系统的事。

很多初学者写Agent编排时经常把控制流“塞进”数据里。比如消息队列里的一条记录同时承载着业务数据和“下一步该做什么”的状态标志，Agent内部再根据这个标志去判断行为。这样的设计短期内能跑，但每次改流程都是改多个Agent内部的逻辑，几乎没法复用。

1.3 为什么聊着聊着变成了“架构”问题

单个Agent内部你不需要区分数据流和控制流，一个函数从头写到尾，顺序执行本来就是默认的控制方式。但多个Agent一旦协作，“谁先做谁后做”和“做完的产出给谁”就变成了两个独立的问题。

从编程模式来看，Agent协作和微服务编排很像：每个服务有自己的输入输出，服务之间通过消息或接口传递数据，编排层去决定调用顺序、处理失败情况。可Agent又有自己的特殊性——Agent本身的执行是不可靠的，LLM的调用可能超时、可能返回格式错乱、可能上下文够长但结果答非所问，这些不确定性意味着Agent协作架构必须预留更多容错、重试和人工介入的空间。

所以Agent协作不是“把函数调用改成Agent调用”那么简单，它需要考虑的是：数据怎么定义、控制怎么表达、流程怎么配置、失败怎么处理。这就是我们说的架构问题，而且是最容易被忽略但决定性最强的那部分架构。

2. 为什么要费劲分离：耦合带来的噩梦和分离后的自由

2.1 不分离的典型症状：越迭代越寸步难行

我先说说不分离的代码通常长什么样。最常见的是直接用代码编排Agent：

python复制# 伪代码：不分离的Agent编排
def main():
    product_data = agent_oa_crawl_product()   # A Agent
    if len(product_data) == 0:
        retry()
    clean_data = agent_clean(product_data)    # B Agent
    if len(clean_data) < 20:
        clean_data = agent_clean_force(product_data)  # 特殊逻辑
    summary = agent_summarize(clean_data)     # C Agent
    agent_publish(summary)                    # D Agent

这个函数在一两个Agent时完全没问题，逻辑直白，跑得也快。但真上了规模，你会发现几个典型的痛：

第一个痛点是改动局部就要理解全局。你想给C Agent加一个输入检查，你得从头读完整个main函数才能确定传入的clean_data到底有没有被B Agent处理过、是否有其他分支绕过了B直接喂给C。

第二个痛点是复用性极差。如果你想把这套流程的B Agent和C Agent单独抽出来供另一个流程使用，你没法干净地抽——它们的上下文里隐含了A Agent的输出格式和D Agent的输入要求。

第三个痛点是异常处理散落。每个Agent都可能失败，于是你不得不在main函数里写一堆if分支，把重试、降级、跳过、终止全部揉在一起。代码越来越长，每次加Agent都像在大型工程施工，谁都不敢动旧逻辑。

这些问题本质上都是因为数据流和控制流没有分开：控制流通过代码的顺序隐含表达，数据流通过函数参数隐式传递，两个维度在源码层面彻底纠缠。

2.2 分离后的收益：架构变成了插拔式的“乐高积木”

如果把两条链路拆开，你得到的是一个更接近“管线”的形态：数据流在消息通道里自然流转，控制流注册成可配置的规则或编排流程。

带来的收益第一条就是替换Single Agent的成本骤降。每个Agent只知道自己处理的输入格式和输出格式，不关心上游是谁、下游是谁。你想把传统规则实现的清洗逻辑替换成LLM清洗，只需要发布一个新Agent并订阅对应的事件类型，老Agent下线即可，整个系统其他部分不需要动。

第二条收益是新流程可以复用旧零件。我之前做了一个情报摘要Agent，一开始只给A流程用。后来另一个项目要做一个竞品监控流程，需要采集、去重、摘要这几个环节，我直接把原来的采集Agent和摘要Agent拿过来重新编了个B流程，一天就搞定。如果没有把数据流和控制流分离，我大概率得从A流程里复制粘贴一大堆代码。

第三条收益是流程可观测、可运维。控制集中到一张编排配置或者一个协调器里，你就有机会做全流程的日志跟踪、超时控制、失败重试。数据在消息里流动，也天然有了审计依据。这些在耦合架构里要花大功夫才能做到的，在上面很容易支持起来。

2.3 一个类比：送货公司里的货物和调度室

我用一个更容易理解的例子总结一下。把Agent系统想象成一家快递公司，数据就是包裹，Agent就是各个分拣站和运输车辆。

不分离的架构是什么状态？每个货车司机都随身带着一张写满了“下一站去哪、遇到爆仓怎么办、如果丢件了去哪补”的表。看起来每个司机都很自主，但换一条运输线路时，你得重新培训所有司机，因为路线信息全在司机脑子里。

分离后的架构则不同——每个司机只负责一件事：把车上的包裹按标准卸到集散点的传送带上，至于这批货是发往哪个城市、哪些货物优先级更高、如果集散点饱和是否绕行，都由一个调度室统一决定，然后司机照着调度指令执行。

这个类比放在Agent系统里，数据流就是一股一股往前涌的包裹，控制流就是调度室里不断变化的排班表和路线图。包裹怎么包装、装什么车，是数据流要管的；哪辆车先走、中途遇到检查是否改道，是控制流说了算。把它们拆开之后，司机可以随时替换，调度规则可以随时调整，两边不会互相拖累。

3. 落地分离的第一板斧：用统一消息结构定义Agent间的数据流

3.1 为什么数据流必须走“消息”而不是走“调用”

要让数据流不依赖具体的调用方和被调用方，最自然的做法是引入消息机制。Agent之间不直接call对方的方法，而是把数据封装成一条消息，投递到一个可以被订阅的通道里。谁需要这条数据，谁去订阅这个通道。

这件事的本质是在两个Agent之间加了一个间接层。间接种的好处是：Agent不再持有对方实例的引用，只依赖“消息通道”这个抽象。这么一来，任何Agent都可以从通道里读到消息，你不需要在代码里硬编码“谁是这条数据的下一环”。

我在实际落地时选择的是最简单的消息总线模型，没有引入重量级的消息中间件。很多时候Agent之间跑在同一进程里，直接走进程内的pub/sub就够了，引入Kafka之类的东西反而增加部署负担。但为了将来扩展，我会把消息总线的接口设计成可替换的，让进程内版本和RPC版本共用一套API。

3.2 消息结构的设计：字段拆解比你想的重要

消息结构是数据流的地基。我强烈建议给消息定义一个统一的外层封装，这个封装里要包含三个部分：头部元信息、业务载荷、追踪信息。业务需求五花八门，但封装的外壳尽量稳定，这个稳定性就是整个架构可扩展的保障。

下面给一个我在项目中使用的Python数据结构示例：

python复制from dataclasses import dataclass, field
from typing import Any, Optional
import uuid

@dataclass
class AgentMessage:
    # 基本定位
    message_id: str = field(default_factory=lambda: uuid.uuid4().hex)
    source_agent: str = ""              # 谁发的
    target_agent: Optional[str] = None  # None代表广播，由所有订阅者自行决定
    event_type: str = ""                # 消息类型，也承载着控制信号

    # 业务数据
    payload: dict = field(default_factory=dict)

    # 追踪信息（这才是运营的守护神）
    trace_id: str = ""
    created_at: float = 0.0

    def reply(self, **kwargs):
        """快速构造一个表示回应的新消息"""
        return AgentMessage(
            source_agent=self.target_agent or "unknown",
            event_type=kwargs.pop("event_type", "response." + self.event_type),
            trace_id=self.trace_id,
            **kwargs
        )

这个结构里有几个我认为很重要的设计决策：

target_agent字段我留了可选项。如果某些业务场景就是明确的一对一投递，可以指定接收者；但默认我倾向于让它为None，用event_type做路由。因为一旦所有场景都指定target，两两之间的耦合会悄悄回流。广播意味着你随时可以插入一个观察者Agent，比如审计Agent，订阅所有消息做监控而不改变任何现有逻辑。

payload类型是dict而不是Object。很多人喜欢定义严格的pydantic模型做类型约束，这在单一系统里绝对是好事，但我建议在Agent之间的边界上用dict，宁可宽松一点，多做运行时校验，也别把消息格式锁得太死——消息格式一变，所有订阅方都得跟着变，那又回到了耦合。

trace_id字段的作用容易被低估。多Agent系统排查问题时最痛苦的就是找不到一条请求完整经过了哪些Agent。有了trace_id，你打的每一条日志都能串起来看全链路。

3.3 数据合约：定义好输入输出，Agent才能成为“零件”

只有统一外壳还不够，你还要对业务数据的核心字段做约定。我用一个很简单的方式管理数据合约：为每个Agent定义标准的输入输出文档，同时用校验函数在入口强制完成格式检查。

每个Agent的实现可以五花八门，但输入输出尽量遵循行业里常见的数据形态。比如要让Agent能大规模复用，尽量别把私人定制的数据形状写死在Agent内部。你在产出Agent之间流转时，能清晰区分“哪部分是Agent要处理的业务内容、哪部分是对Agent行为的命令”，这个架构就成功一大半了。

这里给一个我编写Agent时的天然约束：

python复制def validate_contract(msg: AgentMessage, required_fields: list[str]) -> bool:
    missing = [k for k in required_fields if k not in msg.payload]
    if missing:
        raise ValueError(f"消息缺少必要字段: {missing}")
    return True

把这个校验挂在每个Agent处理业务前，它的存在看着啰嗦，但它能帮你把错误在源头拦截下来，而不是让坏数据一路污染到最后的Agent才发现。

3.4 数据流与控制流在同一个消息里共存，不冲突吗

这里要说一个容易误解的点：AgentMessage里既有业务payload，又有event_type这个控制字段，是不是又变成了不分离？

这两者的区分很简单：payload代表货物内容，event_type相当于包裹上面贴的物流标签。控制流设计关心的是“event_type”应该怎么定义、怎么流转，而数据流关心的是货物本身的内容和形状。两种信息放在同一条消息里不叫耦合，只要它们各自有清晰职责，同封寄送反而省事——你不需要为每个控制信号单独建一套通道。

在实际使用中，我用event_type表达这个Agent做完之后对外发出的信号。比如抓取Agent做完后发出crawl.succeeded事件，payload里是抓到的HTML；如果失败发出crawl.failed，payload里是错误码和重试建议。下游Agent订阅crawl.succeeded，编排器订阅crawl.failed。信号是控制流的信息，HTML是数据流的内容，互不污染，又自然契合。

4. 落地分离的第二板斧：把控制流收拢到编排层

4.1 定义控制信号的词汇表：不要让Agent“自说自话”

分离的核心体现在控制信号词汇表的统一。如果每个Agent自己造一套表示成功和失败的事件名，比如A发done，B发finished，那编排层就得维护一份天文数字般的映射关系。所以第一步就是统一定义一套语义清晰的控制信号。

我一般把事件类型分成四类：

这个表格里的类型不必每个都提前定义全，但当你新加一个Agent时，第一件事应该是思考它产生的信号应该归到哪一类、事件名是否符合现有词汇表，而不是随手写一个别人猜不到名字的事件。

4.2 编排器：流程的控制大脑

有了Agent和消息之后，还需要一个“编排器”去订阅事件、根据事件类型决定调用哪个Agent、往什么通道投递哪个消息。这个编排器是控制流真正的载体。

我推荐用相当轻量的方式落这个角色：不需要上重型工作流引擎，一个集中式的事件处理入口配合一份可配置的流程映射就够了。项目初期可以先用代码写一个简单的规则调度器，将来如果在同一条流程里Agent数量超过10个，再考虑迁移到专门的工作流引擎，比如Prefect、ZenML一类的工具。

下面是我在项目里写的编排器骨架：

python复制class Orchestrator:
    def __init__(self):
        self.bus = MessageBus()
        self.handlers: dict[str, list[Callable]] = defaultdict(list)

    def register(self, event_type: str, handler: Callable):
        self.handlers[event_type].append(handler)

    def dispatch(self, msg: AgentMessage):
        for handler in self.handlers.get(msg.event_type, []):
            try:
                result = handler(msg)
                if result:
                    self.bus.publish(result)
            except Exception as e:
                self.handle_failure(msg, e)

    def handle_failure(self, msg: AgentMessage, err: Exception):
        fallback_msg = msg.reply(
            event_type="flow.error",
            payload={"error": str(err), "original": msg.payload}
        )
        self.bus.publish(fallback_msg)

    def run(self, start_msg: AgentMessage):
        self.bus.publish(start_msg)

这个编排器的核心思想是：它不直接实现“做什么”，只维护一个从事件到处理器的映射表，并在适当时候重新发布新事件。 控制流变成一个注册表，你把“当article.extracted产生时，调用SummaryAgent的提取方法”写进去，这就完成了流程的接线。

4.3 控制流程应该配置化，而不是埋在代码里

当你上面这套机制跑顺之后，会发现一个更大的机会：控制流不一定非要写死在Python里。既然Agent接入方式是标准接口，事件和处理器之间是映射关系，那就完全可以把流程定义成一份配置。比如用JSON或者YAML描述：

yaml复制flow:
  - id: 1
    when_event: "crawl.succeeded"
    action: "clean_agent.process"
  - id: 2
    when_event: "clean.succeeded"
    action: "summary_agent.process"
  - id: 3
    when_event: "clean.failed"
    action: "retry_agent.process"
  - id: 4
    when_event: "summary.succeeded"
    action: "publish_agent.process"

这份配置让非开发角色也能参与流程设计。我接触过一些团队，产品经理在确定了Agent能力清单之后，自己就能画出一条内容生产流程，大大释放了开发同学的精力。

有读者会问，这不就是事件驱动加规则引擎吗？对，本质就是这样。这也是Agent架构最朴素的底层模式：Agent负责专业能力，编排层负责流程，数据流在消息通道中自然流动，控制流注册在可更换的规则里。两者的边界被划清楚之后，系统会获得相当可观的灵活度。

4.4 状态管理应该放在编排层还是Agent内

控制流设计里一个绕不开的问题是状态。比如“A Agent已经处理过这个产品ID了”或者“这轮流程尝试次数已超过3次”，这个状态应该谁持有？

我的经验是，跟流程相关的状态放在编排层，跟Agent自身输入相关的配置放在Agent的初始化参数里。 Agent实例本身尽量无状态化，这样同一个Agent可以被多个流程并发复用。最怕的写法是Agent内部持有一个成员变量去记录“我上一次处理到哪了”，这个变量一旦被多个流程共享，就会出现状态错乱，两个流程的数据互相污染。

在实现层面，编排器可以为每一条流程实例维护一份上下文（Context），里面存流程级状态，比如当前进行到哪个节点、已经重试过几次、积累的中间结果缓存。事件处理函数会拿到这个上下文，决定接下来往哪走。

我用一个简单的字典充当上下文存储：

python复制class FlowContext:
    def __init__(self, trace_id: str):
        self.trace_id = trace_id
        self.data: dict = {}
        self.retry_counts: dict = {}
        self.max_retry = 3

    def can_retry(self, node_name: str) -> bool:
        return self.retry_counts.get(node_name, 0) < self.max_retry

    def bump_retry(self, node_name: str):
        self.retry_counts[node_name] = self.retry_counts.get(node_name, 0) + 1

控制流关注的是“这个任务走到哪了”，Agent关注的是“怎么把这个任务处理好”，两个问题被明明白白分开。

5. 一套可落地的参考实现：三层骨架与完整示例

5.1 三层骨架：消息总线、Agent容器、编排器

把上面讲的几个部件汇总，会得到一套清晰的架构骨架。我为它起名时更喜欢管这套结构叫“数据管道模式”——因为它的形态特别像一个可插拔的流水线。

核心部件一共三个：

消息总线（MessageBus）：提供pub/sub能力，接收AgentMessage，转发给订阅者。它是数据流动的物理载体。进程内版本可以是一个简单的回调列表，分布式版本可以换成Redis Stream或者更重的中间件。

Agent容器（AgentWrapper）：把真实的Agent逻辑包一层，让它对上层只暴露“处理一条消息并返回一条或多条消息”的接口。这个容器负责输入的校验、结果的标准化、日志埋点、异常捕获。

编排器（Orchestrator）：订阅总线里的事件，查找事件对应的处理器，调用Agent，将处理结果重新投递到总线。

三层各司其职：数据靠总线完成流转和解耦，Agent负责纯粹的领域技能，编排器负责带状态的决策。

5.2 最小可运行示例：从抓取到发布的5-Agent流程

为了让你对这套架构有个直观感受，我拿一个最经典的“自动日报生成”场景写一个最小完整流程。这个流水线包含四个Agent：采集Agent、清洗Agent、总结Agent、发布Agent。

先定义一个简单的内存总线：

python复制class MessageBus:
    def __init__(self):
        self.subscribers: dict[str, list] = defaultdict(list)

    def subscribe(self, event_type: str, callback):
        self.subscribers[event_type].append(callback)

    def publish(self, msg: AgentMessage):
        for cb in self.subscribers.get(msg.event_type, []):
            cb(msg)

定义Agent的基类和事件处理器：

python复制class Agent:
    def name(self) -> str:
        pass

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        pass


# 编排器
class AgentOrchestrator:
    def __init__(self):
        self.bus = MessageBus()
        self.contexts = {}
        self.agent_map = {}

    def register_agent(self, agent: Agent):
        self.agent_map[agent.name()] = agent

    def register_route(self, event_type: str, agent_name: str):
        def run(msg: AgentMessage):
            agent = self.agent_map[agent_name]
            return agent.handle(msg)
        self.bus.subscribe(event_type, run)

    def submit(self, initial_msg: AgentMessage):
        self.bus.publish(initial_msg)

再写四个Agent的实际逻辑，这里为了让代码不过长，简单用print模拟AI能力：

python复制class CrawlAgent(Agent):
    def name(self):
        return "crawler"

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        print(f"[crawler] 收到采集请求:{msg.payload}")
        html_content = "<html>某地天气:晴 25°C</html>"
        return [msg.reply(
            event_type="crawl.succeeded",
            payload={"html": html_content, "url": msg.payload.get("url", "unknown")}
        )]


class CleanAgent(Agent):
    def name(self):
        return "cleaner"

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        print(f"[cleaner] 收到原始内容:{msg.payload.get('html')[:30]}...")
        text_content = "某地天气:晴 25°C"
        return [msg.reply(
            event_type="clean.succeeded",
            payload={"text": text_content}
        )]


class SummaryAgent(Agent):
    def name(self):
        return "summarizer"

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        print(f"[summarizer] 开始总结: {msg.payload.get('text')}")
        summary = "今日天气晴好,气温25度"
        return [msg.reply(
            event_type="summary.succeeded",
            payload={"summary": summary}
        )]


class PublishAgent(Agent):
    def name(self):
        return "publisher"

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        print(f"[publisher] 发布日报: {msg.payload.get('summary')}")
        return [msg.reply(event_type="publish.done", payload={})]

注册路由并启动：

python复制orch = AgentOrchestrator()
orch.register_agent(CrawlAgent())
orch.register_agent(CleanAgent())
orch.register_agent(SummaryAgent())
orch.register_agent(PublishAgent())

orch.register_route("daily.task.start", "crawler")
orch.register_route("crawl.succeeded", "cleaner")
orch.register_route("clean.succeeded", "summarizer")
orch.register_route("summary.succeeded", "publisher")

# 发起一个日报任务
orch.submit(AgentMessage(
    source_agent="system",
    event_type="daily.task.start",
    payload={"url": "https://weather.example.com"}
))

跑起来输出是：

code复制[crawler] 收到采集请求:{'url': 'https://weather.example.com'}
[cleaner] 收到原始内容:<html>某地天气:晴 25°C</html>...
[summarizer] 开始总结: 某地天气:晴 25°C
[publisher] 发布日报: 今日天气晴好,气温25度

这个例子看起来很简单，但你要注意它的架构意义：没有任何一个Agent知道下一个Agent是谁，crawler处理完后广播了一个crawl.succeeded事件，cleaner是因为订阅了这个事件才被触发的。将来你想换一个更强的清洗Agent，只需要注册一个新Agent，把crawl.succeeded的路由指到新Agent即可，其他代码完全不用改。

5.3 中间插入一个Agent，到底改哪里

拿上面这个例子继续。产品经理突然提了个需求：日报发布前必须经过审核Agent，如果审核不通过就重新摘要一次。

在没有分离控制的架构里，你得跑到main函数里改调用顺序、处理分支逻辑，说不好还得动PublishAgent对SummaryAgent的调用。但现在不一样，流程全部集中在路由注册上，你只需要：

python复制class ReviewAgent(Agent):
    def name(self):
        return "reviewer"

    def handle(self, msg: AgentMessage) -> list[AgentMessage]:
        print(f"[reviewer] 审核摘要: {msg.payload.get('summary')}")
        # 模拟审核不通过，打回重做
        if not msg.payload.get("passed", False):
            return [msg.reply(
                event_type="review.rejected",
                payload={"summary": msg.payload["summary"], "reason": "语气太口语化"}
            )]
        return [msg.reply(
            event_type="review.passed",
            payload={"summary": msg.payload["summary"]}
        )]


# 新增一个专门用于重新摘要的Agent，也可以复用同一个Summarizer

重新配置路由：

python复制orch.register_route("clean.succeeded", "summarizer")
orch.register_route("summary.succeeded", "reviewer")
orch.register_route("review.passed", "publisher")
orch.register_route("review.rejected", "summarizer")   # 回到摘要节点重做

看到了吗？流程发生了改变，但四个原始Agent里只有SummaryAgent和PublishAgent之间的路由发生了变化，而且不涉及改它们的内部代码。这就是控制流集中收拢的杀伤力。新增节点是接线的活，不是改造的活。

5.4 隔离Agent依赖：从“A知道B”到“订阅一个信号”

这个参考实现里最本质的设计是让所有Agent“只认事件，不认人”。Agent之间不持有相互引用，不直接访问对方的类，唯一交互方式就是投递和接收消息。这件事带来的额外红利是每个Agent的单元测试变得非常简单——你不需要构造一堆上下游的桩，只要发一条消息给Agent，看它返回什么即可。

我在给几个项目做完这种改造后，还有一个明显感受：Agent的关注点变纯了。以前CrawlAgent里会写“如果页面抓不到就跳过CleanAgent，直接喂给SummaryAgent”这种越权逻辑，现在CrawlAgent只需要诚实地汇报状态，具体怎么走是编排器的事。编排器知道所有Agent，但一个都不实现；Agent只在自己上下文里干活，对全局流程一无所知。各司其职，这是整个架构能复用的一个非常关键的心理前提。

6. 实际项目中遇到的五个坑与排查技巧

6.1 Agent把事件发出来了，但没人订阅——订阅关系遗漏

这个坑在我刚切换到事件驱动时遇到得最多。把一个Agent接好之后，它把新的事件类型发出去了，但编排器里忘了注册对应的route，导致消息发出去了却像石沉大海，没有任何日志。而且那会Agent里是静默的，不会报错。

排查方法： 我在消息总线的publish处加了一个“订阅者数量检查”。如果发布事件时没有任何订阅者，记录一条warning日志，从源头提醒你可能忘了接下一环。

python复制def publish(self, msg: AgentMessage):
    subs = self.subscribers.get(msg.event_type, [])
    if not subs:
        logger.warning(f"事件 {msg.event_type} 发出但无订阅者, payload={msg.payload}")
    for cb in subs:
        cb(msg)

6.2 消息回环：A订阅了B的输出，B又订阅了A的输出

事件驱动架构最容易出的逻辑错误就是消息在Agent之间无限循环。比如一个Agent审核失败了打回给重写Agent，重写Agent写完又触发了审核事件，审核又失败……如果没有终止条件，这个循环会一直跑到把token烧光。

这个问题不能只靠测试发现，要在设计时给每个“回环节点”配上计数器。我上面FlowContext里那个bump_retry就是干这个的。在审核Agent里面收到超过两次review.rejected时，不再重写，而是直接把摘要降级为草稿，走一个人工处理的后续流程。

6.3 Agent执行超时导致整条流程卡死

有些Agent底层调用大模型，响应时间随随便便几十秒。如果一个Agent卡住了，上游事件已经处理完，下游事件迟迟不发，流程就悬在那儿。这时候最反直觉的是整个系统不一定报错——没有异常、没有失败事件，就是进度不下去。

我的解决办法是每个Agent处理业务之前注册一个超时哨兵，超过最大执行时间时就由编排器主动发出一个agent.timeout事件。比如你用asyncio.wait_for包住Agent的handle方法，超时了生成一个errback事件，让编排器决定是重试、跳过还是走降级。

6.4 上下文变量在不同事件之间被串用

有一次两个并发任务同时跑同一套流程，我意外发现Task A的文本内容混进了Task B的摘要。查了半天，原因是FlowContext里缓存字段用的是实例级属性，两个事件回调同时访问同一个字典，把对方的中间结果覆盖了。

现在我做了一个硬性规定：多实例并发时，上下文必须以trace_id为键做隔离，Agent内部绝不能使用共享的实例变量去存中间产品。 每个Agent处理函数接收的消息里都带着trace_id，想存时先取到本任务专属的context。

下面是一个高并发下安全的写法示例：

python复制class FlowManager:
    def __init__(self):
        self.contexts: dict[str, FlowContext] = {}

    def get_context(self, trace_id: str) -> FlowContext:
        if trace_id not in self.contexts:
            self.contexts[trace_id] = FlowContext(trace_id)
        return self.contexts[trace_id]

    def cleanup(self, trace_id: str):
        self.contexts.pop(trace_id, None)

每个Agent需要存取流程级数据的时候，用它来管理，而不是自创全局变量。

6.5 事件定义太随意，数据形态隐式依赖

有段时间团队里新来的同学加Agent时会随手定义新事件，比如cleaned、result_ok，导致编排器里越来越乱。每个Agent要消费什么字段也靠口头沟通，某个Agent改了输出的key，下游立刻爆出一堆KeyError。

后来我把Agent接入模板固定下来，每个Agent的开发必须提供一份伴随消息合约的说明：事件名、输出payload的几个核心字段、可能产生的失败类型。校验层会在测试环境强制检查这些合约字段是否存在。看起来增加了一点文书工作，但换来的是整个团队并行开发Agent时不需要频繁沟通坐标。

6.6 快速自查清单：分离是否到位

在做架构review时，我会拿下面这个清单过一遍代码：

• Agent是否持有其他Agent的类或实例引用？
• 是否在Agent内部写了if xxx == “agent_a”这种分支？
• 新增一个Agent是否必须修改既有Agent的代码？
• 是否有除编排器以外的代码直接订阅事件？
• Agent的输出字段是否依赖了上游Agent的私有格式定义？
• 控制状态是否散落在多个Agent的全局变量里？

如果以上任何一项为“是”，说明数据流和控制流还没有完全分离，架构重构还需要继续。别急着交付，先把脏东西清干净。

7. 关于可复用和扩展的一些额外心得

7.1 先从小流程练手，别一上来就搭“万能框架”

我见过不少团队看了这类文章后立刻热血沸腾，想引入一个特别复杂的Agent编排框架。但实际项目中，最缺的往往不是框架能力，而是团队对“事件边界”的认知。如果连自己业务里什么是事件、什么是Agent职能都说不清楚，框架再强也白搭。

我建议从一条最简单的流程起步：三个Agent串起来，手工定义好事件和字段，把消息总线跑通。感受一下事件化思维和函数调用思维的差别。等团队习惯了这套思维再扩展，你会发现Agent加得越多，这套结构的优势体现得越明显，边际成本越来越低。

7.2 数据流是“契约”，控制流是“策略”——二者发生冲突时怎么办

在实际业务里，数据格式的定义往往要先于控制流程画出来。原因是数据契约一旦确定，Agent之间的语义边界就稳定了，后续调控制流只是改路由。如果数据契约不稳定，团队就会陷入一个怪圈：想改数据格式，但下游Agent全要跟着改，改动范围能波及整条链路。

所以我在启动一个多Agent项目时最重视的就是数据契约。前期宁可多花时间讨论清楚采集结果长什么样、清洗结果长什么样、摘要结果长什么样，也不急着把Agent全写出来。数据契约讨论得越扎实，后面控制流的调整就越轻松。

7.3 什么时候需要从进程内总线升级到分布式组件

如果你Agent数量不多、全部跑在同一个Python进程里，那我上面写的轻量进程内总线足够用了，别引入额外中间件去增加运维成本。但如果你遇到这几个信号，就要考虑升级了：

• Agent开始部署到多个机器上。
• 流程并发数大，进程内队列产生阻塞。
• 需要对历史消息做回放和审计查询。
• 不同的Agent使用不同的技术栈实现，需要语言的隔离。

这时候可以把MessageBus替换成Redis Stream或Kafka等成熟的消息中间件。好消息是由于我们前期把消息结构和订阅逻辑都抽象好了，替换总线实现不需要修改Agent内部逻辑，只要把总线适配层重写一遍即可。

8. 再分享一个没用上但很关键的小技巧

最后想留一个小技巧给读到这里的你。无论你的架构设计得多好，Agent本身的行为依然有可能产生不可控——比如模型输出格式漂移、工具调用失败、上下文被截断。这套分离架构能帮助你快速定位问题，但并不能让Agent不出问题。所以有条件的话，尽量让Agent只做“纯函数式”的处理逻辑，即输入消息进来，输出消息出去，内部不要残留跨消息的隐式状态。

我从踩过坑的实际感受来说，这套架构最大的价值在于：当你需要在下周一临时接入一个新Agent去参与一个老流程时，你不需要熬夜通读老代码、不需要发版所有Agent服务，只需要在编排配置里加两行路由、带上新Agent自己上线的服务，事情就接上了。这种感觉对于一个靠业务吃饭的团队来说，会让人非常安心。数据流和控制流的分离不是银弹，应对不了模型效果不好或者流程设计本身没用的问题，但在协作架构的扩展性这件事上，它能把系统维护成本降一个量级，值得多花点心思去打磨。