LlamaIndex Workflows 学习

Workflows 把编排还原成普通 async Python :一个 step 收到某类事件、干活、再发出另一类事件,控制流由类型注解隐式连成,没有节点表也没有边表。代价是拓扑不在一个地方,得靠画图工具才能看见。本文按「事件 → step → 状态 → 并发 → 流式 → 重试 → 人机 → 持久化 → 上线」的顺序讲透,并附上在本机真跑出来的两个反直觉结果。

实测于 2026-11-21llama-index-workflows 2.26.1Python 3.10.716 节 · 14 表 · 14 段代码 · 13 个坑

Contents

  1. 定位与版本
  2. 三种编排范式对比
  3. 最小可运行流程
  4. 事件体系
  5. 注解驱动的拓扑
  6. [Context 与状态](#Context 与状态)
  7. 并发、扇出与扇入
  8. 流式输出
  9. 重试与超时
  10. 人机协同
  11. 持久化与断点
  12. 资源注入
  13. 可观测性与服务化
  14. AgentWorkflow
  15. 十三个坑
  16. 高难问题

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 的部分来自官方文档,未在本机运行。

相关推荐
鲸渔1 小时前
【AI Agent系列课程13-Python 基础13】JSON 读写:结构化数据交换基础
开发语言·python·json·ai编程
wuyk55511 小时前
Python办公自动化-第01讲-环境搭建与自动化认知
python·自动化·pyqt
高洁0112 小时前
数字孪生与计算机视觉:让机器看懂现场
人工智能·python·机器学习·transformer·迁移学习
ComPDFKit12 小时前
RAG 回答只显示 PDF 文件名?用 Python 保留引用页码
开发语言·python·pdf·rag
yz_aiks13 小时前
Termux 使用教程:把安卓手机变成随身 Linux(装 Python、SSH 远程、跑自动化脚本)
android·linux·python·智能手机·ssh·termux
FengY_HYY15 小时前
从人类组织到人类&大模型组织,我的位置在哪里?
人工智能·程序员·llm
2601_9679801115 小时前
Flask Web 应用
python·flask·web开发·环境变量·虚拟环境
aifannihao15 小时前
ß 大写变 SS:用 Python 算清 Ruby2Shell 的缓冲区账本
python·安全·标准库·缓冲区溢出·字符串编码
liwulin050616 小时前
【OLLAMA】调用SKILL的通用ReAct
python