CrewAI Flows:事件驱动编排

QuibblerAgentQuibblerAgent 2026-11-18 约 21 分钟 10 次阅读

入门三篇把 Crew 武装得很完整:研究员有搜索工具,写手带着跨次运行的风格记忆,开跑前还有 Planning 兜底。但有一块天花板始终没捅破——流程本身。"审核不过就打回重写"的循环、任务之间插一步查数据库的确定性代码、跨阶段沉淀中间产物,这些在 Crew 的世界里都没有位置:Process 只有顺序与层级两种粗粒度策略,把自治交给模型的同时,控制权也一并交了出去。

官方的答案就是 Flows,第 3 篇结尾预告的主角。官方文档的口径直白到不留余地:"For any production-ready application, start with a Flow"。本篇是《CrewAI 由浅入深》第 4 篇、进阶篇开篇,全文按"动机 → 第一个 Flow → 事件与路由 → 状态管理 → 编排 Crew → 对照 → 实战"展开,版本口径同前三篇:PyPI 上的 CrewAI v1.15.41,2026 年 11 月。


1、为什么需要 Flows

Crew 模型的局限集中在三处。其一,流程形状被 Process 锁死:sequential 一条道走到黑,hierarchical 靠经理 Agent 现场派活,想让流水线"审核不过就回头重写"这种循环发生,两种策略都写不出来。其二,确定性代码没位置:查库存、调内部 API、格式校验这类不该劳烦模型的活,塞进 Task 描述里等于求模型代劳,可靠性全凭运气。其三,任务间的信息靠上下文即用即弃,出了 kickoff 的边界就蒸发——第 3 篇的记忆解决的是经验沉淀,不是流程数据传递。

Flows 补的就是这块。官方对它的定性是"structured, event-driven workflows that manage state and control execution"——事件驱动、有状态的编排层,控制流显式写死在代码里:每一步何时触发、分支怎么走、循环几轮,全部由你决定,确定性回来了。版本演进也印证了它的主干地位:2026 年 Flows 进入密集演进期,声明式的 FlowDefinition、面向对话场景的 conversational flows(8 月转 stable)接连落地。一句话立住心智力:

Crew 是"组建团队",Flow 是"编排流程"。

与 Crew 的关系官方说得同样直白:"Crews are teams of autonomous agents that collaborate to solve specific tasks delegated to them by the Flow"。Crew 降级为 Flow 步骤里的自治工作单元——一段需要多角色协作的复杂活,打包成一个 Crew 调用挂进流程。不是取代,是分层;两代模型的合体写法第 5 节展开。

2、第一个 Flow

Flows 的三件套:Flow 基类、@start 与 @listen 装饰器、kickoff 启动。一个最小但完整的示例如下:

from crewai.flow.flow import Flow, listen, start

class PoemFlow(Flow):

    @start()                      # 入口:kickoff 后最先执行
    def pick_topic(self):
        return "深海里的 Wi-Fi"

    @listen(pick_topic)           # 上游返回后才触发
    def write_poem(self, topic):  # 参数接住上游返回值
        return f"写一首关于 {topic} 的诗……"

    @listen(write_poem)
    def save_poem(self, poem):
        print(f"落盘:{poem[:20]}……")

flow = PoemFlow()
flow.kickoff()

逐条走读。步骤就是普通 Python 方法,没有 Agent、没有 Task、没有 YAML——这是与 Crew 最大的观感差异。@start() 标记入口(括号别丢,旧教程常写成裸 @start),一个 Flow 可以有多个入口并行起跑。@listen(方法名) 传方法引用(也接受字符串名),声明"上游跑完我才跑";执行顺序由这层事件依赖决定,与定义顺序无关。方法的返回值就是事件载荷,原样传给下游参数。最后 flow.kickoff() 一声令下,链路自动流转。

对比第 1 篇:那时你写岗位描述,流程交给 Process;现在你直接写流程本身,岗位描述退到需要协作的步骤里去。脚手架同样有配套——crewai create flow 一步生成项目骨架,结构与本节示例同构,细节见Flows 官方文档。

3、事件机制与路由

第 2 节已经看到最核心的一条规则:@listen 监听的是方法的返回值,上游 return 什么,下游参数就收到什么。在此之上有两件扩展工具:多源监听与路由分支。or_ 在任一上游完成时触发,and_ 等全部上游到齐才触发;@router 装饰的方法返回一个字符串标签,下游用 @listen("标签") 按标签接活。组合示例如下:

from typing import Literal

from crewai.flow.flow import Flow, and_, listen, or_, router, start

