全书目录

第九编 框架层

第 48 章 LlamaIndex：从数据框架走向 Agent Workflow

14 分钟 6,232 字 第 49 / 161 个阅读单元

如果说前面几个框架大多从“控制流”或“运行时”进入 Agent，那么 LlamaIndex 代表的是一条非常不同的路线。

它最初并不是先问：

text
Agent 应该怎么调度？

而是先问：

text
模型怎样才能稳定地接近外部数据世界？

这两种出发点会带来完全不同的框架气质。

因此，第 48 章第一条结论应该是：

text
LlamaIndex 首先是数据框架，
然后才在这个数据框架之上长出了 Agent 和 Workflow。

这句话如果不先立住，后面几乎所有比较都会偏。

因为 LlamaIndex 真正的第一性对象长期都不是图，也不是多 Agent runtime，而是：

  • Reader
  • Document
  • Node
  • Index
  • Retriever
  • QueryEngine
  • Response Synthesizer
  • Tool

只有在这些对象之上，才继续长出：

  • FunctionAgent
  • ReActAgent
  • CodeActAgent
  • AgentWorkflow
  • Workflow

所以，理解它的关键不是把它当成“又一个 Agent 框架”，而是先承认：

text
它是从“数据如何被模型可靠使用”这个问题出发，逐步长成 agent system 的。

#48.1 它真正解决的，不是“控制流先行”，而是“数据中间层先行”

很多框架做 Agent，是先发明一个执行内核，再让数据能力挂载上去。

LlamaIndex 恰好相反。

它长期在回答的问题是：

  • 外部资料怎么读进来
  • 原始文档怎么切成 node
  • 节点之间怎么保留 metadata 和关系
  • 如何建立 index
  • 如何做 retrieval
  • 如何把 retrieval 结果合成为回答

这意味着它最先建的不是“Agent 的骨架”，而是“知识进入模型的中间层”。

这也是为什么它在 README 和框架文档中长期强调：

  • data connectors
  • data structures
  • retrieval/query interface
  • integrations

所以，本章最重要的第一个系统判断是：

text
LlamaIndex 的根问题不是 agent 如何思考，
而是模型如何借助稳定的数据对象、检索对象和查询对象来接近世界。

一旦把这一点看清，你就不会再用纯 runtime 框架的眼光去要求它。

#48.2 对象模型：为什么 Reader → Document → Node → Index → Retriever → QueryEngine → Tool 才是主链

如果要用本书第 41 章的方法找“框架真正的中心对象”，LlamaIndex 最该看的不是 FunctionAgent，而是它的数据主链。

这条链可以压缩成七步：

  1. Reader
  2. Document
  3. Node
  4. Index
  5. Retriever
  6. QueryEngine
  7. Tool

这七步其实把它的世界观完整写出来了。

Reader 负责连接现实数据源。

Document 负责把外部材料变成统一输入对象。

Node 则是它非常关键的一层。文档明确说，from_documents 时会把 document 切分成 node，node 是保留文本、metadata 和关系的轻量抽象。

这意味着：

text
LlamaIndex 并不鼓励 agent 直接面对一坨原始文本，
而是先把知识压成可检索、可引用、可组合的节点对象。

然后 Index 负责组织这些节点。

Retriever 负责在查询时找回最相关的上下文。

QueryEngine 负责把“检索到什么”和“如何回答”串起来。

最后 Tool 才把这些查询能力暴露给 agent。

这里最重要的一点是：

text
在 LlamaIndex 里，tool 往往不是和数据层并列的第一对象，
而是数据能力被包装给 agent 的出口。

QueryEngineTool 的源码就非常直白：

  • 持有 BaseQueryEngine
  • 接收自然语言输入
  • 调用 query() / aquery()
  • 返回 ToolOutput

所以你可以把它理解成：

text
先有数据查询能力，
再有 agent 可调用工具。

这与很多一开始就围绕 tool calling 组织世界的框架非常不同。

#48.3 生命周期：它的主语不是“先跑 agent”，而是“先建知识链，再跑 agent”

LlamaIndex 的典型生命周期不是：

  1. 定义 agent
  2. 定义工具
  3. 让 agent 自己解决一切

而更像：

  1. 通过 reader 读入数据
  2. 转成 document / node
  3. 建 index
  4. 生成 retriever
  5. 生成 query engine
  6. 把 query engine 或相关函数封成 tool
  7. 让 agent / workflow 来协调这些工具

这就是为什么它的 starter tutorial 都明显呈现出这种路径：

  • 先做一个最简单的工具 agent
  • 再把 VectorStoreIndex 和 query_engine 接进来
  • 然后让 agent 拥有 RAG 能力

从系统设计角度看，这条路径非常值得重视。

因为它说明：

text
LlamaIndex 的 agent 不是为了替代数据层，
而是为了调度已经建好的数据能力。

这也是为什么很多人在 LlamaIndex 上做 agentic RAG 会比较顺手。

因为它不是让你先假装“agent 已经很聪明”，而是先把知识接入、组织、检索与合成做好，再把 agent 放到最上面作为协调层。

