Workflows 把编排还原成普通 async Python :一个 step 收到某类事件、干活、再发出另一类事件,控制流由类型注解隐式连成,没有节点表也没有边表。代价是拓扑不在一个地方,得靠画图工具才能看见。本文按「事件 → step → 状态 → 并发 → 流式 → 重试 → 人机 → 持久化 → 上线」的顺序讲透,并附上在本机真跑出来的两个反直觉结果。
实测于 2026-11-21llama-index-workflows 2.26.1Python 3.10.716 节 · 14 表 · 14 段代码 · 13 个坑
Contents
- 定位与版本
- 三种编排范式对比
- 最小可运行流程
- 事件体系
- 注解驱动的拓扑
- [Context 与状态](#Context 与状态)
- 并发、扇出与扇入
- 流式输出
- 重试与超时
- 人机协同
- 持久化与断点
- 资源注入
- 可观测性与服务化
- AgentWorkflow
- 十三个坑
- 高难问题
01 · Orientation
定位与版本:先分清两个导入路径
Workflows 最早内置在 llama-index-core 里,2025 年中独立成包 llama-index-workflows,2025-06-30 宣布 1.0、2025-08-30 发布 2.0。今天写新代码应该用独立包,而不是核心包里那份较旧的稳定版1。
| 包 | 截至 2026-11 的版本 | 导入 | 适用场景 |
| llama-index-workflows | 2.26.1(2026-10-22) | from workflows import Workflow, Context, step | 新项目;只想要编排、不需要整套 RAG 依赖 |
| llama-index-core | 0.14.26(2026-11-14) | from llama_index.core.workflow import ... | 已经用 LlamaIndex 做 RAG / Agent,顺手复用内置那份 |
llama-index-utils-workflow |
0.7.x | from llama_index.utils.workflow import draw_all_possible_flows |
画流程图、导出最近一次执行路径 |
|---|---|---|---|
| [表 1:两个包、两个导入路径] |
两个路径的 API 长得一样,但版本会漂 :核心包 re-export 的是它自己锁定那一版2。踩过的最典型差异是 ctx.get() / ctx.set():老教程里到处是它们,而在 2.26.1 里这两个方法已经不存在 (实测 hasattr(ctx, "get") 为 False),统一改成异步的 ctx.store.get() / ctx.store.set()7。
本文的实测边界
下面所有代码与输出,都在 Windows + Python 3.10.7 + llama-index-workflows 2.26.1 的环境里真跑过。没有装 llama-index-core,也没有接任何 LLM------Workflows 本身不需要模型就能跑,这也是它最适合先学编排的原因。涉及 WorkflowServer、DBOS、OTel 的部分来自官方文档,本文会明确标注。
02 · Paradigms
三种编排范式:事件驱动、显式图、装饰器连线
选框架时最该问的不是"谁功能多",而是控制流写在哪里。这决定了你调试时看什么、重构时改什么、以及能不能断点续跑。
| 维度 | LlamaIndex Workflows | LangGraph | CrewAI Flows |
| 控制流在哪 | 类型注解。返回事件 A,触发参数注解为 A 的 step | 节点表 + 边表,显式声明 | 装饰器参数 @listen(方法名) |
| 拓扑是否先声明 | 不声明,是注解的副产物,可运行时动态生成 | 必须先声明,循环也要显式加边 | 半显式,靠方法名连线 |
| 状态 | 每次 run 一个 Context,可序列化 | 图级共享 state + thread 检查点 | self.state + @persist |
| 断点续跑 | Context 快照 + 手动 step 级快照 | 内建 checkpointer,一等公民 | kickoff(restore_from_state_id=...) |
| 上手成本 | 最低,写起来像普通 async 代码 | 最高,要先设计图 | 低,但要接受 CrewAI 生态 |
|---|---|---|---|
| [表 2:Workflows 与三个主流编排框架的设计差异] |
事件驱动的真正好处不是"少写代码",而是加一条分支只需加一个事件类和一个 step ,不用回头改任何已有连线。真正坏处也很明确:拓扑不在一处 ,读代码时你得靠注解在脑子里重建图,静态分析基本帮不上忙。所以画图工具在 Workflows 项目里不是可选项,是必需品8。
03 · First Run
最小可运行流程:17 行看完全部骨架
PowerShell · 只装编排库
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install llama-index-workflows
.\.venv\Scripts\python.exe -c "import importlib.metadata as m; print(m.version('llama-index-workflows'))"
实测输出2.26.1
Python · 一个能跑的最小 Workflow(含状态与流式)
import asyncio
from workflows import Workflow, Context, step
from workflows.events import Event, StartEvent, StopEvent
class Progress(Event):
msg: str
class Parsed(Event):
text: str
class DocFlow(Workflow):
@step
async def parse(self, ctx: Context, ev: StartEvent) -> Parsed:
ctx.write_event_to_stream(Progress(msg="parsing")) # 给外部看的进度
text = str(ev.text).strip()
await ctx.store.set("chars", len(text)) # 本次 run 的状态
return Parsed(text=text)
@step
async def summarize(self, ctx: Context, ev: Parsed) -> StopEvent:
chars = await ctx.store.get("chars", default=0)
return StopEvent(result=f"{ev.text[:12]}...({chars})")
async def main():
w = DocFlow(timeout=30)
h = w.run(text=" hello workflows ")
async for ev in h.stream_events():
if isinstance(ev, Progress):
print("progress:", ev.msg)
print("result:", await h)
asyncio.run(main())
实测输出progress: parsing result: hello workfl...(15)
这 17 行已经包含四件事:入口事件 (StartEvent 的 kwargs 变成属性)、状态 (ctx.store)、对外流式 (write_event_to_stream,只给外部看,不参与路由)、出口事件 (StopEvent.result)。剩下的一切都是这三种东西的组合。
run() 返回的不是结果,是 handler
w.run(...) 立刻返回一个 handler,它既可以被 await 取最终结果,也可以被 stream_events() 消费事件流3。顺序无所谓:先 await 再 stream 拿不到事件,因为流只保留到你消费为止6。
04 · Events
事件体系:一切连接的最小单位
事件是 Pydantic 模型,字段即载荷。自定义事件就是继承 Event 并声明字段,没有注册、没有 ID、没有字符串名字------类型本身就是身份。
| 事件 | 方向 | 说明 |
| StartEvent | 入口 | run(topic="x") 的 kwargs 成为字段;也可直接传 start_event=实例 获得校验 |
| StopEvent | 出口 | result 承载返回值;工作流一收到就停 |
| Event | 中间 | 用户自定义事件的基类,建议一个事件一件事 |
| InputRequiredEvent | 出 → 人 | 需要人类输入时写入对外流 |
| HumanResponseEvent | 人 → 入 | 人类回答通过 handler.send_event() 送回 |
| WorkflowTimedOutEvent | 终止 | 超时;是 StopEvent 子类 |
| WorkflowFailedEvent | 终止 | 带 step_name、exception、attempts |
StepStateChanged |
内部 | 默认被过滤,需 stream_events(expose_internal=True) |
|---|---|---|
| [表 3:内置事件清单(2.26.1)] |
StopEvent 子类会改变 run() 的返回类型
这条规则很多教程没写清楚:返回基类 StopEvent 时,await run() 得到的是 stop_event.result;返回子类 时,得到的是那个事件实例本身 。实测里定义了 class MyStop(StopEvent): extra: str = "x",跑完 await w.run() 拿到的类型是 MyStop,.extra 可读,而 .result 里放的是另一段字符串。
Python · 类型安全的出口
class ReportReady(StopEvent):
markdown: str
word_count: int
# 调用方拿到的是 ReportReady 实例,不再是 Any
ev = await flow.run(topic="workflows")
print(ev.word_count)
想固定入口形状就用 StartEvent 子类,好处是缺字段时在 run() 之前就报错,而不是在 step 里出 AttributeError16。
05 · Routing
注解驱动的拓扑:分支、循环,以及一个会静默超时的坑
连线规则只有一句:上游 step 的返回注解 → 下游 step 的参数注解,精确类型相等 。没有名字、没有注册表。由此推出三种常见结构4。
| 结构 | 怎么写 | 要点 |
| 分支 | -> A | B,函数体里 if 决定返回哪个 | 只发一个事件;两个分支的消费者可以是两个不同 step |
| 循环 | 某 step 返回一个上游已在消费的事件类型 | 典型是 -> LoopEvent | StopEvent,靠条件退出 |
| 子类路由 | @step(accept_event_subclasses=True) |
默认关闭;父类 step 不会自动收到子类事件 |
|---|---|---|
| [表 4:三种控制流的写法] |
实测:返回子类事件而消费者只认父类,会静默卡死 45 秒
我写了一个 step 注解为 -> P,实际却 return Child(v=1)(Child 是 P 的子类),消费者注解是 ev: P。运行结果不是报错,而是:
workflows.errors.WorkflowTimeoutError: Operation timed out after 45.0 seconds. No steps active
原因:路由按运行时事件的实际类型精确匹配 ,Child 找不到消费者,流程变成死路;而类定义期的校验只看到注解写的 P,所以放行了。加上 @step(accept_event_subclasses=True) 后立刻通过,消费者收到的 type(ev).__name__ 是 Child。这条坑的杀伤力在于错误信息只说"没有活跃 step",不说"你的事件没人接"。
先校验,再运行
Workflow 在启动前会做一次事件图校验:必须有 Start 与 Stop;被消费的事件必须有生产者;产出的事件必须有人消费。也可以手动调 wf.validate()(实测该方法存在)。但要注意校验看注解、运行看实例------上面那个坑正是两者的缝隙。
Python · 自定义循环:reflection 的两步
class Draft(Event):
text: str
class Critique(Event):
text: str
score: int
class ReflectFlow(Workflow):
@step
async def write(self, ev: StartEvent | Critique) -> Draft:
prev = ev.text if isinstance(ev, Critique) else "" # 入口与反思共用
return Draft(text=prev + "...")
@step
async def review(self, ev: Draft) -> Critique | StopEvent:
score = len(ev.text) % 10
if score >= 8:
return StopEvent(result=ev.text)
return Critique(text=ev.text, score=score)
循环靠"write 同时收 StartEvent 与 Critique"建立:入口一次、每轮反思一次。注意这种写法必须自己设退出条件 ,否则会一直转,直到撞上 timeout。
06 · State
Context 与状态:每次 run 一个独立容器
Context 有三重身份:状态容器、事件控制台、快照源。一个 step 想拿到它,只要在参数里写 ctx: Context,框架会自动注入7。
| API | 同步/异步 | 语义 |
| await ctx.store.set(k, v) | 异步 | 写本次 run 的状态 |
| await ctx.store.get(k, default=...) | 异步 | 读状态;default 避免 KeyError |
| async with ctx.store.edit_state() as s | 异步上下文 | 加锁的原子读改写;块内只放纯计算 |
| ctx.send_event(ev) | 同步 | 立即发出事件,可发数量未知的多个 |
| ctx.collect_events(ev, [T, T]) | 同步 | 没集齐返回 None;集齐按传入顺序返回 list |
| ctx.write_event_to_stream(ev) | 同步 | 写对外流,不参与路由 |
| ctx.to_dict() | 同步 | 快照:状态 + 事件队列 + broker log |
| Context.from_dict(wf, d) | 类方法 | 恢复快照,再把 ctx 传给 run(ctx=...) |
await ctx.wait_for_event(...) |
异步 | 等某类事件,可附带提示事件与匹配条件 |
|---|---|---|
| [表 5:Context 的 API 与语义(2.26.1 实测)] |
老教程里的 ctx.get() / ctx.set() 已经没了
实测 hasattr(ctx, "get")、hasattr(ctx, "set")、hasattr(ctx, "get_resource") 全是 False。照抄旧代码的报错是 AttributeError: 'Context' object has no attribute 'set',而错误信息不会提示你"改用 store"。迁移只需把 ctx.set(k, v) 改成 await ctx.store.set(k, v),把函数补成 async。
状态还能跨 run 复用
把同一个 ctx 传给下一次 run(ctx=ctx):如果它还在跑,等于恢复该 run(不会重发 StartEvent);如果已经结束,就在同一份状态上开新一轮。这构成了最简单的"多轮对话"实现,不需要额外的 session 概念。
Python · 用同一个 ctx 续跑
w = DocFlow(timeout=30)
h1 = w.run(text="first")
await h1
h2 = w.run(ctx=h1.ctx, text="second") # 沿用同一份 state
print(await h2)
需要类型约束时用 Context[MyState]:状态模型是 Pydantic 类,读写带上字段补全与校验,长流程里比一堆字符串 key 可靠得多。
07 · Concurrency
并发:返回什么,决定框架怎么跑
Workflows 的并发不是靠配置,而是靠返回值的形状 。同一个 step 返回一个事件、一个列表、或者 None,运行时行为完全不同5。
| 写法 | 语义 | 失败时 |
|---|---|---|
return A() |
发一个事件 | 不发,异常向上抛 |
return A() if x else B() |
分支,只发一个 | 同上 |
return [A(), A(), A()] |
一个批次扇出,并发处理 | 一个都不发(全有或全无) |
return None |
不发事件;在扇入里表示丢弃该分支 | --- |
参数 events: list[Done] |
整批收齐后只触发一次 | --- |
参数 (a: A, b: B) |
每个类型各到一个后触发一次 | --- |
| [表 6:返回形态与运行语义] |
Python · 扇出 5 路、丢弃偶数、按完成顺序收齐
class Task(Event):
n: int
class Done(Event):
n: int
class FanFlow(Workflow):
@step
async def fan_out(self, ev: StartEvent) -> list[Task]:
return [Task(n=i) for i in range(5)]
@step(num_workers=5)
async def work(self, ev: Task) -> Done | None:
await asyncio.sleep(0.01)
if ev.n % 2 == 0:
return None # 这条分支不出结果
return Done(n=ev.n)
@step
async def join(self, events: list[Done]) -> StopEvent:
return StopEvent(result=sorted(e.n for e in events))
await FanFlow(num_concurrent_runs=4).run() # 实测返回 [1, 3]
实测结果 [1, 3] 说明两件事:扇入不会因为两条分支 None 就永远等下去 (剩余分支齐全就触发),并且 list 的顺序是完成顺序 而非发出顺序------所以第二行我加了 sorted()。真实项目里如果顺序有意义,永远自己排序,别指望到达顺序。
| 参数 | 作用域 | 典型用法 |
| @step(num_workers=N) | 单次 run 内该 step 的并发副本数 | 限制对某接口的打并发量 |
| Workflow(num_concurrent_runs=N) | 进程内同时活跃的 run 数 | 保护下游,超出就排队 |
asyncio.Semaphore(n) |
你自己控制,跨 run 共享 | 限制第三方 API 的总并发 |
|---|---|---|
| [表 7:三个容易混淆的并发旋钮] |
list 与 ctx.send_event 的差别在失败语义:list 是全有或全无 (step 抛错就一个都不发),send_event 是边算边发(已发出的收不回来)。需要"先给用户看部分结果"就用后者,接受它不原子。
08 · Streaming
流式:一条只能消费一次的流
对外流与路由是两条完全独立的通道。write_event_to_stream() 发出去的事件不会触发任何 step ,只被 handler.stream_events() 的消费者看见。这是给 UI 做进度条的正确工具6。
Python · 消费事件流直到结束
handler = flow.run(topic="x")
async for ev in handler.stream_events():
match ev:
case Progress():
ui.update(ev.msg)
case StepStateChanged(): # 需 expose_internal=True
log.debug(ev.step_state)
case StopEvent():
break
result = await handler
三个必须知道的限制
- 一条流只能消费一次 。两个客户端各自
stream_events()拿不到同一份事件,多端展示要自己做广播。 - 先 await 再 stream 会丢事件。想边跑边看,就必须先拿 handler、先开始迭代。
- 内部事件
StepStateChanged默认被过滤,要stream_events(expose_internal=True)才可见。
异常终止也会往流里推事件
超时、取消、失败不会让 async for 静默结束:框架会先推一个 WorkflowTimedOutEvent / WorkflowCancelledEvent / WorkflowFailedEvent,然后再让 await handler 抛出对应异常。所以前端可以先用事件流显示"任务失败",后端再处理异常------不必只靠 try/except 猜。
09 · Resilience
重试与超时:一个按 step 配,一个按流程配
timeout 是 Workflow 的构造参数(实测默认 45.0 秒,None 关闭),不是 run() 的参数。run() 的签名只有 ctx、start_event 和若干 kwargs------把 timeout 传给 run() 只会变成一个无用的 StartEvent 字段。
Python · 组合式重试策略(2.26.1 实测可导入)
from workflows.retry_policy import (
retry_policy, retry_if_exception_type,
wait_fixed, wait_exponential_jitter,
stop_after_attempt, stop_after_delay,
)
policy = retry_policy(
retry=retry_if_exception_type((TimeoutError, ConnectionError)),
wait=wait_exponential_jitter(initial=1, max=8),
stop=stop_after_attempt(4) | stop_after_delay(30),
)
class FetchFlow(Workflow):
@step(retry_policy=policy)
async def fetch(self, ev: StartEvent) -> StopEvent:
return StopEvent(result=await call_api())
| 能力 | 配置位置 | 说明 |
| 单步重试 | @step(retry_policy=...) | 只有被装饰的 step 会重试;其余步骤不受影响 |
| 重试条件 | retry=retry_if_exception_type(...) | 支持 | 组合(任一),也有 &(同时) |
| 等待策略 | wait=wait_fixed / wait_exponential_jitter | 可相加组合,做出"固定 + 抖动" |
| 停止条件 | stop=stop_after_attempt(n) | stop_after_delay(s) | 两个条件谁先满足谁停 |
| 整体超时 | Workflow(timeout=...) | 超时抛 WorkflowTimeoutError |
| 默认策略 | retry_policy() 无参 |
所有异常、最多 3 次、固定 5 秒 |
|---|---|---|
| [表 8:重试与超时的分工] |
旧写法 ConstantDelayRetryPolicy(delay=5, maximum_attempts=10) 仍然能导入,但已被标记为不推荐;等价的新写法是 retry_policy(wait=wait_fixed(5), stop=stop_after_attempt(10))9。另外不要去找 WorkflowRetryPolicy 这个类------它属于 Dapr / Temporal 那一族,LlamaIndex 里没有工作流级别的统一重试参数。
超时时间的真实含义
它限制的是整个 run 的墙钟时间 ,包括所有 step 与所有等待。带人机协同的流程(等人审批)如果把 timeout 留在 45 秒,人还没点按钮就超时了。这类流程通常要配 timeout=None,改用业务层的过期策略来兜底。
10 · Human in the Loop
人机协同:两种写法,选错了会重跑代码
Workflows 没有"暂停"按钮,人机协同靠一对事件实现:step 把 InputRequiredEvent 写进对外流,等人类通过 handler.send_event(HumanResponseEvent(...)) 送回答案10。
| 写法 | 结构 | 注意 |
| 两个 step(推荐) | step A 返回 InputRequiredEvent;step B 收 HumanResponseEvent 继续 | 流程自然停在事件边界,没有重放问题 |
| 单 step 内等待 | await ctx.wait_for_event(HumanResponseEvent, waiter_event=..., waiter_id=..., requirements=...) |
会重放 wait 之前的代码,前面必须有幂等性 |
|---|---|---|
| [表 9:两种实现路径的取舍] |
Python · 事件式人机协同
class AskApproval(Workflow):
@step
async def draft(self, ev: StartEvent) -> InputRequiredEvent:
return InputRequiredEvent(prefix=f"批准这份草稿吗?{ev.title}")
@step
async def publish(self, ev: HumanResponseEvent) -> StopEvent:
return StopEvent(result=f"human said: {ev.response}")
# 调用侧
handler = AskApproval(timeout=None).run(title="周报")
async for ev in handler.stream_events():
if isinstance(ev, InputRequiredEvent):
await handler.send_event(HumanResponseEvent(response="ok"))
单 step 等待为什么会重放
wait_for_event 的语义是"这个 step 被重新调度,从函数开头再跑一遍,直到那次 wait 命中条件"。所以如果把"扣款""发邮件"写在 wait 之前,重放就会真的扣两次 。官方文档给的实测签名是 (event_type, waiter_event=None, waiter_id=None, requirements=None, timeout=2000),requirements 用于多个 waiter 抢同一类事件时做路由。
Web 场景要跨请求,就得存 Context
handler 是进程内对象。收到 InputRequiredEvent 后如果直接等,用户关掉页面就永远占着一个协程。正确做法是:handler.ctx.to_dict() 存库 → 结束当前 run → 用户提交时 Context.from_dict(...) 恢复并 send_event。多副本部署时这不是优化,是必须。
11 · Durability
持久化与断点:2.x 没有内置 checkpointer
这是个版本差异容易被忽略的地方:llama-index-core 时代曾提供 WorkflowCheckpointer(按 step 自动建检查点,支持 run_from),而独立 workflows 1.x 之后官方明确写了**"没有可开启的内置 checkpointer"** ,改为让你自己监听内部事件做快照11。
Python · 自己写 step 级快照
from workflows.events import StepStateChanged, StepState
async for ev in handler.stream_events(expose_internal=True):
if isinstance(ev, StepStateChanged) and ev.step_state == StepState.NOT_RUNNING:
db.save(run_id, json.dumps(handler.ctx.to_dict())) # 该 step 已完成
| 路径 | 粒度 | 代价 |
| ctx.to_dict() 手动存 | 你决定何时存 | 要自己写循环;快照含事件队列,体积可能不小 |
| DBOS runtime | 每个 step 自动落库 | 引入外部运行时与数据库 |
WorkflowServer |
handler 级持久化 | 默认内存存储,重启即丢;要配 Sqlite/DBOS |
|---|---|---|
| [表 10:三种持久化路径] |
恢复语义是 at-least-once :已完成的 step 不重跑,但崩溃时正在执行的那个 step 会从头再来。因此每个 step 的副作用都必须可重复 ------发邮件要带去重键,写库要用幂等 upsert。实测 ctx.to_dict() 与 Context.from_dict() 在 2.26.1 上可用,但要求状态里的值都能 JSON 序列化:塞了数据库连接或 bytes 会在快照时整体失败。
12 · Resources
资源注入:把重量级依赖从状态里赶出去
别把数据库连接、LLM 客户端、检索器塞进 ctx.store------它们不可序列化,一存快照就整体失败。正解是用 Resource 声明在 step 参数上,由框架创建与缓存12。
Python · 用 Annotated 注入(实测可用)
from typing import Annotated
from workflows.resource import Resource
def make_db() -> FakeDB:
return FakeDB()
class ResFlow(Workflow):
@step
async def s(self, ev: StartEvent,
db: Annotated[FakeDB, Resource(make_db)]) -> StopEvent:
return StopEvent(result=db.name)
实测输出db
| 要点 | 行为 |
| 缓存粒度 | 默认每次 run 缓存一份:同一 run 内多个 step 拿到同一实例,factory 只调一次 |
| 关闭缓存 | Resource(factory, cache=False) 每次注入都新建 |
| 配置类资源 | ResourceConfig(config_file="x.json", path_selector="...") 把 JSON 配置解析成 Pydantic 模型 |
| 快照恢复 | 资源不被序列化,恢复时重新调 factory 创建 |
|---|---|
| [表 11:资源注入的四个要点] |
还有一个反直觉的实测结论:ctx.get_resource() 并不存在 (hasattr 为 False)。网上有些片段是按名字从 ctx 里取资源,那是别的框架或很旧的版本。在 2.x 里资源只能通过参数注解注入。
13 · Production
可观测性与服务化:插桩是自动的,导出不是
Workflows 默认给每个 step 打 instrumentation(记录输入输出与嵌套关系),但**"有 span"不等于"发到后端"** 。要进 OpenTelemetry 需要额外装 llama-index-observability-otel 并显式启动 exporter13。
Python · 接 OTel(需单独安装)
from llama_index.observability.otel import LlamaIndexOpenTelemetry
instrumentor = LlamaIndexOpenTelemetry(
span_exporter=your_exporter,
service_name_or_resource="weekly-report",
)
instrumentor.start_registering()
两种服务化方式
官方主路径是 WorkflowServer:它把工作流挂成 HTTP API,自带一套 handler 生命周期管理与调试 UI14。轻量集成则直接在 FastAPI 里 await,因为 Workflows 本身是 async-first。
| 端点 | 作用 |
|---|---|
POST /workflows/{name}/run |
同步执行并返回结果 |
POST /workflows/{name}/run-nowait |
异步启动,立刻返回 handler_id |
GET /results/{handler_id} |
查结果;仍在跑返回 202 |
GET /events/{handler_id} |
订阅事件流(NDJSON,可转 SSE) |
POST /events/{handler_id} |
向运行中的流程注入事件,人机协同用这个 |
POST /handlers/{handler_id}/cancel |
取消运行 |
| [表 12:WorkflowServer 的主要端点] |
Python · 自己用 FastAPI 做 SSE
from fastapi.responses import StreamingResponse
@app.post("/stream")
async def stream():
handler = ReportFlow(timeout=120).run(topic="workflows")
async def gen():
async for ev in handler.stream_events():
yield f"data: {ev.model_dump_json()}\n\n"
return StreamingResponse(gen(), media_type="text/event-stream")
多副本部署的第一杀手:把 handler 放在内存里
handler 是进程内对象。用户请求打到副本 A 启动流程,下一轮轮询打到副本 B,就拿不到任何东西。WorkflowServer 默认的 MemoryWorkflowStore 同样如此------要么做会话粘滞,要么配 SqliteWorkflowStore(单进程)或 DBOS + Postgres(分布式)。这不是"以后再说"的性能问题,是功能会直接坏掉。
14 · AgentWorkflow
AgentWorkflow:官方预构建的那一个 Workflow
学完前面 13 节,AgentWorkflow 就没什么神秘的了:它就是一个已经写好的 Workflow ,内部用事件完成"用户消息 → root agent → handoff → 回复"的循环。单 Agent 是它只有一个节点的退化情况15。
Python · 多 Agent 交接
from llama_index.core.agent.workflow import AgentWorkflow, FunctionAgent
calc = FunctionAgent(
name="calc", description="算数",
tools=[add], llm=llm,
can_handoff_to=["search"],
)
search = FunctionAgent(
name="search", description="检索文档",
tools=[query_engine], llm=llm,
)
wf = AgentWorkflow(agents=[calc, search], root_agent="calc")
result = await wf.run(user_msg="先查文档再算总数")
| 你要做的事 | 用哪个 |
|---|---|
| 固定的业务流水线(检索 → 写作 → 校验) | 手写 Workflow:顺序与分支由你控制,成本可预测 |
| 让模型自己决定下一步找谁 | AgentWorkflow:root 路由 + handoff,代价是轮次不可预测 |
| 混合:流程里嵌一个会思考的步骤 | 手写 Workflow,把 AgentWorkflow 当子流程或工具调用 |
| [表 13:Workflow 与 AgentWorkflow 的分工] |
事件流同样可观测:AgentInput、AgentStream、ToolCall、ToolCallResult、AgentOutput。前端要"打字机效果"就消费 AgentStream,要展示工具调用链就消费 ToolCall 那一对。
15 · Pitfalls
十三个坑:前四个是本机真跑撞出来的
| # | 现象 | 根因 | 修法 |
| 1 | WorkflowTimeoutError: No steps active,等满 45 秒 | 返回了子类事件,消费者只认父类;路由是精确类型匹配 | 消费者加 @step(accept_event_subclasses=True),或让生产者返回注解与实际类型一致 |
| 2 | AttributeError: 'Context' object has no attribute 'set' | 照抄旧版 API;2.x 已改为 ctx.store | await ctx.store.set(k, v),函数补 async |
| 3 | await run() 返回值不是预期的字符串 | 返回了 StopEvent 子类,得到的是事件实例 而非 .result | 要么读 ev.result,要么统一返回基类 StopEvent |
| 4 | 扇入结果顺序每次都不一样 | list 参数按完成顺序收集 | 拿排序键显式 sorted() |
| 5 | 把 timeout 传给 run() 没生效 | run() 只接 ctx / start_event / kwargs,timeout 变成 StartEvent 字段 | 写在 Workflow(timeout=...) 构造里 |
| 6 | 流式事件丢了一半 | 先 await handler 再 stream_events();或两个消费者抢同一条流 | 先拿 handler 先迭代;多端自己做广播 |
| 7 | 找不到 workflow.draw() | 2.x 的 Workflow 没有这个方法 | 装 llama-index-utils-workflow,用 draw_all_possible_flows() |
| 8 | 快照 to_dict() 直接抛序列化错误 | state 里存了连接、bytes、自定义对象 | 只存可 JSON 化的值;依赖走 Resource 注入 |
| 9 | 恢复后某个 step 又跑了一遍,副作用重复 | 恢复语义是 at-least-once,崩溃时正在执行的 step 会重跑 | 副作用幂等:去重键、upsert、外发消息带 id |
| 10 | 人机协同里"扣款"执行了两次 | 用了 wait_for_event,它会重放 wait 之前的代码 | 改用两个 step 的事件式写法,或把副作用挪到 wait 之后 |
| 11 | 两个包混用,行为对不上文档 | llama_index.core.workflow 是核心包内置的旧版 | 统一 from workflows import ...,并在依赖里锁版本 |
| 12 | 多副本下轮询结果永远 404 | handler 在另一个进程里 | 持久化 Context,或用 WorkflowServer + 外部 store |
| 13 | 在同步代码里调 w.run() 报 RuntimeError: no running event loop |
run() 内部同步 执行 asyncio.create_task,必须已有运行中的循环 |
放进 async def main() 里再 asyncio.run(main());或改用 asyncio.get_event_loop().run_until_complete 之类的显式循环 |
|---|---|---|---|
| [表 14:坑点总表] |
16 · Hard Problems
六个高难问题:文档不会直接告诉你的
① 拓扑隐式,静态检查帮不上忙
事件驱动的代价就是"图不在代码里"。一个跑了半年的项目,step 可能有三十个,事件类型五十个,谁也说不清删掉某个事件会影响谁。可行的工程化手段只有两条:把 draw_all_possible_flows() 的输出纳入 CI 产物做人工 diff,以及用测试锁住关键路径 ------每个分支至少一个端到端用例,断言最终 StopEvent 的形状。
② 死路是静默的
坑 1 说明了最危险的一类失败:事件没人接,不报错,只是等到超时。默认 45 秒在开发时像"卡了",在生产里就是一次白等的资源占用。建议把 timeout 显式写出来(多数业务 45 秒偏短),并在 WorkflowFailedEvent / WorkflowTimedOutEvent 上挂告警。
③ 并发的两层限制容易配错
num_workers 管单次 run 内某 step 的副本数,num_concurrent_runs 管进程内活跃 run 数,两者相乘 才是对下游的最大压力。只配一个,另一个仍是默认的"不限",压力测试时很容易打穿第三方接口。跨 run 的总量控制要自己加 Semaphore。
④ 长流程与超时的矛盾
带人工审批、带长任务(比如跑一次爬虫)的流程,和 timeout 天然冲突。要么把 timeout 设成 None 并用业务层 TTL 兜底,要么把它拆成"两段 workflow + 中间持久化"。前者简单但失去兜底,后者复杂但要可靠------这个取舍必须在设计阶段做,不能上线后再改。
⑤ 恢复语义决定的架构约束
at-least-once 意味着"每个 step 都必须能安全重跑"。这条约束会反向影响你的业务设计:外发消息要能去重、写库要幂等、第三方调用要带幂等键。很多团队是在第一次生产事故后才发现这一点,然后回头改十几个 step。
⑥ 何时不该用 Workflows
三种情况建议换方案:需要强审计、可回放 的合规流程(图的显式性更值钱,选 LangGraph);需要大量数据管道 与重试语义(用任务队列,不必套 Agent 框架);流程其实只有三步且永不变(一个 async def 就够)。Workflows 的甜区是"步骤多、分支多、需要流式与人机、但结构相对稳定"的中等复杂度代理流程。
四条判据,快速判断该不该上手
- 控制流能否用"事件 → step"自然表达?能,就合适。
- 是否需要边跑边给用户看进度?需要,
stream_events很省事。 - 是否有人工审批环节?有,用两个 step 的事件式写法。
- 是否要求崩溃后精确续跑?要求高,就先想清楚快照与幂等,再决定用不用 DBOS。
说明:第 3、4、5、6、7、9 节的代码与输出在本机实测(Windows + Python 3.10.7 + llama-index-workflows 2.26.1,未安装 llama-index-core、未接任何 LLM)。已验证的 API 形状包括:Workflow.__init__ 的 timeout=45.0 与 num_concurrent_runs、ctx.store.get/set、ctx.send_event、ctx.collect_events、ctx.to_dict / Context.from_dict、retry_policy 组合式策略、Resource 注入;同时确认 ctx.get/set 与 Workflow.draw 不存在。坑 1、3、4、13 与第 5 节的反射循环均为实测复现。第 10、11、13、14 节涉及 WorkflowServer、DBOS、OTel 与 AgentWorkflow 的部分来自官方文档,未在本机运行。