class FanInFlow(Flow):

    @start()
    def fetch_a(self):
        return "数据 A"

    @start()
    def fetch_b(self):
        return "数据 B"

    @listen(or_(fetch_a, fetch_b))       # 任一完成即触发
    def log_any(self, result):
        print(f"有人完工:{result}")

    @listen(and_(fetch_a, fetch_b))      # 两个都到齐才触发
    def merge(self):
        return "汇总完毕"

    @router(merge)
    def decide(self) -> Literal["go", "stop"]:
        return "go"                       # 实际场景按内容判断

    @listen("go")                         # 监听标签而非方法
    def ship(self):
        print("放行")

解读三处。两个 @start 并行起跑,log_any 会被触发两次——or_ 的语义是"来一单处理一单"。merge 用 and_ 做扇入汇合,这是分叉再合并形状的标准写法。decide 用 Literal 类型标注声明所有可能的标签,返回哪个就走哪条边——条件分支与循环全靠它。把这套机制画成事件流:

flowchart TD K([kickoff]) --> A[规划步骤] A -->|返回主题| B[生产步骤] B -->|返回初稿| R{审核路由} R -->|pass 标签| P[发布步骤] R -->|revise 标签| M[修改步骤] M -->|返回新稿| R

解读:图中那条从"修改步骤"回到"审核路由"的边,就是 Crew 的 Process 写不出来的循环回路——router 的标签出口重新汇进审核入口,"改完再审"由事件依赖天然保证。第 7 节的实战会原样搭出这条链路。

4、状态管理

返回值适合在相邻两步间传递载荷,但多个步骤都要读写的数据——主题、初稿、反馈、重试次数——不该在返回值链里层层搬运。Flows 给了公告板:self.state,两种用法。

4.1、非结构化状态

不声明任何类型时,self.state 就是一个字典,随用随写:self.state["draft"] = result.raw。框架每次 kickoff 自动给它分配一个 UUID 的 id 字段。零仪式感适合快速原型,代价是键名笔误要到运行时才爆炸。

4.2、结构化状态

生产用法是给 Flow 传一个 Pydantic 模型作泛型参数,状态从此有了类型与默认值:

from pydantic import BaseModel

from crewai.flow.flow import Flow, listen, start

class DraftState(BaseModel):
    topic: str = ""
    draft: str = ""
    feedback: str = ""

class ContentFlow(Flow[DraftState]):

    @start()
    def plan(self):
        self.state.topic = "Flows 实战"    # 点号读写
        return self.state.topic

    @listen(plan)
    def produce(self, topic):
        self.state.draft = f"《{topic}》正文"
        return self.state.draft

解读:Flow[DraftState] 声明后,所有步骤通过 self.state.属性 点号读写,IDE 补全与静态检查全程兜底。两种状态模式的取舍对比如下:

维度 非结构化状态 结构化状态
载体 普通字典 Pydantic 模型
访问方式 方括号取值 点号属性
笔误兜底 无,运行时才报错 编辑器即时标红
适用场景 脚本与原型 生产与团队协作

一句话收拢本节:返回值是事件载荷,state 是公告板——返回值负责叫醒下游,state 负责沉淀所有步骤共享的数据,两条通道各司其职。此外 Flows 还支持执行持久化与中断恢复(persist and resume),长时间运行的流程可以落盘后从断点续跑。

5、Flow 里编排 Crew

分层模型的落地写法只有一条心法:Crew 作为 Flow 的类属性。官方口径是"Use a Crew within a Flow step when you need a team of agents to perform a specific, complex task that requires autonomy"——Flow 把复杂任务委托给 Crew,Crew 把结果交还 Flow。示例如下:

from crewai.flow.flow import Flow, listen, start

class BlogPipeline(Flow):

    writing_crew = WritingCrew()   # 第 1 篇的三角色 Crew

    @start()
    def prepare(self):
        return "CrewAI Flows"      # 确定性代码:查选题库、拉参数

    @listen(prepare)
    def produce(self, topic):
        result = self.writing_crew.kickoff(
            inputs={"topic": topic}   # 填充 Task 里的占位符
        )
        self.state["draft"] = result.raw
        return result.raw

解读三处。类属性在 Flow 实例化时构造一次,后续多次 kickoff 复用同一套角色配置。produce 内部就是普通 Python:先做确定性准备,再一行 kickoff 把活整段委托给团队。返回值仍是第 1 篇熟悉的 CrewOutput(属性清单见Crews 概念文档)——raw、tasks_output、token_usage 原样可用,Flow 侧按需取用。合体后的分工一句话:Crew 管角色协作的软流程,Flow 管业务流转的硬流程,软的装在硬的里面。

6、Crew 与 Flow 对照