#48.4 Agent 层：为什么 BaseWorkflowAgent 本质上仍然是 Workflow

虽然 LlamaIndex 不是从 agent 内核起家，但它后来的 agent 抽象并不弱。

最值得注意的一点，是源码直接把 BaseWorkflowAgent 定义成：

  • Workflow
  • BaseModel
  • PromptMixin

三者的结合体。

这意味着它的 agent 不是一个孤立人格对象，而是：

text
一个带配置、带 prompt、但本质上运行在 workflow 基础设施之上的执行单元。

这非常关键。

因为它说明 LlamaIndex 后来长出来的 agent，不是和 workflow 平行的一套世界，而是建立在 workflow 机制上的高层封装。

具体到对象上：

  • FunctionAgent 依赖模型的 function/tool calling
  • ReActAgent 依赖 reasoning prompt
  • CodeActAgent 依赖代码行动式模式

但无论是哪一种，底下都还是 workflow 化的运行结构。

所以，第 48 章第二条结论应该是：

text
LlamaIndex 的 prebuilt agent 不是独立 runtime，
而是构建在 workflow 基础设施之上的高层 agent 形态。

这也是它和纯 agent-only SDK 的一个明显区别。

#48.5 AgentWorkflow：为什么它不是纯多 Agent 框架，而是“workflow 化的多 Agent 协调器”

AgentWorkflow 更能说明这一点。

从源码看，它持有：

  • agents
  • root_agent
  • initial_state
  • handoff_prompt
  • handoff_output_prompt
  • state_prompt
  • output_cls

并在 ctx.store 中维护：

  • memory
  • agents
  • can_handoff_to
  • state
  • current_agent_name
  • next_agent
  • max_iterations
  • num_iterations

这里最重要的不是字段多少，而是它们透露出的系统语义。

AgentWorkflow 的多 Agent 协调，不是消息总线式 runtime，也不是静态图编排。 它更像：

text
一个建立在 workflow 上的、带 handoff 语义和共享状态的多 Agent 协调器。

源码里 handoff 甚至被直接做成工具：

  • agent 决定 handoff
  • handoff 工具设置 next_agent
  • workflow 在后续步骤中切换 current_agent_name

这说明它的多 Agent 不是独立 Actor 地址空间模型，而是共享上下文中的控制权切换。

所以和 AutoGen 比，LlamaIndex 的多 Agent 更偏：

  • workflow 内协调
  • handoff 约束
  • 共享 state / memory

而不是：

  • 完整消息 runtime
  • actor identity
  • 通用分布式 agent 通信

#48.6 状态与记忆：Context、ctx.store、Memory 是它 agent 系统真正的状态基座

如果要找 LlamaIndex agent 系统里最关键的状态对象，不是单独的 chat history，而是：

  • Context
  • ctx.store
  • memory

官方文档明确写到：

  • AgentWorkflow 默认在 runs 之间是无状态的
  • 想跨运行保留状态，需要保留 Context
  • Context 可序列化，可保存再恢复

这件事很重要。

因为它说明 LlamaIndex 没有把“会话连续性”做成某个魔法默认值，而是明确要求你管理上下文对象。

同时，agent 文档与源码也都显示：

  • initial_state 进入 ctx.store["state"]
  • tool 可以直接访问 Context
  • ctx.store.edit_state() 允许工具修改共享状态

这意味着它的状态模型并不是“纯 prompt 拼接”，而是显式上下文存储。

再看 memory 层，就更能看到它的数据系统气质。

当前文档说明：

  • 默认仍常用 ChatMemoryBuffer
  • 但长期方向转向更通用的 Memory

而 Memory 又支持：

  • session_id
  • short-term memory
  • memory blocks
  • fact extraction
  • vector-based memory
  • remote DB / SQLite persistence

这说明在 LlamaIndex 里，记忆不是单纯的聊天缓存，而是已经被做成和检索体系相衔接的结构化组件。

因此，本章第三条结论应该是：

text
LlamaIndex 的 agent 状态不是靠“长上下文硬塞”维持的，
而是靠 Context、显式 state 与可配置 memory 系统共同支撑的。

#48.7 工具与 RAG 的结合：它为什么特别擅长把“数据能力”变成 agent 能力

LlamaIndex 最强的地方，不在于它先发明了多新奇的 agent loop，而在于它特别擅长把数据能力转成 agent 能力。

最典型的桥梁就是：

  • QueryEngineTool
  • tool_retriever
  • object retrieval

文档明确说：

  • FunctionTool 可以包装普通函数
  • QueryEngineTool 可以包装 query engine
  • agent 的 tool_retriever 可以动态取回工具

甚至在索引层文档中，VectorStoreIndex 还能检索：

  • nodes
  • query engines
  • retrievers
  • query pipelines

这件事非常值得注意。

因为这意味着 LlamaIndex 并不是把“知识”只理解成回答上下文。

它还允许：

text
把知识访问能力本身对象化，并进一步被检索、被组合、被包装成 tool。

