agent-design

# 智能体设计模式 本文档涵盖了在 Claude API 上构建智能体的决策启发式方法：选择哪些原语、如何设计工具表面，以及如何在长时间运行中管理上下文和成本。有关每个工具的机制和代码示例，请参阅 `tool-use-concepts.md` 和特定语言的文件夹。 --- ## 模型参数 | 参数 | 使用场景 | 预期效果 | | --- | --- | --- | | **自适应思考** (`thinking: {type: "adaptive"}`) | 当您希望 Claude 控制思考的时机和深度时。 | Claude 根据每个请求确定思考深度，并在工具调用之间自动交替进行思考。无需调整 Token 预算。 | | **努力程度** (`output_config: {effort: ...}`) | 当需要调整彻底性与 Token 效率之间的权衡时。 | 较低的努力程度 → 更少且更整合的工具调用，更少的序言，更简洁的确认。`medium` 通常是一个良好的平衡点。当正确性比成本更重要时，请使用 `max`。 | 有关模型支持和参数详情，请参阅 `SKILL.md` 中的“思考与努力”章节。 --- ## 设计工具表面 ### Bash 与专用工具 Claude 不了解您的应用程序安全边界、审批策略或用户界面。Claude 发出工具调用；您的工具集（harness）负责处理它们。这些工具调用的形状决定了工具集能做什么。 **Bash 工具** 为 Claude 提供了广泛的编程杠杆 — 它可以执行几乎任何操作。但它只给工具集提供了一个不透明的命令字符串，对于每个操作形状都相同。将操作提升为**专用工具**，可以为工具集提供一个带有类型化参数的特定钩子，以便进行拦截、门控、渲染或审计。 **何时将操作提升为专用工具：** - **安全边界。** 需要门控的操作是天然的候选者。可逆性是一个有用的标准：难以逆转的操作（外部 API 调用、发送消息、删除数据）可以放在用户确认之后。`send_email` 工具很容易门控；而 `bash -c "curl -X POST ..."` 则不然。 - **陈旧性检查。** 专用的 `edit` 工具可以在文件自 Claude 上次读取后发生更改时拒绝写入。Bash 无法强制执行该不变性。 - **渲染。** 某些操作受益于自定义 UI。Claude Code 将提问提升为一个工具，以便它可以渲染为模态框、呈现选项，并阻塞智能体循环直到得到回答。 - **调度。** 只读工具（如 `glob` 和 `grep`）可以标记为并行安全。当相同的操作通过 bash 运行时，工具集无法区分