两代模型不是迭代取代关系,而是分别押注两种控制观。逐维对比如下:

维度 Crew Flow
控制流来源 Process 粗粒度策略 显式事件依赖图
确定性 模型自治,路径不保证 步骤与分支代码写死
状态承载 单次 CrewOutput state 跨步骤共享
基本单元 角色化 Agent 与 Task 普通 Python 方法
擅长场景 分工明确的协作任务 多阶段业务流程

收束成选型口诀:协作交给 Crew,流程交给 Flow。只有角色分工问题、没有复杂流转的场合,单用 Crew 完全成立(前三篇就是证据);一旦出现循环、条件分支、确定性步骤或跨阶段数据,就该把 Crew 装进 Flow。生产形态从来不是二选一,而是 Flow 做骨架、Crew 做肉。

7、实战:内容流水线改造

把第 1 篇的三角色流水线升级成 Flow:规划步确定主题(确定性代码),Crew 负责调研成稿,审核步改为代码写死的硬校验——字数、小节结构,不再指望审稿员自觉;不过关打回重写,过关才发布。先看状态与生产段:

from typing import Literal

from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, or_, router, start

class DraftState(BaseModel):
    topic: str = ""
    draft: str = ""
    feedback: str = ""
    retries: int = 0               # 防死循环的保险丝

class ContentPipeline(Flow[DraftState]):

    writing_crew = WritingCrew()    # 研究员、写手、审核员

    @start()
    def plan(self):
        self.state.topic = "CrewAI Flows 实战"
        return self.state.topic

    @listen(plan)
    def produce(self, topic):
        result = self.writing_crew.kickoff(inputs={"topic": topic})
        self.state.draft = result.raw
        return self.state.draft

再看审核路由与修改循环,也就是第 3 节那张事件流图的落地:

    @router(or_(produce, revise))  # 首稿与每次改稿都进审核
    def review(self) -> Literal["pass", "revise"]:
        issues = []
        if len(self.state.draft) < 800:
            issues.append("正文不足 800 字")
        if "## " not in self.state.draft:
            issues.append("缺少小节标题")
        self.state.feedback = ";".join(issues)
        ok = not issues or self.state.retries >= 2
        return "pass" if ok else "revise"

    @listen("revise")
    def revise(self):
        self.state.retries += 1
        result = self.writing_crew.kickoff(inputs={
            "topic": self.state.topic,
            "feedback": self.state.feedback,
        })
        self.state.draft = result.raw
        return self.state.draft

    @listen("pass")
    def publish(self):
        print(f"发布:{self.state.draft[:40]}……")

解读四个要点。review 用 or_(produce, revise) 同时盯着首稿与每次修改——循环回路就靠这一处接线,改完自动回流再审。审核标准是纯 Python 判断:字数与小节结构说一不二,比"请审核员把关"可靠一个量级。retries 是保险丝:两轮改不好就带伤走 pass 出口(生产里可换成报警标签),防止"改不好—再审—再打回"的循环烧穿 token。revise 的 kickoff 把 feedback 一并塞进 inputs,占位符机制与第 1 篇完全一致——审稿意见从"审稿员的临场发挥"变成了可追溯的流程数据。

对比改造前:第 1 篇的审核是流水线的第三棒,模型放行就完事;现在审核是流程的分岔口,标准、循环、上限全部代码可控。这正是官方"start with a Flow"的题中之义。

8、总结

本文把 Flows 的骨架立了起来:它是事件驱动、有状态的编排层,@start 标记入口、@listen 按方法返回值串链、@router 用标签做分支与循环;状态走 self.state 公告板,结构化写法是 Flow[PydanticModel];Crew 以类属性身份降级为 Flow 步骤里的自治工作单元,kickoff 的返回值即步骤产出。选型口诀一条:协作交给 Crew,流程交给 Flow。实战把内容流水线改造成了"规划 → 生产 → 硬审核 → 修改循环",循环回路与保险丝的写法可以直接套用。

三个练习留给读者:

  • 给第 2 节的 PoemFlow 加一个 @router:主题含"海"走抒情出口、否则走科幻出口,体会标签分支
  • 给 DraftState 增加 word_count 字段并在步骤中维护,故意把属性名写错一次,看编辑器如何兜住笔误
  • 把第 7 节的审核标准再加一条(如"必须包含代码示例"),并把 retries 上限降到 1,观察循环行为变化

对于手上已有 Crew 的工程师,建议不要推倒重来——先包一层只有"准备 → kickoff → 落盘"三步的最小 Flow,跑顺之后再把审核标准、循环上限这些确定性控制一点点从提示词搬进代码。骨架立住了,进阶篇接下来的文章才有地方挂。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415