这也是它在 agentic RAG 上非常有代表性的原因。

很多所谓 agentic RAG 项目，真正困难的其实不是 agent 推理，而是：

  • 数据入口不稳定
  • chunking 不稳定
  • 检索不稳定
  • query engine 没有业务语义
  • tool 暴露层太薄弱

LlamaIndex 的优势恰恰就集中在这些中间层。

#48.8 治理、结构化输出、HITL 与观测：它的控制面建立在 Workflow 和 Instrumentation 上

虽然 LlamaIndex 不是先从治理起家，但它的控制面也并不弱。

这一层主要体现在四个方面。

第一，结构化输出。

无论在 agent 还是 query 层，文档与源码都明确保留：

  • output_cls
  • structured_output_fn

这说明它并不满足于“生成一段文本”，而是鼓励把输出压成程序可消费的结构。

第二，人审与 HITL。

官方的 human-in-the-loop 文档直接建立在 workflow 事件之上：

  • InputRequiredEvent
  • HumanResponseEvent
  • wait_for_event
  • send_event

这意味着它的人审能力不是简单的“暂停一下”，而是借助 workflow 事件机制把等待与恢复做显式化。

第三，流式事件。

WorkflowHandler、stream_events() 等能力说明，它非常重视执行过程被外部系统实时感知。

第四，instrumentation。

官方明确把新的 instrumentation 模块当成 callbacks 的替代者，并把：

  • event
  • span
  • handler
  • dispatcher

做成统一观测语言。

所以从治理视角看，LlamaIndex 的风格不是“先造一个专门 agent observability 产品”，而是：

text
把治理、HITL、结构化输出与观测，建立在更通用的 workflow 与 instrumentation 基础设施上。

#48.9 业务适配：它为什么特别适合知识密集型 Agent 系统

从业务适配角度看，LlamaIndex 最适合的问题，有一个鲜明共性：

text
真正的难点不在“角色数量”，而在“知识如何被正确接入、检索、组合并再被 agent 调度”。

这类场景包括：

  • 企业知识库助理
  • 文档问答与多文档分析
  • 报告生成
  • 法务、金融、医疗等知识密集型检索系统
  • agentic RAG
  • 文档驱动的多步骤自动化

在这些问题里，很多失败项目表面上看是 agent 不聪明，实际上失败在：

  • 文档没切好
  • node 设计不对
  • metadata 设计不对
  • retriever 设计不对
  • query engine 没有按业务语义封装
  • tool 描述和职责不清

而 LlamaIndex 恰恰最擅长处理这些前置层。

所以，它的业务适配优势不是“会聊天”，而是：

text
它能把知识系统、检索系统和 agent 系统压成一条连续工程链。

#48.10 最常见的误用：把它当成纯 orchestration 框架，或者跳过数据中间层

LlamaIndex 最常见的误用，也几乎都来自忘了它的数据出身。

第一，把它当成纯控制流框架。 一上来就写复杂 agent workflow，却不先设计：

  • document
  • node
  • index
  • retriever
  • query engine

这样等于直接绕过了它最强的半壁江山。

第二，把原始文本直接扔给 agent。 这会跳过 node、metadata、检索和合成策略，最后把问题重新退化成“上下文越塞越多”。

第三，误以为 AgentWorkflow 默认等于生产级 durable runtime。 实际上它的连续性依赖 Context 和 memory 管理，而不是像某些图 runtime 一样默认就把恢复语义做到最底层。

第四，把它看成纯聊天 agent 框架。 这会让团队忽略：

  • QueryEngineTool
  • composable retrieval
  • ingestion pipeline
  • memory blocks
  • instrumentation

这些真正建立系统稳定性的中间层。

第五，把工具理解成孤立函数，而不是知识能力接口。 在 LlamaIndex 里，很多高价值工具本质上是 query engine 或 retrieval 能力的封装，而不只是随手写的 function。

#48.11 它和 LangGraph、CrewAI 的本质分界

把 LlamaIndex 放回第九编，分界就很清楚了。

和 LangGraph 相比：

  • LangGraph 的第一性对象是图与运行时
  • LlamaIndex 的第一性对象是数据与检索链

和 CrewAI 相比：

  • CrewAI 的第一性对象是角色、任务与流程语言
  • LlamaIndex 的第一性对象是知识接入、查询与工具化

和 OpenAI Agents SDK 相比：

  • OpenAI Agents SDK 更偏 run-centered runtime objects
  • LlamaIndex 更偏 data-centered agent composition

所以，更准确的说法不是“它是不是 Agent 框架”，而是：

text
它是一套以数据中间层为核心、再向 agent workflow 生长的 agent framework。

#48.12 本章结论

本章最后要留下的判断是：

text
理解 LlamaIndex 的关键，不是先把它当成“又一个 Agent 框架”，
而是先承认：它把 Reader、Node、Index、Retriever、QueryEngine、Tool 这条知识链做深之后，
才进一步长出了 Workflow、Agent 和多 Agent 协调能力。