Agent框架选型

Agent 写到后面，最先变长的往往不是模型调用，而是围着循环转的那一圈胶水：状态怎么存、分支怎么走、失败怎么重试、运行到一半怎么接着跑、工具结果怎么回放。手写脚本能做，只是工具多了以后，代码会越来越长，改一处漏一处的风险也在涨。

08 里那个待办循环已经能看出形状了：模型判断、Python 执行、历史记录回填、循环继续。框架不是把这个形状改掉，而是把它拆成现成的组件，省掉一部分重复写法。

一、先分层

Agent 相关的“框架”不全是一类东西。它们常见的分工大致是这样：

• 原始 SDK：管一次请求、一次工具调用、一次回填。
• 流程框架：管状态、分支、节点、重试、检查点。
• 检索框架：管资料接入、切片、索引、查询、召回。
• 结构框架：管 Pydantic 模型、依赖、输入输出字段。

这个分层一旦分开，看名字就不会太乱。OpenAI SDK 不是 LangGraph，LlamaIndex 也不是 PydanticAI。它们有些能一起用，有些只是负责不同位置的胶水。

二、原始 SDK

最底层还是直接调 SDK。像 05、07 里那样，responses.create()、function_call、function_call_output、response.output_text 这些对象都能直接看到。

这种写法最直白。流程短的时候，状态都摆在脚本里，哪一步出问题一眼能看出来。刚写完的待办 Agent 就属于这一类：一轮一轮跑，循环、历史记录、工具分发、停止条件都在同一个文件里。

SDK 的短板也很明显。循环一长，input_items、trace、max_steps、工具白名单这些东西就会开始散；一旦再加分支、回退、断点保存，脚本就会越来越像一个小框架。

所以 SDK 更像地基。它不负责把事情包装得很漂亮，只负责把最原始的调用和回填先接通。

三、LangGraph

LangGraph 这类框架更像流程图。它关心的不是“怎么发一条请求”，而是“这一步之后该走哪条线”“这个状态该怎么往下传”“某个节点失败后回到哪里”。

对 Agent 来说，这一点很实用。比如日志分析助手常见的路径不是单线的：有时先读日志，有时先查 Runbook，有时先问用户补时间范围，有时还要回到前一步重新取证。手写 while 循环也能做这些事，但分支多了以后，代码会越来越绕。

LangGraph 的好处，是把这些分支显式放出来。节点、边、状态、检查点都能单独看。后面要接断点恢复、人工介入、失败重试，改起来也比较顺。

它更适合这种场景：

• 一条问题会走好几个分支。
• 中间步骤要保留状态。
• 跑到一半可能停下，过会儿还能接着跑。
• 不同节点之间需要很清楚地看见输入和输出。

如果只是一个待办清单循环，LangGraph 反而显得重。那种情况直接写脚本更顺手。

四、LlamaIndex

LlamaIndex 更偏资料接入和检索。它最擅长的不是“把 Agent 循环包起来”，而是把各种资料接进来：文档、网页、数据库、向量索引、查询器，再把这些东西串成可问答的入口。

这和 07 里的 RAG 很像，只是工具更多，接法更完整。资料切片、索引、检索、召回、重排、查询接口这些东西，LlamaIndex 都能包一层。Agent 在这里更像上面的一层：模型根据问题决定查哪类资料，再把结果整合出来。

如果系统的核心是“资料多、入口多、检索多”，LlamaIndex 会比较顺。比如知识库问答、文档助手、内部资料查询这类场景，很多时候重点不在循环写得多漂亮，而在资料接得够不够顺。

它不太像一个“只管 Agent 的框架”，更像“把知识库和检索这块先整理好”。Agent 只是其中一个入口。

五、PydanticAI

PydanticAI 的味道和普通 Python 项目更近。它把 Pydantic 模型、依赖注入、结构化输出、工具调用这些东西绑得比较紧，写起来会比较像在维护一个普通应用，而不是在搭一套很大的编排系统。

如果前面已经在用 Pydantic、FastAPI、数据校验这一套，PydanticAI 会顺一些。模型输出、工具参数、依赖对象都能用类型和 schema 说清楚，少写一堆手动解析。

它比较适合这种情况：

• 输入输出字段本来就很规整。
• 代码里已经大量使用 Pydantic。
• 需要把模型输出直接接到 Python 对象上。
• 关心的是“这个字段是什么类型”，而不只是“模型说了什么”。

它给人的感觉没那么“流程图”，更像把普通 Python 应用里那套对象和校验继续往 Agent 里推了一点。

六、Haystack

Haystack 更偏搜索和问答管线。它把检索、排序、生成这些步骤拆成组件，再按管线连起来。和单纯的 Agent 框架比，它更像“资料问答系统”的骨架。

如果资料检索是主角，Haystack 会很顺手。比如文档搜索、语义检索、召回、重排、生成这些步骤，常常不是一个大循环能说清楚的，而是一串固定管线。Haystack 就是把这串管线摆清楚。

它和 LlamaIndex 有点像，但气质不太一样。LlamaIndex 更像围着“资料怎么接进来”转，Haystack 更像围着“这条检索链怎么跑”转。真到落地时，两边都会碰到检索、切片、重排这些词，只是入口和组织方式不一样。

七、怎么挑

如果只是把 08 里的待办循环跑通，原始 SDK 已经够了。那种代码虽然朴素，但路径最清楚。

如果问题会分叉、会回退、会重试、会断点续跑，流程框架更顺，比如 LangGraph。

如果核心工作是接资料、建索引、做检索，LlamaIndex 和 Haystack 会更贴近问题本身。

如果项目里本来就围着 Pydantic、FastAPI、结构化输出打转，PydanticAI 会更像顺手接上去。

实际写的时候，经常不是一套框架包到底。底层调用还在 SDK，上面一层可能接检索库，再上面才是流程控制。框架不是越多越好，关键是看它把哪一层重复代码收走了。

一个小判断比较管用：如果脚本里最烦的那一部分是“状态和分支”，看流程框架；如果最烦的是“资料接入和检索”，看 LlamaIndex 或 Haystack；如果最烦的是“输入输出字段和校验”，看 PydanticAI；如果还没烦到要换框架，直接写脚本也没什么问题。