这两年聊开源 Agent 框架绕不开 DSH、Codex、Pi、Hermes 这几个名字。它们被社区放在一起比较的频率非常高但每次看别人讨论都像在打哑谜有人夸 DSH 流程稳有人说 Codex 改代码是真香还有一波人坚持 Pi 的多模态才是未来而 Hermes 则被当作轻量场景的标配。我先把话说在前面下面提到的四个名字可以理解为社区里对四类典型开源 Agent 框架的代称没必要纠结具体对应哪个仓库。这四类方案分别代表了流程编排、代码操作、多模态感知、轻量对话四种主流路线。搞明白自己的场景落到哪一类再去看具体项目选型才不会被带偏。这篇文章不吹不黑只讲我实际用下来看到的优缺点、踩过的坑以及一套可以直接照着做的选型判断方法。如果你正打算给团队引入 Agent 框架或者自己想做个小工具但不知道从哪个框架入手这篇文章应该能帮你省掉几天的调研时间。1. 先想清楚Agent 框架到底解决什么问题很多人一开始选型就犯迷糊是因为把模型和框架混在一起了。Agent 框架不是大模型本身它是在模型外面套的一层调度层负责决定什么时候调用模型、什么时候调用工具、怎么把任务拆成多步、怎么把结果拼回去。可以用开公司的逻辑来类比。模型是员工框架是管理层。员工能力再强如果没有管理层把任务拆清楚、安排好流程、协调好工具最后出来的结果往往是看着聪明、实际干不成事。框架解决的就是怎么让模型真正干完一整件事的问题。具体来说框架至少要承担四件事。第一任务拆解。用户给一句含糊的需求比如帮我把这份数据整理成周报框架要把这个目标拆成读取数据、分析趋势、生成文本、格式化输出几个子任务。第二工具调用。Agent 要能调用外部工具比如搜索、数据库查询、文件读写、执行代码、调用 API。框架需要管好什么时候调、调哪个、参数怎么传、返回结果怎么塞回上下文。第三状态与记忆。多步任务中间会产生大量中间结果框架需要决定哪些要保存、哪些可以丢、哪些需要放到长期记忆里避免上下文越拖越长最后把模型燃尽。第四异常处理。模型偶尔会抽风、工具偶尔会报错、任务偶尔会超时框架要有兜底策略是重试、换路径还是把问题抛回给用户。这四个能力决定了一个 Agent 是能干活还是只能演示。所以选框架之前你得先回答一个问题你的核心场景卡在哪一块如果是重流程、多角色协作那流程编排能力优先如果是改代码、跑测试代码操作能力和仓库集成优先如果是处理图片、音频、环境感知多模态链路优先如果只是做个查资料的终端助手轻量和快速上线优先。这个前置判断做完了再看下面的框架对比你就会有坐标感。1.1 框架选型的四个核心维度我一般用四个维度快速筛框架不只看功能列表。第一个维度是运行开销。Agent 框架不是免费的它要跑调度逻辑、维护对话状态、处理工具日志可能还要起一个长期驻留的服务。像轻量的场景用太重的东西就是把一台货车当自行车骑跑起来又费电又占地方。第二个维度是扩展成本。你的场景大概率不只是聊天而是要接内部系统、接数据库、接业务 API。框架能不能让你低成本地写一个自定义工具文档全不全社区有没有现成插件这些比框架本身的花活重要得多。第三个维度是可控性。Agent 执行过程动不动就不可复现这次跑对了下次跑错了。框架能不能给你清晰的日志、断点续跑、人工审核环节直接决定了你敢不敢把它放到生产环境里。第四个维度是生态成熟度。框架的周边工具、示例项目、踩坑帖子多不多决定了你遇到问题能不能自己查明白。一个再漂亮但没人用的框架你踩坑时就是孤军奋战。2. 四个框架的定位拆解各有各的强势区把四个框架放一起对比时千万不要把它们看作谁比谁更强而是看作谁更适合哪类任务。我说说实际用的感受。2.1 DSH流程稳定派DSH 是我接触最早的一类框架特点是流程引擎非常扎实。它对任务的定义方式是结构化、有明确边界的开发者要声明任务依赖、执行顺序、分支条件和异常出口。它更适合那种步骤一定要按顺序来中间不能乱的场景比如多轮数据清洗、定时任务编排、需要人工审批的业务流程。DSH 的优点首先是稳定。它的执行引擎会把每一步的状态落盘节点挂了可以从断点续跑。其次是可控所有 Agent 的状态都可以通过管理接口查询谁在跑哪些任务、跑到哪一步、占了多少资源清清楚楚。最后是测试友好因为流程是显式声明的你几乎可以像测试普通程序一样测试 Agent 流程。DSH 的缺点也很明显那就是重。学习曲线陡声明流程的配置要多写不少代码。而且它对自由对话和多模态支持比较弱如果你希望 Agent 能即兴发挥、走一步看一步地探索DSH 会憋死你。给 DSH 一个画像适合已经有一定中后台开发经验的团队适合任务边界清晰、需要审计合规的严肃场景。如果你是刚上手玩 Agent第一周大概率会觉得配置繁琐到想放弃。2.2 Codex代码操作派Codex 这一类框架的核心场景是代码仓库级操作。它不只是生成一段代码而是能把改代码、跑测试、看报错、再改一版、提交这个循环串起来。开发者给它一个 issue它能自己去仓库里找文件、定位问题、改代码、跑测试最后生成一个提交说明。这类框架在开源社区里讨论热度高是因为它解决了一个特别痛的痛点日常修 bug 和写小需求的重复劳动。这类框架的优点第一是代码理解能力强对多文件项目结构有建模不是只看单个文件。第二是工具链集成度高常见 Git 操作、命令行执行、测试框架它都内置了。第三是结果可验证它会给出改动前后对照、测试通过情况你可以审查而不是盲信。它的缺点也很真实。一是资源消耗高跑一个任务要动用好几个模型调用耗时和成本都比纯聊天高一个量级。二是扩展性偏科如果你想让这类框架去做代码以外的事比如处理合同文档、做客服问答会发现它的很多设计都是围绕代码场景改造成本很大。三是安全边界要小心它能够在你的仓库里执行命令权限必须严格控制否则就是给自己埋雷。画像大概是面向开发者效率工具、需要深入代码库的自动化场景。如果你的目标只是帮我写个函数其实不需要它直接让模型生成再复制粘贴就行如果目标是处理整个 issue这类框架就很香。2.3 Pi多模态感知派Pi 这类框架的核心差异点在于环境感知。它不只处理文本还能把图片、界面截图、音视频信息当作输入让 Agent 不只是读文字而是看环境。典型场景包括根据设计图生成页面、分析用户发来的报错截图、在 GUI 环境中操作软件完成数据录入。Pi 最亮眼的地方是它把视觉理解和操作决策合并到一条链路里而不是让视觉模型和决策模型互相倒腾。这意味着它在看一眼界面-决定下一步点哪里-执行的循环中响应快、误判少。另外一个优点是自定义多模态工具很方便你可以把自建的图像分类模型包装成工具交给 Agent 调用。代价是Pi 对部署环境有要求要跑视觉模型的话需要一定的 GPU 资源。如果你只是在 CPU 服务器上跑很多能力会缩水。同时这类框架的代码量偏大抽象层次多新手容易在到底哪个组件负责什么上绕晕。画像需要处理视觉信息的场景优先选它比如 UI 自动化、图片内容理解、多模态客服。如果你的需求纯文本就能解决杀鸡用牛刀没必要上 Pi。2.4 Hermes轻量快跑派Hermes 类框架给我的感觉像是一把瑞士军刀不追求每个功能都极致但开箱即用、干啥都行。它走的是轻量路线核心设计目标是把一个 Agent 快速跑起来同时保持对常用工具的覆盖。你拿来接个网页搜索、读个文件、发个 HTTP 请求它都有现成实现。优点是上手成本极低。装好依赖、配好模型接口、写几句 Prompt一个能用的 Agent 就起来了。配置文件的写法也很直观不会像 DSH 那样要建一堆流程定义。它的内存占用也低适合跑在单机小容器里。社区里还有很多插件包想扩展个 Slack 通知、邮件发送、定时任务基本是装一个包的事。缺点是当任务稍微复杂时它容易力不从心。因为核心流程编排比较灵活自由度太高反而容易失控。工具之间的依赖顺序没有 DSH 那么严谨跑长任务时会出现上下文管理问题、中途状态丢失。它在多模态和代码仓库这两个专业方向上也不如 Pi 和 Codex 深入。画像个人效率工具、快速原型、想要一个不折腾就能用的助手Hermes 非常合适。你是团队里负责写基建、要长期维护一套复杂业务的人迟早会被它的自由度逼疯。2.5 四框架横向对比速查表维度DSHCodexPiHermes核心强项流程编排、稳定性代码仓库级操作多模态感知、GUI 操作快速启动、轻量部署学习成本高中高中低运行资源占用中高高低工具扩展难度中中偏高易典型场景业务审批、数据管道修 bug、写需求、CI 辅助设计稿转页面、界面自动化个人助手、群聊机器人不适合场景快速原型、自由探索非代码类业务纯文本轻任务长链路严肃流程这张表只代表某个时间节点的普遍感受。开源项目迭代太快今天不适合的明天可能就是强项所以我更建议把它当判断框架的方法论而不是对某个版本的最终结论。3. 核心细节解析架构、工具调用与扩展性选框架不能只看定位还得看具体的技术细节。这几个细节会直接影响你后面踩坑的数量。3.1 架构设计的差异决定了你的维护成本四个框架的架构有本质差异。DSH 采用的是显式编排架构。它有一个中央调度器流程通过配置文件定义Agent 节点之间是明确的前后依赖。这种架构的好处是行为可预测缺点是代码抽象层数多出了 bug 要往下翻很多层才能找到根因。Codex 采用任务循环架构。框架建立一个循环每一轮都让模型决策下一步操作是改文件、跑命令还是读日志直到任务完成。这种架构天然适合探索性任务但你也需要为循环设置上限不然遇到死循环模型能自己空转很久。Pi 采用感知-决策-行动三段式架构。感知模块对输入进行视觉、文本等多模态理解决策模块结合历史状态生成计划行动模块执行工具调用。模块之间有一个共用的状态缓冲区。它的好处是逻辑清晰坏处是模块依赖较重。Hermes 采用最小核心插件架构。核心只负责会话运行和工具分发其余功能全部以插件形式加载。这种架构让主进程很轻但也意味着插件质量需要你自己把关插件写崩了核心进程不会帮你兜底。理解架构之后你会发现所谓哪个框架好其实是哪种架构适合你的团队维护习惯。如果你们擅长传统后端服务DSH 的显式编排上手会很快如果你们习惯做算法模型集成Pi 的三段式更贴近你的思维。3.2 工具调用设计真正决定 Agent 效率的地方Agent 能不能干活关键在于工具调用设计。我重点看三个细节。第一个是工具描述格式。框架需要把有哪些工具可以选、参数是什么、什么时候该用传给模型。有的框架用纯文本描述简单但容易冗长有的框架用结构化定义模型一次就能准确匹配。实操下来结构化定义在复杂任务中准确率明显更高。第二个是工具返回结果的处理。一个工具执行完返回的可能是一大段日志、一张表甚至一个文件路径。框架怎么把这些塞回上下文要不要做截断、摘要、结构化直接影响下一轮模型判断。好的框架会让你自定义返回结果处理器差的框架只会把原始输出硬塞进去几次工具调用后上下文就乱掉。第三个是工具并行调度。有的框架每次只执行一个工具有的框架支持同一轮并行调用多个独立工具。并行能力强不强不是拉满数量就完事还得看框架有没有做依赖分析。我见过一个框架拿到简单任务也喜欢并行调一堆工具结果互相等资源比串行还慢。实操时无论你选哪个框架先写一个最小工具测一下让 Agent 先查一个文件再根据文件内容调一个外部 API。跑通这个链路你就知道框架的工具调用设计是不是顺手。3.3 多 Agent 协作不是银弹很多人选框架一上来就问支不支持多 Agent 协作好像只要支持了就能解决所有问题。实际不是。多 Agent 协作本质上是要在多个模型角色之间分配任务、同步状态、汇总结果这非常考验框架的通信机制。DSH 对多 Agent 的支持是编排式协作每个 Agent 有明确的槽位和职责像是在流水线上分工。它的优点是协作过程可审计缺点是灵活性一般临时改角色分配要重写配置。Codex 的多 Agent 更偏向主从协作一个主 Agent 规划若干个子 Agent 执行。子 Agent 执行过程中可能会再派生子 Agent。这种模式灵活但也会带来状态膨胀一个复杂任务跑完中间会有几十个子任务的记录上下文和存储压力都很大。Pi 的多 Agent 协作是围绕共享工作区设计的多个 Agent 可以往同一个状态区里写入观察结果。这种模式适合需要环境信息的场景比如一个 Agent 截图、一个 Agent 分析、一个 Agent 决策。Hermes 的多 Agent 支持则更多依赖外部流程来控制框架本身并没有太强的协作协议更适合多个独立 Agent 各干各的最后由外部脚本汇总的模式。我的建议是如果单个 Agent 加几个工具就能解决别硬凹多 Agent。多 Agent 的复杂度是指数级上升的调试成本极高。框架支持多 Agent 是加分项但不能作为首要选型依据。3.4 记忆管理的细节长任务成败的关键长任务跑久了上下文管理不到位Agent 会变得既忘事又糊涂。记忆管理是四个框架里差异最大的地方。DSH 的流程状态分阶段保存节点执行完会把结果写到状态库下一节点再读取天然适合长任务但记忆单元比较重不适合高频小任务。Codex 会用会话摘要来压缩历史每执行几步就把之前的决策过程提炼一下。这样上下文不会无限膨胀代价是压缩过程会丢细节有时候它会把之前明确说过的限制条件给忘掉。Pi 的多模态记忆是分模态管理的文本记忆和视觉特征分开存查询时通过跨模态索引来关联。这种设计适合视觉场景但在纯文本任务里没有明显优势。Hermes 默认把多轮对话完整保存在上下文里直到把上下文塞爆。你可以配滚动窗口但滚动后它就只能依赖外部存储来做长期记忆这块实现比较弱。实操上你在做长任务时最好主动给它记忆锚点比如让 Agent 每隔几步输出一个结构化的阶段小结而不是全靠框架自动管理。这能省掉不少返工。4. 实操过程从选型到跑通一个 Demo理论说完了来点实际的。我拿一个读取数据文件并按需求生成报告的典型小任务演示怎么用这四个框架把它们跑通并验证哪种框架适合这个需求。4.1 准备环境与模型接口无论用哪个框架你都需要一个模型接口作为 Agent 的大脑。现在主流框架基本都支持 OpenAI 兼容的接口格式也有各自的适配器。实际部署时我建议把模型接口地址和密钥统一放到环境变量里别硬编码在代码中。环境层面尽量准备一台带 GPU 的 Linux 服务器至少 16G 内存。Pi 如果不跑本地视觉模型可以不用 GPU但体验会打折扣Codex 跑代码任务时吃 CPU 和内存多一些DSH 和 Hermes 对硬件要求没那么苛刻。还要准备一个最小数据文件我建议用 CSV 格式里面包含日期、销售额、地区三列三五十行数据够 Agent 分析用了。4.2 用每个框架实现同样的任务任务定义为读取 CSV 文件统计各地区的总销售额按销售额降序排列生成一段 Markdown 格式的摘要报告。在 DSH 中你需要把任务拆成三个节点数据读取节点、统计计算节点、报告生成节点。每个节点声明输入输出 Schema然后由编排引擎串联。中间如果某个节点失败框架会自动从上一个成功节点重跑。我第一次配这种三个节点的流程花了两个小时熟悉之后二十分钟能配完。在 Codex 中实现思路完全不同。你只需要给模型一句话任务描述然后给它文件路径和可用的工具列表。它会自己决定先用读取工具看文件结构再写一段 Python 做统计最后生成报告。这里的关键参数是最大推理步数我一般设置 15 步以内超过就终止防止它空转。实测跑了四个来回工具调用能完成耗时约两分钟。在 Pi 中我会额外加入一个视觉步骤让 Agent 先读取数据并生成一张柱状图然后再看这张图来写报告。这里要用到它的多模态能力中间会调用绘图工具生成图片再由视觉模块解析图片。这个链路更复杂但输出形式更丰富。在 Hermes 中我用插件方式快速加载 CSV 读取插件和 Markdown 输出插件然后写一段非常直白的 Prompt读这个文件统计每个地区总销售额写一段报告。 它很快就能跑完且配置量是四个框架里最少的。但如果数据文件变大、或者要接多步处理它的表现就会明显吃力。4.3 参数选择的思考这里重点说几个影响成败的参数每个框架都有类似概念。第一个是温度参数。做数据统计这种事实性任务温度必须调低我一般设 0 到 0.2 之间否则模型会自己发挥给你编一个不存在的数字。写创意文案时再调高到 0.7 以上这属于基本常识但新手经常忘。第二个是上下文窗口大小。Codex 和 Hermes 一旦任务步骤多了很容易耗尽上下文。你需要根据任务规模提前评估是裁剪输入、启用摘要还是拆成子任务。我跑这个 demo 时把 CSV 内容做了前 15 行预览传给模型让它按行分析避免把整份文件塞进去。第三个是最大迭代次数或最大工具调用数。这个参数是保命用的不设的话Agent 可能在工具报错之后反复重试同一个操作白白烧掉大量 token。按这个任务的复杂度我设 8 到 15 次就够。第四个是输出格式强制字段。DSH 和 Pi 这类结构化配置的框架一定要显式声明输出的 JSON Schema否则模型输出的 Markdown 里会夹带私货比如以下是报告这种废话。声明了格式模型就会老老实实交出纯内容。4.4 跑通后要观测哪些指标跑通一次只是开始别急着欢呼。我会看四个指标。耗时时长。任务的端到端时间在大模型应用里显得很慢动辄几十秒到几分钟。如果你要做交互式产品这个指标可能直接决定方案可不可行。Token 消耗总量。不同框架在相同任务下消耗 token 的数量能差出两三倍。D 框架会为了状态记录花掉额外 tokenC 框架会在反复看文件时消耗较多H 框架最省。这个指标直接对应你的运营成本。人工干预次数。正常跑通一次不难难的是随机换一份数据能不能也跑通。如果每次都需要你调整 Prompt 或修正路径说明框架的任务理解能力不足后期运维会非常痛苦。故障恢复能力。故意让某个工具中途报错看框架是傻傻重试、换方案还是直接放弃。比较下来DSH 的恢复机制最稳健Codex 在代码错误时会在重试前尝试读日志找原因Pi 更容易在感知模块报错时止步Hermes 报错后基本要靠 Prompt 外部的重试逻辑兜底。5. 常见问题与排查技巧实录按这套方法选下来你还是会遇到一些通用问题。我把最常见的几个列出来附带排查思路。5.1 为什么 Agent 总是调用同一个工具导致死循环这是工具调用类框架最常见的问题。原因是模型发现某个工具报错了会误以为换个参数重试就能成功结果陷入死循环每次都烧一样的 token产出为零。排查思路分三步。先看日志里工具返回的报错信息是不是同一个如果是同一个说明模型在走老路。再看 Prompt 里有没有强调每轮至少换一种解决思路我刚才说的最大迭代次数参数必须设这是底线。最后检查工具描述里是否写了明确的适用条件模型不知道什么时候不该用它自然就会乱用。我的做法是在工具描述里加一行当你已经重试同一工具超过两次且仍然失败时应停止调用并总结原因。这行字能有效减少死循环。5.2 为什么任务跑着跑着上下文越拖越长因为框架默认会把每轮工具返回结果都原样保留。像 Codex 这类框架每次读文件都会返回大段内容多轮之后上下文直接爆炸。解决方法是给工具调用加返回结果摘要。比如 CSV 读取工具不要让 Agent 看到全部数据而是让它只看前几行和统计摘要需要完整数据时单独再给完整路径让它自行读取。另一个技巧是定期让 Agent 输出当前阶段总结并把这个总结作为下一轮对话的起点老上下文丢进存储不再传给模型。这招在 Hermes 里特别有用。5.3 为什么 Agent 生成的代码在本地跑不过大概率是环境依赖问题。Codex 类框架在执行代码时往往用的是一个沙箱环境和你的真实项目环境不完全一致有些包没装、Python 版本不对就会报错。我建议在任务描述里明确给出运行命令和环境要求比如用项目根目录的 requirements.txt 安装依赖后再执行测试。还要允许框架读取项目的环境配置文件把它当作上下文的一部分。另外不要让它一上来就跑整体测试先跑一个最小用例快速暴露环境问题。5.4 为什么同一个任务偶尔成功偶尔失败大模型应用天然有随机性但分布区间过大会影响可用性。排查时先看温度参数是否设置过低或过高再看工具调用结果是否稳定比如外部 API 是否响应延迟大最后看 Prompt 里是否有歧义词。更实用的一招是固定样例测试。把同样的任务跑五次记录成功率和失败时的报错模式。如果五次里失败原因都不同说明 Prompt 表达不够明确如果都是同一个卡点说明框架对某个特定工具调用的处理有问题。5.5 常见问题速查表现象可能原因优先排查方向反复调用同一工具缺少重试限制Prompt 加停止条件设置最大迭代次数上下文很快耗尽返回结果未做摘要给读取类工具加摘要逻辑生成代码跑不过沙箱环境差异在 Prompt 中强制指定环境配置偶发失败率高温度参数不当改成 0.1 再跑五次对比时间太长工具串行依赖太多检查是否有可并行的独立工具输出格式混乱缺少输出 Schema显式声明 JSON 输出格式视觉任务空转感知模块截不到图检查图像传入路径是否被中间步骤包裹5.6 一个容易被忽略的坑模型版本升级导致行为漂移框架版本变化大模型版本变化更大。同一个 Prompt换个模型版本后结果可能完全不一样。很多时候你排查半天发现不是框架的问题是模型接口返回的策略变了。对策是把你常用的 Prompt 和关键任务固化成回归测试集每次升级模型或框架之前都跑一遍。这是维护成本最低、收益最高的做法。否则等到生产环境出问题再去追原因会非常被动。6. 根据场景做最终决断的个人经验框架没有统一的最强只有最匹配。如果你所在团队要做的是严肃业务系统、任务链路固定且需要审计我建议优先考虑 DSH 这一类显式编排框架。它不会给你太多惊喜但能让你安稳睡好觉。如果你要做的是研发效能工具、自动化修 bug、辅助代码评审Codex 这一类代码操作框架是当前最值得投入的方向。如果任务是围绕界面、图像、视频展开的比如设计稿转页面、自动操作办公软件Pi 这类多模态感知框架值得重点关注。纯文本场景选它属于浪费但在视觉场景它基本没有替代品。如果你只是给自己搭一个助手或者想快速验证一个想法Hermes 这类轻量框架最合适。先跑起来数据结构和业务模型验证有效之后再迁移也不迟。我个人在实际操作中的体会是框架选型的本质不是打分题而是匹配题。你先把自己的任务、环境、团队能力、维护周期想清楚再来看框架很多纠结会自动消失。真正靠谱的选型不是选一个听起来强大的框架而是选一个让你愿意长期维护、出了问题能查明白的框架。最后再分享一个经验无论选哪个框架都要留出手工兜底的入口。Agent 会犯错框架会出 bug。一个允许人类中途接管、修改执行路径的框架比一个追求全自动但关上门的框架可靠得多。看框架时多留意它有没有提供断点编辑、人工审核这类接口这会在你的 Agent 翻车时救你一命。
