Agent 设计的实践挑战与经验总结

近期关于智能体（Agent）构建的实践经验表明,这项工作的复杂度远超预期。随着实际应用场景的深入,许多看似简单的技术决策都暴露出需要权衡的地方。本文将从SDK选择、缓存策略、循环强化等多个维度,分享构建生产级智能体过程中的关键发现。

SDK选择的困境与取舍

在智能体开发初期,开发者往往面临一个基础选择:是直接使用底层SDK(如OpenAI SDK或Anthropic SDK),还是采用更高级的抽象层(如Vercel AI SDK或Pydantic)。这个看似简单的技术选型,实际上对后续开发有着深远影响。

实践表明,尽管高级SDK提供了更友好的接口,但在构建智能体时往往会遇到两个核心问题。首先是不同模型之间的差异性问题。各家模型在工具调用、缓存控制、强化需求等方面的实现方式大相径庭,这使得通用抽象层很难提供恰到好处的封装。智能体的基本设计虽然只是一个循环结构,但根据提供的工具不同,这些循环之间存在着微妙但关键的差异。当前阶段,正确的抽象模式尚未形成共识,使用底层SDK反而能获得更好的控制力。

其次是提供商侧工具的兼容性问题。以Anthropic的网络搜索工具为例,在通过Vercel SDK使用时,经常会出现消息历史记录破坏的情况。这类问题的根源在于SDK试图统一不同提供商的消息格式,但这种统一化处理并不总是完美。相比之下,直接使用Anthropic SDK不仅能更轻松地管理缓存,在出现错误时也能获得更清晰的错误信息。

当然,技术生态一直在演进,未来可能会出现更成熟的抽象方案。但就目前而言,在构建智能体时,直接使用底层SDK可能是更务实的选择,至少在整个技术栈稳定下来之前是如此。

缓存管理的哲学转变

不同平台在缓存策略上的差异,揭示了设计哲学的根本分歧。Anthropic采用的是付费显式缓存模式——开发者需要明确管理缓存点,并为缓存使用付费。这种设计初看起来似乎增加了复杂度,但深入使用后会发现其独特价值。

显式缓存管理带来的最大优势是可预测性。开发者能够清晰地了解成本构成和缓存利用率,这对于生产环境的成本控制至关重要。更进一步,这种控制权开启了许多高级用法。比如可以将一个对话分叉成两个方向同时运行,或者在对话过程中进行上下文编辑。虽然最优策略还在探索中,但拥有这种精细控制的能力本身就很有价值。

在实际应用中,Anthropic智能体的缓存配置相对直接:第一个缓存点设置在系统提示之后,另外两个设置在对话开始处,其中一个会随着对话推进而动态调整。这种配置也带来了一些实现上的调整——为了避免破坏缓存,需要将动态信息(如当前时间)通过消息而非系统提示传递。相应地,循环中的强化机制也需要更频繁地介入。

强化机制的深度应用

强化(Reinforcement)在智能体循环中扮演着比预期更重要的角色。每次工具执行后,系统不仅要返回工具产出的数据,还可以注入额外的上下文信息。这包括提醒智能体整体目标和任务状态,在工具失败时提供调用建议,或是通知后台发生的状态变化。特别是在使用并行处理时,每次工具调用后都可以注入最新的状态信息,确保智能体掌握全局动态。

有时,智能体的自我强化就足以推动任务前进。比如"待办事项写入工具"本质上只是一个回显工具——接收智能体认为应该执行的任务列表,然后原样返回。看似简单的设计,却能有效地帮助智能体在复杂执行过程中保持清晰的任务感知,避免在冗长的上下文中迷失方向。

强化机制还用于处理环境异常。当执行过程中出现对智能体不利的状态变化时,比如恢复操作的数据损坏,系统会注入消息建议智能体回溯几步重新执行。这种主动的异常处理机制,能够显著提升智能体的鲁棒性。

故障隔离的技术策略

代码执行过程中的故障是不可避免的,关键在于如何处理这些故障信息,避免它们污染主循环的上下文。目前主要有两种隔离策略。

第一种是使用子智能体(subagent)模式。将可能需要多次迭代的任务独立运行,让子智能体反复尝试直到成功,然后仅向主智能体报告成功结果,附带一个简短的失败方法摘要。让智能体了解子任务中的失败模式是有益的,因为这些经验可以反馈到后续任务中,避免重复踩坑。但关键是要控制失败信息的粒度,不需要完整的错误堆栈和输出。

第二种是上下文编辑,这是Anthropic提供的一项特殊能力。通过移除那些未能促成成功但占用大量上下文的失败尝试,可以在后续迭代中节省token。不过目前这方面的实践经验还比较有限,主要挑战在于上下文编辑会自动使缓存失效,何时进行这种权衡才能抵消清除缓存的成本,还需要更多探索。

