2025 年做 Agent 还是很难：来自一线实践的真实复盘

做 AI Agent 已经快两年了，我越来越觉得：这件事远没有大家想象的那么“开箱即用”。即使用了最先进的模型、最流行的框架，真正跑通一个可靠、可控、成本可接受的 Agent 系统，依然充满坑。这篇文章把最近几个月踩过的坑、趟过的雷、总结出的经验一股脑儿倒出来，希望能帮你少走一些弯路。

先说结论（TL;DR）

• Agent 本质是一个大循环，别指望现成的 SDK 能完美帮你抽象好一切；
• 高层框架（比如 Vercel AI SDK）在真实工具调用场景下很容易崩；
• 缓存最好自己显式控制，Anthropic 的付费缓存反而是我们最喜欢的；
• 强化（reinforcement）在循环里承担的作用比你想象的大得多；
• 失败必须严格隔离，否则一次小错误就能把整个上下文带崩；
• 共享状态（虚拟文件系统）是多工具、多子 Agent 协作的基石；
• 输出工具比直接让模型说话难控制得多；
• 选模型还是那句话：Haiku/Sonnet 依然是最好的 tool caller，Gemini 2.5 在处理大文档和图片时最稳；
• 测试和评估仍然是最头疼的事，目前还没找到特别满意的方案。

下面逐条展开讲。

一、到底该用哪个 SDK 做 Agent？

很多人第一反应是：直接用 Vercel AI SDK、LangChain、LlamaIndex 这些高层框架多好，一行代码切换模型，省心。

我们一开始也是这么干的，结果发现：越到后面越后悔。

为什么？因为真实 Agent 的工具调用千差万别，模型之间的差异又特别大（工具格式、缓存机制、错误提示、并行工具支持……），高层框架为了“统一”往往把这些差异抹平了，反而让你失去控制权。

举几个真实踩过的坑：

• Anthropic 的 web search 工具在 Vercel AI SDK 里经常把整个 message history 搞乱，至今没完全搞清楚原因；
• 缓存控制在 Vercel 那一层完全失灵，错误信息也看不懂；
• 想做并行工具调用时，格式对不齐，经常报错。

现在我们的选择是：直接用 Anthropic 官方 SDK，自己手写 Agent 循环。虽然代码多写几百行，但完全可控，出错也能一眼看出是模型问题还是我们自己的问题。

方案	优点	缺点
官方 SDK（Anthropic/OpenAI）	完全掌控循环、缓存、错误信息清晰	需要自己写循环，代码量稍多
高层框架（Vercel AI / LangChain）	开箱即用、切换模型方便	工具调用场景容易崩，缓存控制基本失灵

建议：除非你只是做个玩具 demo，否则先用官方 SDK，把循环跑通了再考虑要不要抽象。

二、缓存：越“麻烦”的方式反而越好用

不同平台的缓存策略天差地别：

• OpenAI：自动缓存，命中就便宜，但你完全猜不到命中率；
• Anthropic：手动创建 cache point，还要付费。

我一开始觉得 Anthropic 这设计太反人类了，后来发现：这才是真正的工程友好设计。

手动缓存的好处：

1. 成本完全可预测：你知道哪段一定会命中，哪段一定会重新算；
2. 可以把对话叉出两条分支同时跑（fork conversation）；
3. 支持上下文编辑（context editing），虽然我们还没完全用好；
4. 配合动态消息（比如当前时间）可以大幅提升缓存命中率。

我们现在的缓存策略非常简单：

• 系统提示之后立刻建一个 cache point（几乎 100% 命中）；
• 对话开头再建两个，第二个会随着对话尾巴往前推；
• 当前时间、用户名等动态信息全部放在后面单独的消息里，绝不污染前面缓存。

这样做的结果：同一个任务重复跑，90% 以上的输入 token 都是缓存命中，成本直接降到原来的 1/10 以下。

三、强化（Reinforcement）才是 Agent 的灵魂

