9.6.2 Agent 框架全景

本节定位

到了 Agent 阶段，很多人很快就会掉进另一个坑：

“框架太多了，到底该学哪个？”

这节课不是为了站队，也不是为了背框架名字，而是为了先建立一张判断地图：

不同框架到底在帮你抽象什么、放弃什么、适合什么。

学习目标

• 理解为什么 Agent 项目常常会引入框架
• 分清不同框架在抽象层级上的差异
• 知道框架通常在替你省什么、又让你失去什么
• 建立初步的框架选型视角

读这张图时可以把它看成取舍图：越底层的框架控制力越强，越高层的框架启动成本越低，偏检索的框架更适合以文档和知识为中心的系统。

---

为什么需要 Agent 框架？

没有框架时，自己写会遇到什么？

一个稍微复杂一点的 Agent 系统，通常要自己处理：

• 状态管理
• 工具调用
• 消息流转
• 失败重试
• 追踪
• 多 Agent 协作

你当然可以手写，但很快会遇到：

• 重复样板代码很多
• 每个项目结构都不一致
• 调试和扩展越来越难

框架真正解决什么？

可以先用一句话记住：

框架不是替你做产品，而是在帮你把高频结构先搭好。

例如：

• 图结构状态流
• 工具注册机制
• Agent 间协作抽象
• 运行与观测接口

---

框架最大的差别通常不在“能不能做”，而在“怎么做”

一个很重要的视角：抽象层

很多框架都能：

• 接工具
• 跑工作流
• 做多 Agent

但它们抽象的层级不同：

• 有的更接近“底层搭积木”
• 有的更接近“高层角色编排”
• 有的更偏检索与数据组织

一个类比

你可以把不同框架想成不同类型的厨房：

• 有的给你锅碗瓢盆，自己做菜
• 有的给你半成品套餐，按说明组合
• 有的专门擅长某类菜

所以框架差别很多时候不是“谁更强”，而是：

谁更适合你现在的任务和团队习惯。

---

先看一张粗粒度地图

下面这张图不是精确排名，而是帮助你快速建立直觉：

框架方向	更擅长什么	常见感觉
图/工作流型	复杂状态流、明确控制	灵活但更工程化
检索/知识型	文档、索引、RAG	数据导向更强
角色/团队型	多 Agent 角色协作	上手快但抽象更高
通用实验型	快速搭演示	灵活但需要自己补工程层

这张图最重要的作用是：

先不要问“哪个最好”，先问“我的问题更像哪一类”。

---

框架一般帮你省掉哪些工作？

状态流和节点管理

例如：

• 当前任务状态放哪
• 下一步流向哪里
• 出错如何回退

工具接入和消息结构

例如：

• 工具注册
• 调用结果包装
• 错误处理

运行和观察

例如：

• 追踪
• 步骤 记录
• 中间状态可视化

所以框架最常见的价值并不是“模型更聪明”，而是：

系统组织得更清楚。

---

框架也会带来代价

抽象越高，越容易失去底层控制

框架帮你省事，但也会带来：

• 学习框架本身的成本
• 框架约束
• 调试时必须理解它的内部抽象

一个很常见的问题

很多新人不是不会做 Agent，而是：

• 还没把任务想清楚
• 就先学了很多框架接口

结果最后学到的是框架用法，不是 Agent 本质。

所以正确顺序通常是：

先懂系统，再借框架提速。

---

一个最小“框架感”示例

下面这个例子不是某个真实框架，而是一个“框架抽象味道”的极小示例。

class MiniWorkflow:
    def __init__(self):
        self.steps = []

    def add_step(self, name, fn):
        self.steps.append((name, fn))

    def run(self, state):
        for name, fn in self.steps:
            state = fn(state)
            print(name, "->", state)
        return state

def retrieve(state):
    state["docs"] = ["退款政策"]
    return state

def answer(state):
    state["answer"] = f"根据 {state['docs']} 生成回答"
    return state

wf = MiniWorkflow()
wf.add_step("retrieve", retrieve)
wf.add_step("answer", answer)

wf.run({"query": "退款政策是什么"})

预期输出：

retrieve -> {'query': '退款政策是什么', 'docs': ['退款政策']}
answer -> {'query': '退款政策是什么', 'docs': ['退款政策'], 'answer': "根据 ['退款政策'] 生成回答"}

这段代码为什么有“框架感”？

因为它已经在抽象：

• 步骤
• state
• 流程组织

真实框架无非是在这条路上做得更完整、更复杂。

---

什么时候更适合不用框架？

如果你的系统是：

• 小实验
• 单 Agent
• 工具不多
• 状态流很简单

那手写未必更差。

很多时候：

• 手写更容易理解本质
• 框架反而会增加抽象负担

所以不要把“上框架”当成成熟的唯一标志。

---

一个很实用的选型思路

先问这几个问题：

1. 我的系统复杂度高不高？
2. 状态流是不是明显复杂？
3. 多 Agent 协作是不是核心？
4. 检索 / 文档能力是不是主线？
5. 团队更想要底层控制，还是更快起步？

如果这些问题你答得出来，再看框架，判断会清楚很多。

---

初学者最常踩的坑

先学框架，再学系统

这样最容易“会调用 API，但不会做架构判断”。

因为框架火就直接选

框架流行不代表适合你当前项目。

把框架当能力本身

框架只是组织方式，不是系统质量保证。

---

留下的证据

学完这一页，至少保留这张证据卡：

问题形态

工作流图、检索应用、角色团队或实验

框架选择

它增加了什么抽象，以及隐藏了什么控制

追踪记录

状态、节点、tool 调用、消息或运行 id

失败检查

框架魔法隐藏状态、重试或权限问题

决策

只有在单代理循环清晰后才选择框架

小结

这一节最重要的不是记住一串框架名字，而是理解：

Agent 框架的本质，是把高频的状态流、工具流和协作结构先抽象出来，帮助你更快组织系统。

理解了这一点，后面你再看具体框架，就会更像在比较“组织方式”，而不是在追热点。

---

练习

1. 用自己的项目场景，判断它更适合“图/工作流型”还是“角色协作型”框架。
2. 想一想：为什么说复杂度不高的项目，手写反而可能更好？
3. 用自己的话解释：框架真正替你省掉的工作是什么？
4. 如果你团队特别看重可控性，你会更倾向选择什么风格的框架？

项目交付参考与讲解

1. 如果难点是状态、分支、重试和可观测性，更适合 graph/workflow 取向；如果难点是把工作拆给不同专业角色并审核结果，更适合 role-collaboration 取向。
2. 低复杂度项目手写代码可能更好，因为抽象更少、隐藏默认行为更少、调试路径更短。
3. 框架真正节省的是重复工程：消息传递、状态容器、tool 绑定、trace、重试、memory hook 和常见工作流模式。它不会替你理解系统设计。
4. 如果团队最重视可控性，应优先选择显式 workflow / graph 风格框架，甚至小型手写编排层，因为状态转移和失败路径更容易检查。