Agent 框架选型：裸 SDK 自搭 vs 开箱框架，别选错了

做 Agent 到底自己搭还是用现成框架？这个问题比看起来更值得认真想——选错方向，要么你三周后在重复造轮子，要么你被框架的约定绑住，想加个特殊逻辑全是改库的活。

两条路都有人走通，但适合的场景不一样，搞混了才会进坑。

---

两条路各是什么

路线一：裸 SDK 自搭

裸 SDK 指直接用模型官方提供的 SDK，比如 Claude Agent SDK（anthropic Python 包）或 OpenAI Agents SDK，自己写工具列表、消息历史、主循环。

你控制一切：工具怎么定义、循环什么时候停、出错了怎么处理，全是你的代码。没有额外的约定，也没有框架帮你做的"隐藏逻辑"。

骨架大概长这样（已在 2.3 节跑通过）：

while True:
    response = client.messages.create(model=..., tools=tools, messages=messages)
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "tool_use":
        # 你自己执行工具、把结果塞回 messages
        ...

就这些。几十行代码，四要素全齐，这已经是一个真实可用的 Agent 结构。

路线二：开箱框架

开箱框架在裸 SDK 之上加了一层：把常见需求打包进来，让你不用每次从零写。代表性的比如：

• hermes-agent：自带技能加载（Skills）、对话记忆、基本的多工具编排，一条命令启动，约定大于配置。具体能力以官方仓库为准，本文写作时以公开文档为参考，不做超出官方说明的承诺。
• LangGraph：图节点式编排，适合复杂状态机和多 Agent 图，有明确的节点/边/状态概念。
• 其他开源框架（CrewAI、AutoGen 等）：各有侧重，有的面向角色扮演式多 Agent，有的面向代码执行沙箱。

框架的本质：它帮你搭好了骨架，你填入自己的工具和逻辑。骨架是框架定的——你获得了开箱能力，但同时接受了框架的约定。

---

各自适用什么场景

裸 SDK 适合这些情况

学习/理解本质：你想真正搞懂 Agent 的工作原理，而不只是会用一个工具。裸 SDK 代码透明，每一行都对得上 Agent 四要素，出了问题加个 print 就能看到现场。

完全定制的业务逻辑：工具调用顺序很特殊、需要自定义的重试机制、要把 Agent 嵌进现有系统的某个位置——这些在框架里都是"逆着约定干活"，不如自己搭。

轻量单 Agent 任务：任务不复杂，一个 Agent 搞定，不需要记忆持久化、不需要多 Agent 协作，裸 SDK 10 行启动，没有多余依赖。

要集成进自己代码库：你已经有一套服务架构，Agent 是其中一个模块，不是独立运行的。裸 SDK 就是一个 Python 函数，随便嵌。

开箱框架适合这些情况

快速上生产，要现成能力：你不在意学原理，就想让 Agent 跑起来，而且 hermes 这类框架提供的能力（记忆、技能加载）刚好够用——那就直接用，省掉自己写轮子的时间。

已有稳定的 Agent 模式，要复用：你的团队已经跑通了一套 Agent 模式，要在多个项目里复用，框架的约定帮你统一，新人上手也快。

需要可视化调试 / 托管运行：有些框架提供 trace、可视化编排界面，debug 体验比裸 print 好。如果你的 Agent 复杂到需要这些工具，值得引入。

复杂多 Agent 图：任务需要多个 Agent 协作、有条件分支、有并行执行，手写循环管理状态很快就失控。这时候 LangGraph 这类图编排框架的约定是帮你理清逻辑的。见 什么时候上 LangGraph。

---

选型对比表

维度	裸 SDK 自搭	开箱框架（hermes 等）
上手速度	慢一点，要自己搭骨架	快，一条命令启动
骨架控制权	你全控，逻辑透明	框架控制，你填入工具/配置
定制能力	想加什么加什么	受框架约定限制，改深层逻辑要动框架代码
调试可见度	代码透明，print 随便加	依赖框架的 trace/日志，黑盒部分较多
内置能力	零，全自己写	记忆、技能加载、部署等开箱即用
学到什么	Agent 本质结构，触类旁通	学了该框架的约定，换框架重学
维护成本	你的代码，自己负责	框架升级可能带来 breaking change
适合阶段	学习期、深度定制	生产快跑、复用成熟模式

没有哪个绝对好。两条路不是竞争关系，是不同阶段、不同需求的工具——先裸 SDK 跑通本质，再按需引框架，是比较扎实的路径。

---

"子代理优先、框架按需"原则

这个原则回答一个具体问题：任务变复杂了，是加框架还是加子代理？

很多人遇到 Agent 任务变复杂，第一反应是"我是不是要引个框架"。但其实很多时候，一个主 Agent + 几个子代理就能解决问题，不需要动框架。

