选框架最怕的不是选错，而是选了一个你还没搞清它替你做了什么的东西。打算做 Agent 接入与开发的人，通常卡在这几处：不知道该用现成框架还是自己写调用循环、框架升级后代码跑不动、工具一多状态就乱。这篇按场景给判断依据和上手前的检查动作，不替你拍板，只帮你在动手前把条件对齐。
选框架最怕的不是选错，而是选了一个你还没搞清它替你做了什么的东西。不少人上手就跑去找「哪个框架最强」，结果代码写到一半才发现框架根本管不了状态持久化，或者工具一多参数校验就崩。更务实的顺序是：先把自己的场景定下来，再反过来挑框架能力。
这篇不替你拍板用哪个框架，只帮你按场景拆条件。判断依据和检查动作给到位，具体到某个框架的版本、依赖、价格波动，去站内页面看当时的数字，别拿别人半年前的经验直接套。
先按场景分档，再谈框架
同样是做 Agent，三个场景对框架的要求完全不一样。单轮工具调用，本质就是「模型输出一个函数名加参数，你去执行」，步骤少、无分支、失败重试一次就够。多步带分支的任务，比如先查数据再决定走哪条路，就需要能表达条件跳转和循环的结构，还得能记住中间结果。需要人参与确认的长流程，节点之间可能隔几个小时甚至几天，状态必须能从内存里拿出来落盘。
场景层级比框架知名度更能决定选型。知名框架往往在某几个场景特别顺手，换到另一个场景反而绕。先问自己三个问题：最多几步、要不要回滚、要不要并发分支。这三问的答案基本就把候选范围砍掉一半了。
| 场景特征 | 优先看框架的哪项能力 | 容易忽略的坑 |
|---|---|---|
| 步骤固定、无分支 | 工具注册与参数校验 | 校验太松，模型传错类型才发现 |
| 多步带条件分支 | 流程编排、节点间数据传递 | 分支写死，改一次逻辑动全身 |
| 长流程、跨会话 | 状态持久化、断点续跑 | 状态只存内存，重启全丢 |
| 需要人工确认 | 中断恢复、审批节点 | 确认点无法暂停，只能整段重跑 |
框架到底替你做了什么，没做什么
- 流程编排
- 把多个步骤组织成可读的结构，支持条件跳转和循环
- 状态与记忆
- 把中间结果和对话历史存哪里、怎么取回来
- 工具注册与参数校验
- 把函数暴露给模型，并检查入参类型和必填项
- 可观测与重试
- 记录每步输入输出，失败时自动或手动重跑
多数框架只在上面四块里的一两块做得扎实，其余只是薄薄一层封装。你去翻文档时别被功能列表唬住，重点看它在你缺的那块到底做了多少。比如你的痛点是长任务状态丢失，那就盯着持久化方案看，而不是看它支持多少种工具类型。
框架不负责的部分要提前认清：鉴权、限流退避、成本控制这些它基本不管，得你自己在调用层做。一旦这些和框架逻辑搅在一起，后面换框架就是灾难。可到站内的技术栈图谱与 Agent 常用接口清单核对当时的实际情况。
- 画节点图把你要做的流程先画成方框加箭头，每个节点写清输入输出
- 标标注特殊节点在图上圈出哪几个节点需要重试、哪几个需要人工确认、哪几个要落盘
- 拿去对照用这张图去翻框架文档，看它能不能原样表达。表达不了就是硬伤，别指望后期补
把框架圈在边界内，别让它长进业务
框架圈在边界内，业务逻辑只依赖自己定义的接口，这是最省心的写法。框架相关代码收在一个适配层，业务侧调用的是你自己定义的函数签名。这样换框架或者退回裸调用时，改动只集中在适配层，业务代码一行不动。
状态存哪是另一个关键点。内存态适合本地调试，跑得快也好看。但长任务必须落库或落缓存，否则进程一重启，前面几步全白跑。选之前先确认框架支不支持外部存储，别默认它能自动帮你持久化。
- 入参类型写清楚，别用模糊的 object 糊过去
- 必填项显式标记，缺参数时返回明确错误而不是静默猜
- 错误返回格式统一，让模型能读懂失败原因并决定要不要重试
- 给每个工具设超时上限，避免一个卡住的调用拖垮整个流程
- 工具数量控制在你能逐个说清用途的范围内，多了模型也选不准
上手前和换框架前要核对的几件事
动手前先列一份清单，把依赖版本锁死，写清工具数量上限、单次任务步骤上限、失败重试几次。这几项在选型阶段看着琐碎，实际是后面出问题最快的排查入口。清单留一份，换框架时逐项比对。
版本升级踩坑集中在两处：依赖冲突和接口改名。升级前别直接改生产代码，先跑一遍自己的最小用例。另建议长期保留一份不依赖框架的最小复现脚本，出问题时用它区分到底是框架的问题还是模型的问题。
| 核对项 | 动作 | 不适用的情况 |
|---|---|---|
| 依赖版本 | 锁定版本号，升级前先跑最小用例 | 纯本地试验、不打算长期维护 |
| 步骤上限 | 设一个上限值，超了就报错而不是硬跑 | 流程本身很短、步骤固定 |
| 重试策略 | 明确重试几次、间隔多久 | 调用本身幂等、失败就放弃 |
| 状态存储 | 确认落库还是内存，写清恢复方式 | 跑完即弃、不需要断点恢复 |
参数细节、接口变动这些容易过时的信息，别信记忆，直接去站内页面看当时的数字。选型判断可以自己拿主意，但事实性数据要以站内核对为准。
下一步去工具目录翻一下你要用的那类 Agent 开发工具，对照本文的场景分档先圈出候选，再到技术栈图谱核对接口与版本细节。→常见问题
Agent 开发框架一定要用吗，自己写调用循环行不行？
看你流程的复杂度。如果只是固定几步工具调用、没有分支和人工确认，自己写循环更容易调试，也更少被依赖升级牵着走。一旦出现条件分支、多轮重试、跨会话记忆或需要中途人工介入，框架在状态管理和编排上的省事就开始划算。判断标准是你的流程图能不能用几行伪代码画完，画不完再考虑上框架。
换了框架之后原来的工具代码要重写吗？
取决于你当初有没有做适配层。工具函数的实际逻辑通常可以复用，要改的往往是注册方式和参数声明，比如schema写法、错误返回约定、超时字段位置。如果工具是直接按框架要求写的，换框架时基本要重包一遍。上手前把工具定义和框架调用分开，之后迁移成本会低很多。具体字段写法到站内对照页面确认当时的约定。
框架跑长任务跑到一半断了怎么办？
先看状态存在哪。内存态一断就没了，只能从头跑；落库的状态可以续跑，但要想清楚重复执行同一个工具会不会有副作用，比如重复下单或重复发消息。通常在工具层做幂等，在编排层记录已完成的步骤编号，重启后从断点继续。步骤上限和重试次数也要设，避免一直转圈烧成本。相关排查思路站内有专门的文章可参考。
