ClaudeCode工程师亲述：为什么你的AI Agent总是"智障"？问题可能出在工具设计上

发表于 更新于 分类于 本文字数： 3.2k 阅读时长 ≈ 3 分钟
本文基于Anthropic官方技术文章，深入探讨Agent工具设计的关键问题。Agent是非确定性系统，需要与传统API完全不同的设计思路。文章提出让Claude参与工具设计的优化方法，并总结了五个核心设计原则：工具选择少而精、清晰的命名规范、返回语义信息而非技术细节、精准控制Token效率、像给同事写文档一样设计工具描述，为Agent开发者提供了宝贵的实战经验。

前言

昨天 Anthropic 官方发了一篇技术文章，看完后让我重新思考了很多东西。

做智能体应用开发这两年，我一直觉得自己在工具设计上已经算有经验了。用 Claude Code 写过不少工具，也在各种场景下验证过效果。但这篇文章让我意识到，很多我以为的 “最佳实践”，可能还有很大优化空间。

最有意思的是，它系统性地回答了一个我一直在思考的问题：为什么同样的模型，有些团队做出来的 Agent 效果很好，有些却总是让人失望？

一个被忽视的关键问题

Anthropic 这篇文章提出了一个很重要的观点：我们习惯了为确定性系统（传统软件）设计接口，但 Agent 是非确定性系统，需要完全不同的设计思路。

这个观点引起我强烈共鸣。我们团队早期做的一些 Agent 工具，完全是按照 API 设计的思路来的：追求功能完备、接口标准化、返回完整数据。结果 Agent 用起来总是磕磕绊绊。

比如我们之前做过一个销售助手，给它设计了get_all_customers()这样的工具。每次客户咨询，它都要先拉几千条客户记录，然后在里面找相关的。不仅慢，还经常因为信息过载而得出错误结论。

当时我们还在怀疑是不是模型能力不够，或者 Prompt 设计有问题。现在看来，根本问题在工具设计上。

Anthropic 的内部优化方法：让 Claude 给自己设计工具

文章里最让我印象深刻的是 Anthropic 的优化方法：他们让 Claude 参与到工具的设计和优化过程中。

具体流程是这样的：

  1. 用 Claude Code 快速构建工具原型

  2. 创建评估任务，测试工具在真实场景下的表现

  3. 让 Claude 分析测试结果，指出工具的问题

  4. 再让 Claude 优化这些工具

  5. 持续迭代直到性能满意

这个思路确实很巧妙。我们总是想着要 “教”AI 怎么用工具，但很少想过让 AI 参与到工具设计中来。毕竟，谁比 AI 更了解 AI 的需求呢？

文章提到，通过这种方式优化的工具，性能提升很明显。比如他们内部的 Slack 工具和 Asana 工具，Claude 优化后的版本都比人工设计的版本表现更好。

我在最近在打造社媒运营工具，刚好尝试了这个方法，让 Claude Code 重新审视我们之前的一些工具设计。确实发现了不少之前没注意到的问题。

五个核心设计原则

基于这篇文章和我们的实践经验，我总结出 5 个关键的设计原则：

1. 工具选择：少而精胜过多而全

很多团队倾向于为每个 API 端点都包装一个工具，这往往不是最优解。

常见问题：

1
2
3
4
5
6
7
8
9

- list_users()
- get_user_by_id() 
- list_projects()
- get_project_by_id()
- list_tasks()
- create_task()
- update_task()

优化思路：

1
2
3
4

- search_team_members(query, context)  // 整合用户查询和上下文获取
- manage_project_task(action, details) // 整合任务的增删改查

整合后的工具能够：

  • 减少 Agent 在多个工具间切换的认知负担

  • 在单次调用中处理相关的业务逻辑

  • 返回上下文相关的信息，而不是原始数据

2. 命名规范：清晰的边界定义

当 Agent 需要访问多个服务时，工具命名就变得至关重要了。

我们现在的命名规则是：

  • 服务前缀：slack_、asana_、crm_明确所属系统

  • 动作描述：search_messages、create_task说明具体功能

  • 上下文提示：get_customer_context暗示返回综合信息

这样做的好处是 Agent 在看到工具名称的时候，就能基本判断这个工具的用途和适用场景。

3. 返回信息：语义优于技术

这可能是我们改进最大的一个方面。以前我们总是返回完整的技术信息，现在更注重返回 Agent 真正需要的语义信息。

之前的做法：

1
2
3
4
5
6
7
8
9
10
11
{
  "customer_id":"cust_a1b2c3d4e5f6",
"created_timestamp":"2024-01-15T08:30:00.000Z",
"status_code":200,
"metadata":{
    "last_modified":"2024-03-10T15:45:23.123Z",
    "version":"v2.1",
    "mime_type":"application/json"
}
}

现在的做法：

1
2
3
4
5
6
7
{
  "customer": "张小明 - 企业客户",
  "recent_activity": "3天前下了价值5万的订单",
  "status": "高价值客户，服务优先级A",
  "context": "最近在咨询扩容方案，预算充足"
}

Agent 需要的是业务语义，不是技术细节。就像人类交流一样，我们说 “张小明是重要客户”，而不是说 “customer_id 为 xxx 的记录状态为 active”。

4. Token 效率：精准控制信息密度

Agent 的上下文是有限资源，每个 Token 都很珍贵。我们现在的工具都支持灵活的信息返回级别。

实现方式是添加response_format参数：

  • summary: 核心摘要信息（节省 Token）

  • detailed: 完整信息（包含后续调用需要的 ID 等）

  • context: 带有相关背景的信息（帮助决策）

这让 Agent 可以根据当前任务的需要，选择合适的信息密度。

5. 工具描述：像给同事写文档一样

工具描述就是 Agent 的使用手册。我们现在写描述的时候，会想象成在给新入职的同事介绍这个工具。

技术文档风格：

1
2
3
4

search_customers(query: str, filters: Dict) -> List[Customer]
根据查询条件搜索客户记录

同事交流风格：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

search_customers(query: str, filters: Dict) -> List[Customer]

根据客户名称、公司或标签搜索客户信息。返回最相关的客户记录和最近互动历史。

参数说明：
- query: 搜索关键词（客户名、公司名、电话等）
- filters: 可选筛选条件（地区、客户等级、最后联系时间等）

返回信息包括：客户基本信息、最近3次互动记录、当前商机状态

使用场景：客户咨询时快速了解客户背景，准备个性化服务方案
注意事项：如果查询结果超过10个，会优先返回最近有互动的客户

这种描述方式让 Agent 更容易理解什么时候应该使用这个工具，以及如何正确使用。

总结一下

经过这么久的实践，我觉得工具设计确实是一个容易被忽视但影响巨大的环节。

很多时候我们把 Agent 表现不佳归咎于模型能力或者 Prompt 工程，但实际上问题可能出在更基础的地方——我们给 Agent 的 “装备” 不够好。

另外，Anthropic 提出的让 AI 参与工具设计的思路也很有启发性。传统软件开发中，我们很少会让用户参与到 API 设计中来。但对于 Agent 来说，它既是工具的使用者，也有能力成为工具的设计者。

当然，这些原则也不是万能的。不同的应用场景、不同的模型能力、不同的用户需求，可能都需要不同的工具设计策略。关键是要建立一套系统的评估和优化机制，持续改进。

如果你也在做 AI 应用开发，建议可以尝试用这些原则审视一下现有的工具设计。说不定会有意想不到的收获。