子代理的逻辑很简单：主 Agent 把一个复杂任务拆开，把子任务作为工具调用委派给子 Agent，子 Agent 在自己独立的上下文里干完，只把结论交回来。这个模式用裸 SDK 完全可以实现，不需要任何框架——一个函数调用另一个函数，主循环还是那个主循环。

什么时候这个原则不够用了：

• 子 Agent 之间有复杂依赖关系（A 完成后 B 和 C 并行，B 完成后 D 等），手写状态管理开始让代码难维护
• 需要 checkpoint/断点续跑，任务执行几小时中间可能断掉
• 需要可视化监控多个 Agent 的执行状态

到了这个程度，框架才是真的帮到你。在这之前，"先加子代理"通常比"先加框架"代价更低、风险更小。

---

什么时候该从裸 SDK 毕业到框架

毕业不是因为"代码行数多了"，而是有几个具体信号：

信号一：你在反复手写同样的轮子

记忆序列化、工具注册、错误重试——这些你已经写了第三遍了。这时候找一个把这些约定打包好的框架，是合理的。

信号二：多 Agent 状态管理失控

你的代码里开始出现大量"Agent A 的结果要传给 B，B 没跑完 C 要等着"的手写逻辑，维护成本超过了收益。

信号三：团队新人上手成本高

你的裸 SDK 代码只有你自己看得懂架构，框架的约定能帮新人快速定位"这个 Agent 的工具在哪、记忆怎么存"。

信号四：需要框架提供的特定能力

比如 hermes-agent 的技能（Skills）加载方式你用得很顺手，不想自己实现这套机制——以官方仓库能力说明为准，确认它真的提供你需要的能力再引入。

毕业时要检查什么：

• 框架最后一次更新是什么时候？是否还在活跃维护？
• 你的业务逻辑有没有和框架约定有明显冲突的地方？
• 引入框架后，你还能写测试覆盖关键路径吗？

如果框架已经很久没更新、或者你发现逻辑要反复绕过框架的约定，宁可继续裸 SDK，别为了用框架而用框架。

如果你想先看看 hermes-agent 这条路长什么样，可以去 hermes-agent 上手一条命令 感受一下开箱框架的约定风格，再对比这篇做决策。

---

常见问题

Q：我已经用裸 SDK 跑通了一个 Agent，现在要迁移到 hermes，要改多少代码？

取决于你的工具定义方式和框架的约定差距。hermes 有自己的工具注册方式（具体以官方仓库为准），如果你的工具是标准的函数+描述结构，迁移成本可控。最好的方式是先跑一个最小的 hermes 示例，感受一下约定，再评估迁移量，不要先迁再发现不合适。

Q：项目上了线才想换框架，会很痛苦吗？

通常会有一段并行期，要同时维护两套逻辑。更好的做法是在迁移前明确"框架给你带来了什么"——如果只是"感觉更专业"，这不是理由；如果是"记忆持久化我自己写了三次，hermes 打包好了这块"，这才是值得迁移的理由。

Q：LangGraph 和 hermes 怎么选？

LangGraph 适合图状多 Agent 编排，有明确的节点/边/状态概念，学习曲线陡，适合复杂状态机。hermes 开箱体验更轻量，适合快速起步的单 Agent 或简单多 Agent 场景。如果你的任务用子代理模式就够，先不用选任何一个。想深入了解 LangGraph 的适用边界，看 什么时候上 LangGraph。

Q：hermes 这类框架会不会停更，投入了白费？

所有框架都有这个风险，这也是"子代理优先、框架按需"原则的原因之一——裸 SDK 的主循环结构是你自己的代码，不会因框架停更而失效。框架引入得越晚、越克制，你对它的依赖就越浅，迁出成本就越低。引入前确认一下仓库的最近提交频率和 issue 活跃度，是基本尽职调查。

---

小结

• 裸 SDK：骨架你定，控制透明，学到本质，适合学习期和深度定制。
• 开箱框架：骨架框架定，开箱能力丰富，适合快速上生产和复用成熟模式。
• 两条路不是对立的，先裸 SDK 跑通本质 → 识别到真实痛点 → 再按需引框架是比较扎实的路径。
• 子代理优先：任务复杂了先加子代理，而不是先加框架——很多情况子代理就够了。
• 毕业到框架的信号：反复手写同样轮子、多 Agent 状态管理失控、团队上手成本高、需要框架特定能力。

接下来可以去 AI Agent 智能体阶梯 看后续节，或者先跑一下 hermes-agent 上手一条命令 感受开箱框架的约定风格，再对比今天这篇做判断。

👉 看看 AI 数字员工落地指南，或了解 数字员工搭建实战课。需要为企业落地方案，欢迎找我们聊 企业服务。