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

ClaudeCode工程师亲述：为什么你的AI Agent总是"智障"？问题可能出在工具设计上 ClaudeCode工程师亲述：为什么你的AI Agent总是"智障"？问题可能出在工具设计上 Modified September 14, 2025 Code block Plain Text Copy list users() get user by id() list projects() get project by id() list tasks() create task() update task() 优化思路： Code block Plain Text Copy 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真正需要的语义信息。之前的做法： Code block Plain Text Copy { "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" } } 现在的做法： Code block Plain Text Copy { "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的使用手册。我们现在写描述的时候，会想象成在给新入职的同事介绍这个工具。技术文档风格： Code block Plain Text Copy search customers(query: str, filters: Dict) List[Customer] 根据查询条件搜索客户记录同事交流风格： Code block Plain Text Copy search customers(query: str, filters: Dict) List[Customer] 根据客户名称、公司或标签搜索客户信息。返回最相关的客户记录和最近互动历史。参数说明： query: 搜索关键词（客户名、公司名、电话等） filters: 可选筛选条件（地区、客户等级、最后联系时间等）返回信息包括：客户基本信息、最近3次互动记录、当前商机状态使用场景：客户咨询时快速了解客户背景，准备个性化服务方案注意事项：如果查询结果超过10个，会优先返回最近有互动的客户这种描述方式让Agent更容易理解什么时候应该使用这个工具，以及如何正确使用。总结一下经过这么久的实践，我觉得工具设计确实是一个容易被忽视但影响巨大的环节。很多时候我们把Agent表现不佳归咎于模型能力或者Prompt工程，但实际上问题可能出在更基础的地方——我们给Agent的"装备"不够好。另外，Anthropic提出的让AI参与工具设计的思路也很有启发性。传统软件开发中，我们很少会让用户参与到API设计中来。但对于Agent来说，它既是工具的使用者，也有能力成为工具的设计者。当然，这些原则也不是万能的。不同的应用场景、不同的模型能力、不同的用户需求，可能都需要不同的工具设计策略。关键是要建立一套系统的评估和优化机制，持续改进。如果你也在做AI应用开发，建议可以尝试用这些原则审视一下现有的工具设计。说不定会有意想不到的收获。发个福利最后给大家送个小福利，ClaudeCode国内镜像一天的免费体验券（见文末）。读过我之前文章的朋友们知道，Claude Code一直是我的主力工具，之前给大家分享的使用经验也不少送你一张Claude Code速查表，保存到本地，随用随查我发现市面上99%教你用Claude Code的，连最基本的CLAUDE.md都不会用这样使用Claude Code让你的开发效率提升17倍：从入门到精通的实战技巧与避坑指南。很多朋友也私信如何用，海外访问经常不稳定，自建服务器又有封号风险（血和泪的教训）。最近发现银河录像局团队（https://nf.video）做的Claude Code国内镜像服务还不错。主要做海外流媒体和AI模型的国内镜像服务，我体验了一下它家CC的镜像，消耗了3000积分，大概能用2 3小时，效果蛮不错的，跟我200刀的自建服务器一个味道，访问也很稳定。福利来了：他们给我的粉丝准备了一天免费体验券，可以免费体验Claude Code镜像服务。对于想快速上手CC但又不想折腾网络环境的朋友来说，正好可以试试水。免费体验地址：https://cc.yhlxj.com/kycwwx。 PS：如果想购买它家其他的模型服务，比如ChatGPT PLUS，也可以使用我这个优惠码：sjzx2122，比直接买省不少。记得用完觉得好，用再考虑付费哈。栗子KK，一个在AI浪潮中游泳的AI产品Founder 传统技能不能丢，点赞、在看、关注三连走起，让我们一起聊科技、聊产品、聊未来 🚀 同时，欢迎评论区留言交流送你一张Claude Code速查表，保存到本地，随用随查我发现市面上99%教你用Claude Code的，连最基本的CLAUDE.md都不会用这样使用Claude Code让你的开发效率提升17倍：从入门到精通的实战技巧与避坑指南优化思路：整合后的工具能够： • 减少Agent在多个工具间切换的认知负担 • 在单次调用中处理相关的业务逻辑 • 返回上下文相关的信息，而不是原始数据 2. 命名规范：清晰的边界定义当Agent需要访问多个服务时，工具命名就变得至关重要了。我们现在的命名规则是： • • 服务前缀： slack 、 asana 、 crm 明确所属系统 • • 动作描述： search messages 、 create task 说明具体功能 • • 上下文提示： get customer context 暗示返回综合信息这样做的好处是Agent在看到工具名称的时候，就能基本判断这个工具的用途和适用场景。 3. 返回信息：语义优于技术这可能是我们改进最大的一个方面。以前我们总是返回完整的技术信息，现在更注重返回Agent真正需要的语义信息。之前的做法：现在的做法： Agent需要的是业务语义，不是技术细节。就像人类交流一样，我们说"张小明是重要客户"，而不是说"customer id为xxx的记录状态为active"。 4. Token效率：精准控制信息密度 Agent的上下文是有限资源，每个Token都很珍贵。我们现在的工具都支持灵活的信息返回级别。实现方式是添加 response format 参数： • • summary : 核心摘要信息（节省Token） • • detailed : 完整信息（包含后续调用需要的ID等） • • context : 带有相关背景的信息（帮助决策）这让Agent可以根据当前任务的需要，选择合适的信息密度。 5. 工具描述：像给同事写文档一样工具描述就是Agent的使用手册。我们现在写描述的时候，会想象成在给新入职的同事介绍这个工具。技术文档风格：同事交流风格：这种描述方式让Agent更容易理解什么时候应该使用这个工具，以及如何正确使用。总结一下经过这么久的实践，我觉得工具设计确实是一个容易被忽视但影响巨大的环节。很多时候我们把Agent表现不佳归咎于模型能力或者Prompt工程，但实际上问题可能出在更基础的地方——我们给Agent的"装备"不够好。另外，Anthropic提出的让AI参与工具设计的思路也很有启发性。传统软件开发中，我们很少会让用户参与到API设计中来。但对于Agent来说，它既是工具的使用者，也有能力成为工具的设计者。当然，这些原则也不是万能的。不同的应用场景、不同的模型能力、不同的用户需求，可能都需要不同的工具设计策略。关键是要建立一套系统的评估和优化机制，持续改进。如果你也在做AI应用开发，建议可以尝试用这些原则审视一下现有的工具设计。说不定会有意想不到的收获。发个福利最后给大家送个小福利，ClaudeCode国内镜像一天的免费体验券（见文末）。读过我之前文章的朋友们知道，Claude Code一直是我的主力工具，之前给大家分享的使用经验也不少送你一张Claude Code速查表，保存到本地，随用随查我发现市面上99%教你用Claude Code的，连最基本的CLAUDE.md都不会用这样使用Claude Code让你的开发效率提升17倍：从入门到精通的实战技巧与避坑指南。很多朋友也私信如何用，海外访问经常不稳定，自建服务器又有封号风险（血和泪的教训）。送你一张Claude Code速查表，保存到本地，随用随查我发现市面上99%教你用Claude Code的，连最基本的CLAUDE.md都不会用这样使用Claude Code让你的开发效率提升17倍：从入门到精通的实战技巧与避坑指南最近发现银河录像局团队（https://nf.video）做的Claude Code国内镜像服务还不错。主要做海外流媒体和AI模型的国内镜像服务，我体验了一下它家CC的镜像，消耗了3000积分，大概能用2 3小时，效果蛮不错的，跟我200刀的自建服务器一个味道，访问也很稳定。福利来了：他们给我的粉丝准备了一天免费体验券，可以免费体验Claude Code镜像服务。对于想快速上手CC但又不想折腾网络环境的朋友来说，正好可以试试水。免费体验地址：https://cc.yhlxj.com/kycwwx。 PS：如果想购买它家其他的模型服务，比如ChatGPT PLUS，也可以使用我这个优惠码：sjzx2122，比直接买省不少。记得用完觉得好，用再考虑付费哈。栗子KK，一个在AI浪潮中游泳的AI产品Founder 传统技能不能丢，点赞、在看、关注三连走起，让我们一起聊科技、聊产品、聊未来 🚀 同时，欢迎评论区留言交流 🔗 原文链接： https://mp.weixin.qq.com/s/neQ2sxhA... https://mp.weixin.qq.com/s/neQ2sxhA... 原创栗子KK 数镜智心2025年09月13日 07:08 北京前言昨天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端点都包装一个工具，这往往不是最优解。常见问题：