共享状态层的架构设计

基于代码执行和代码生成的智能体,必然需要一个共享的数据存储位置。文件系统(在很多场景下是虚拟文件系统)成为了一个自然的选择,但这要求不同工具能够协同访问。

避免死胡同是设计共享状态层的核心原则。死胡同指的是任务只能在特定子工具中继续的情况。举例来说,如果有一个图像生成工具,但它只能将图像传递给另一个特定工具,就会形成死胡同。因为可能需要用代码执行工具将这些图像打包成ZIP档案。解决方案是让图像生成工具将输出写入文件系统,而代码执行工具可以从同一位置读取。

这种设计是双向的。代码执行工具可能解压一个ZIP档案,然后进入推理阶段描述所有图像,接着再返回代码执行,如此循环。文件系统作为中介层,使得这种灵活的工作流成为可能。具体实现上,ExecuteCode工具和RunInference工具能够访问同一个虚拟文件系统,后者可以接收该文件系统上文件的路径参数。

输出工具的微妙挑战

构建非聊天式智能体时,输出工具的设计出乎意料地复杂。智能体最终需要与用户或外部世界通信,但中间过程的消息通常不对外披露。这就需要一个专门的输出工具,让智能体明确地用它来生成面向人类的消息。

实践中发现,控制输出工具的措辞和语气比想象中困难得多。这可能与模型的训练方式有关。一个尝试过但效果不佳的方案是让输出工具调用另一个快速LLM(如Gemini 2.5 Flash)来调整语气,但这不仅增加了延迟,还降低了输出质量。子工具缺乏足够的上下文,而提供更多主智能体上下文片段又会增加成本,且无法完全解决问题。有时还会在输出中泄露不该出现的信息,比如导致结果的中间步骤。

另一个问题是智能体有时根本不会调用输出工具。解决方法是追踪输出工具的调用状态,如果循环结束时未被调用,就注入强化消息鼓励使用。这种强制机制虽然简单,但确实有效。

模型选择的持续考量

在模型选择方面,Haiku和Sonnet系列仍然是工具调用场景的首选。它们不仅在工具调用的准确性上表现出色,在强化学习方面也相对透明,这使得它们成为智能体主循环的理想选择。Gemini模型系列是另一个明显的选项。相比之下,GPT系列模型在主循环中的表现并不突出。

对于需要推理能力的独立子工具,比如总结大型文档或处理PDF,Gemini 2.5是当前的优选。它在从图像中提取信息方面也表现优异,特别是考虑到Sonnet系列容易触发安全过滤器这一点。

一个重要的认知是,token成本并不能完全定义智能体的经济性。一个更优秀的工具调用者能用更少的token完成工作。市面上有些模型单价比Sonnet更低,但在实际循环中的总成本可能更高。

测试与评估的困境

测试和评估是目前最棘手的问题。智能体的特性使得传统的测试方法难以适用——与提示测试不同,智能体需要输入的数据太多,无法简单地在外部系统中进行评估。这意味着必须基于可观察数据或对实际测试运行进行检测来评估效果。

遗憾的是,目前尝试过的各种解决方案都未能找到令人满意的方法。这正成为构建智能体过程中越来越令人沮丧的一个方面。如何建立有效的评估体系,仍然是一个开放性的挑战。

编码智能体的使用体验

在编码智能体的使用方面,近期开始更多尝试Amp。吸引人的地方不仅在于其技术实现,更在于团队通过发布内容所展现的对智能体的深刻思考。不同子智能体(如Oracle)与主循环之间的交互处理得非常出色,这在当前的工具中并不多见。Amp和Claude Code都给人一种感觉——它们是由真正使用这些工具的人打造的产品,这种自洽性在行业中并不普遍。

值得关注的延伸阅读

几个相关的观点值得分享:

关于MCP的必要性讨论中,Mario Zechner提出了一个有趣的观点。许多MCP服务器可能过度设计了,包含了大量工具集却消耗了过多上下文。针对浏览器智能体用例,一种极简主义方法是通过Bash执行简单的命令行工具(启动、导航、评估JS、截图等),从而减少token使用并保持工作流程灵活性。基于这个思路已经有人构建了相应的Claude/Amp技能实现。

在开源生态方面,有观点认为小型、单一用途的开源库时代即将结束。随着内置平台API的完善和AI工具的普及,简单的实用工具现在可以按需生成,这确实是一个值得庆幸的变化。

工具层面,Tmux在智能体交互场景中展现出独特价值。对于任何需要智能体交互的系统,都值得为其添加Tmux相关的技能支持。

另外,LLM API的同步问题也是一个独立的技术话题,涉及的内容较多,值得专门探讨。

原文：https://lucumr.pocoo.org/2025/11/21/agents-are-hard/