#Workflows 工作流

LlamaIndex Workflows 是 事件驱动、以 step 为单位 的编排：每一步接收某种 Event，做完工作后 return 另一个 Event，运行时根据类型注解把事件送给下一个 @step。循环就是「某步返回更早一步能处理的事件」；分支就是普通 if 返回不同事件类型。官方认为这比把循环/分支画进 DAG 边更接近普通 Python。

权威概念页：Workflows 介绍 · API：Workflows API。签名若与下文不一致，以这两页为准，不要靠记忆硬凑参数。

安装了 llama-index / llama-index-core 时，稳定导入路径是 llama_index.core.workflow。也可 pip install llama-index-workflows 后使用独立包 workflows（官方新文档示例有时从 workflows 直接 import）。FunctionAgent 本身也建立在 Workflow 运行时上，所以 快速上手 里的 Context 与这里是同一套状态对象。

#心智模型

flowchart LR
  S[StartEvent] --> A["@step 生成"]
  A --> E[自定义 Event]
  E --> B["@step 处理"]
  B --> X[StopEvent]

框架提供两种特殊事件：

• StartEvent：workflow.run(...) 的关键字参数会填进起始事件（如 topic= → ev.topic）
• StopEvent：某步返回它时工作流结束，result 就是 await w.run(...) 的返回值

自定义事件是带字段的 Pydantic 对象。@step 的参数与返回类型会在运行前做图校验：有消费者无生产者、没有 StopEvent 等，多数能在启动时发现。

#最小形状（官方 JokeFlow 思路）

下面按官方介绍页的「生成 → 再处理 → 停止」改写，LLM 用 gpt-4o-mini。若你安装的包要求 from workflows import Workflow, step，按官方页改 import 即可，不要混用两套未文档化的类名。

from llama_index.core.workflow import (
    Workflow,
    step,
    Event,
    StartEvent,
    StopEvent,
)
from llama_index.llms.openai import OpenAI

class JokeEvent(Event):
    joke: str

class JokeFlow(Workflow):
    llm = OpenAI(model="gpt-4o-mini")

    @step
    async def generate_joke(self, ev: StartEvent) -> JokeEvent:
        prompt = f"Write your best joke about {ev.topic}."
        response = await self.llm.acomplete(prompt)
        return JokeEvent(joke=str(response))

    @step
    async def critique_joke(self, ev: JokeEvent) -> StopEvent:
        prompt = f"Critique this joke:\n{ev.joke}"
        response = await self.llm.acomplete(prompt)
        return StopEvent(result=str(response))

async def main():
    w = JokeFlow(timeout=60, verbose=False)
    print(await w.run(topic="pirates"))

流式中间事件时保留 handler：handler = w.run(...)，async for ev in handler.stream_events()，最后 await handler。

#和查询流水线怎么接

RAG 在 Workflow 里通常是：StartEvent → 检索步（自定义 Retrieved 事件）→ 合成步 → StopEvent。检索步里调用已有 retriever.aretrieve 或 query_engine.aquery，把文本放进事件字段。官方示例笔记本包括 RAG + rerank、Corrective RAG、引用引擎等，完整参数见文档「Examples」列表，本课不复制可能过期的类名。

需要共享状态、人机输入、并发扇出时，查阅官方表格：ctx.store、ctx.send_event、list[Event] 返回值等——这些属于进阶 Context API，用错会绕过类型图校验。

#对比 LangGraph / CrewAI

固定「检索 → 生成」用 QueryEngine 就够。出现 循环质检、分支路由、并行子查询 再上 Workflow。要标准工具 Agent，先 FunctionAgent；要跨框架编排再接到 LangGraph 或 CrewAI。

#下一步

• 向量库集成
• 实战案例
• 官方：Workflows 介绍