很多人以为把任务描述写清楚、工具写好就行了，其实真正让 Agent “不跑偏”的，是每一步的强化消息。

每次工具调用回来，我们都会往上下文里塞一段强化内容，常见的有：

• 提醒整体目标：“你现在是在帮用户做数据分析，最终要输出一份 PPT”；
• 子任务进度：“第 1/4 步已完成，第 2 步正在进行”；
• 失败时给提示：“上一次用 pandas 报错了，可能是数据里含有空值，试试填补后再计算”；
• 环境变化通知：“刚刚并行分支已经把数据清洗好了，你可以直接读取 /workspace/cleaned.csv”。

还有一种特别好用的自强化工具：todo write 工具。Agent 自己列一个任务清单，工具原样返回给它。这个工具什么都不干，就是个“回音壁”，但效果惊人——它能让模型在上下文爆炸时仍然记得自己还要干嘛。

四、失败必须严格隔离

做代码类 Agent 最大的敌人就是：一次执行失败，把几千行错误日志塞进上下文，后面全崩。

我们现在的做法：

1. 把容易失败的任务拆给子 Agent，成功前主循环只看到“进行中”和“成功+简要总结”；
2. 失败的完整日志只在子 Agent 内部保留，主上下文只保留一句话：“该方案失败，原因是 XXX，建议换另一种方式”。

Anthropic 支持 context editing，可以直接把无用失败删掉，但会破坏缓存，所以我们暂时用得少。

五、共享虚拟文件系统：多工具协作的基石

如果你要做真正的多模态、多工具 Agent，没有共享文件系统基本玩不转。

我们给所有工具都接入同一个虚拟文件系统（in-memory 或磁盘都行），路径统一用 /workspace/xxx。

这样做的好处：

• 代码执行工具可以写文件；
• 图片生成工具可以写图片；
• 推理工具可以读取图片再描述；
• 代码工具可以把图片打成 zip 再上传……

没有这个共享层，很多流程直接死胡同。

六、输出工具为什么这么难用

我们不让 Agent 直接回复用户，而是强制它调用一个 output 工具（比如发邮件）。

结果发现：用工具输出的语气比直接让模型说话难控制太多。

我们试过用 Gemini 2.5 Flash 再润色一遍，结果延迟增加、质量反而下降，还老泄露中间步骤。

现在的临时方案：如果循环结束还没调用 output 工具，就强制塞一条强化消息：“请立刻使用 output 工具给用户最终答案”，然后再跑一轮。

七、2025 年 11 月的模型选型建议

主循环 tool calling：

• 第 1 选择：Claude 3.5 Sonnet（新版 Haiku 也非常接近）
• 第 2 选择：Gemini 2.5 Pro（并行工具支持最好）

子任务（大文档总结、PDF 提取、图片理解）：

• Gemini 2.5 Flash / Pro（基本不会被安全过滤器卡住）

GPT 系列在主循环里表现依然不如上面两家。

记住：单价便宜不等于总价便宜，一个靠谱的 tool caller 可能用 3k token 就搞定，差的模型转 30k 还没搞对。

八、测试和评估：目前最大的痛点

Agent 的评估太难了。

• 不能像普通 prompt 那样用外部评测集；
• 必须在真实运行环境里插桩采集；
• 一次改动可能影响所有任务，回归测试成本极高。

我们试过很多方案，目前没有一个让我们真正满意的。如果你在做 Agent 评测，有好用的框架欢迎告诉我。

九、写在最后

做 Agent 仍然是件“苦活儿”，但也正因为难，才有护城河。

现阶段能把下面几件事做好的团队，已经远远领先了：

1. 自己完全掌控 Agent 循环；
2. 显式缓存 + 强化驱动；
3. 失败隔离 + 共享文件系统；
4. 合理的模型组合。

希望这篇复盘能帮你绕过一些坑。如果你也在做 Agent，欢迎留言交流，我们一起把这件事做成。

（全文约 3400 字，纯干货，欢迎收藏慢慢看）