学会像智能体一样思考

构建智能体工具框架最困难的部分之一，就是设计它的动作空间。Claude 通过工具调用开展工作，但在 Claude API 中，工具的构建方式有多种，可借助 bash、技能（Skills）等基础组件，以及最近推出的代码执行功能（更多关于 Claude API 中程序化工具调用的内容，可参阅 @RLanceMartin 的新文章）。面对这些选择，你该如何设计智能体的工具？只需要代码执行或 bash 这样的一种工具就够了吗？如果为智能体可能遇到的每一种场景都配备一个工具，总共需要 50 个工具，又该如何处理？为了站在模型的角度思考，我喜欢想象自己遇到一道难题时的场景：要解决这道题，你需要什么工具？答案取决于你自身的能力！纸和笔是最基础的工具，但手动计算会限制你的效率；计算器会更好用，但你需要知道如何操作更高级的功能；最快捷、最强大的工具是电脑，但你必须掌握编写和执行代码的方法。这是一个设计智能体的实用框架：你需要为它配备符合其自身能力的工具。但如何了解它的能力呢？你需要仔细观察、阅读它的输出、不断实验——学会像智能体一样思考。以下是我们在构建 Claude Code 过程中，通过观察 Claude 得出的一些经验。

优化提问引导能力与 AskUserQuestion 工具

在构建 AskUserQuestion 工具时，我们的目标是提升 Claude 提出问题的能力（通常称为“提问引导”）。虽然 Claude 可以用纯文本提问，但我们发现，回答这类问题往往需要花费不必要的时间。如何减少这种摩擦，提升用户与 Claude 之间的沟通效率？

尝试方案1：修改 ExitPlanTool 工具

我们首先尝试在 ExitPlanTool 工具中添加一个参数，让它在生成计划的同时，附带一组相关问题。这是最容易实现的方案，但却让 Claude 陷入了困惑——我们同时要求它生成计划和关于计划的问题，如果用户的回答与计划冲突怎么办？Claude 是否需要调用两次 ExitPlanTool 工具？我们需要另一种方法。（关于我们为何开发 ExitPlanTool 工具，可参阅我们关于提示词缓存的文章）

尝试方案2：修改输出格式

接下来，我们尝试修改 Claude 的输出指令，让它使用一种稍作调整的标记语言格式来提问。例如，我们可以要求它输出带括号备选答案的项目符号式问题，然后我们可以解析并将这些问题格式化为用户界面。虽然这是我们能做出的最通用的修改，而且 Claude 似乎也能较好地输出这种格式，但这种方式并不可靠——Claude 可能会添加额外的句子、遗漏选项，或者使用完全不同的格式。

尝试方案3：开发 AskUserQuestion 工具

最终，我们决定开发一个 Claude 可以随时调用的工具，尤其在计划模式下，会专门提示它调用该工具。当工具被触发时，我们会显示一个弹窗来展示问题，并暂停智能体的循环，直到用户给出回答。这个工具可以提示 Claude 输出结构化内容，确保它为用户提供多个选项；同时也为用户提供了组合使用该功能的方式，例如在智能体 SDK 中调用它，或在技能中引用它。最重要的是，Claude 似乎很喜欢调用这个工具，而且我们发现它的输出效果很好。即便工具设计得再好，如果 Claude 不知道如何调用，也是无用的。这是 Claude Code 中提问引导功能的最终形态吗？我们并不确定。正如你将在下一个例子中看到的，适合一个模型的方案，未必适合另一个模型。

随能力迭代：任务（Tasks）与待办清单（Todos）

当我们首次推出 Claude Code 时，我们意识到模型需要一个待办清单（Todo List）来保持专注。待办清单可以在开始时编写，随着模型完成工作逐步勾选。为此，我们为 Claude 提供了 TodoWrite 工具，用于编写或更新待办清单，并向用户展示。但即便如此，我们仍经常发现 Claude 会忘记自己要做的事情。为了改进这一点，我们每 5 轮对话就插入一次系统提醒，让 Claude 记起自己的目标。但随着模型的升级，它们不仅不再需要待办清单的提醒，反而会觉得待办清单有所限制。不断收到待办清单的提醒，会让 Claude 认为必须严格遵守清单，而不能根据实际情况修改。此外，我们发现 Opus 4.5 版本在使用子智能体方面有了很大进步，但子智能体之间如何协调共享待办清单呢？鉴于此，我们用任务工具（Task Tool）替换了 TodoWrite 工具（更多关于任务工具的内容，可参阅此处）。如果说待办清单的作用是让模型保持专注，那么任务工具的核心就是帮助智能体之间进行沟通。任务可以包含依赖关系、在子智能体之间共享更新，模型也可以修改或删除任务。随着模型能力的提升，那些曾经对模型有帮助的工具，现在可能会成为限制它们的因素。因此，不断重新审视关于“需要哪些工具”的原有假设，是非常重要的。这也是为什么我们建议只支持少数能力相近的模型——这样可以降低适配成本。

设计搜索界面

对于 Claude 来说，一组特别重要的工具是用于构建自身上下文的搜索工具。Claude Code 刚推出时，我们使用 RAG 向量数据库为 Claude 查找上下文。虽然 RAG 功能强大、速度快，但它需要索引和配置，而且在多种不同环境下可能不稳定。更重要的是，这种方式是“被动提供”上下文给 Claude，而不是让它自己去查找。但如果 Claude 能在网上搜索，为什么不能搜索你的代码库呢？通过为 Claude 提供 Grep 工具，我们可以让它自主搜索文件，构建属于自己的上下文。我们发现了一个规律：随着 Claude 变得更智能，只要给它合适的工具，它构建上下文的能力就会越来越强。当我们推出智能体技能（Agent Skills）后，正式提出了“渐进式披露”的概念——允许智能体通过探索，逐步发现相关上下文。Claude 可以读取技能文件，而这些文件又可以引用其他文件，让模型能够递归式读取。事实上，技能的一个常见用途就是为 Claude 增加更多搜索能力，例如告诉它如何使用 API 或查询数据库。在一年的时间里，Claude 从几乎无法自主构建上下文，发展到能够通过多层文件的嵌套搜索，找到自己需要的确切上下文。如今，渐进式披露已经成为我们在不添加新工具的情况下，为智能体增加新功能的常用技术。

渐进式披露——Claude Code 指南智能体

Claude Code 目前有大约 20 种工具，我们一直在思考：是否真的需要所有这些工具？添加新工具的门槛很高，因为这会让模型多一个需要考虑的选项。例如，我们发现 Claude 对如何使用 Claude Code 了解不够——如果你问它如何添加 MCP，或者某个斜杠命令的作用，它无法给出回答。我们本可以将所有这些信息都放入系统提示中，但由于用户很少询问这类问题，这会导致“上下文冗余”，干扰 Claude Code 的核心工作——编写代码。因此，我们尝试了一种渐进式披露的方式：给 Claude 一个文档链接，让它可以通过加载链接来搜索更多信息。这种方式虽然有效，但我们发现，Claude 为了找到正确答案，会将大量结果加载到上下文中，而实际上我们只需要最终答案。于是，我们构建了 Claude Code 指南子智能体——当你询问关于 Claude Code 本身的问题时，会提示 Claude 调用这个子智能体。该子智能体有详细的指令，指导它如何高效搜索文档以及返回什么内容。虽然这种方式并不完美——当你询问如何设置 Claude Code 时，它仍然可能会感到困惑，但已经比以前好很多了！我们成功地在不添加新工具的情况下，为 Claude 的动作空间增加了新的能力。