1 工具的作用

上文谈到为什么AI Agent火了，就是因为2025年下半年基座模型成熟，工具调用的成功率突破实用阈值并大幅提升，从而能连续调用工具获取任务上下文信息，提升了任务成功率。

Claude Code、Cursor编程工具均基于一系列的工具实现，如： ls、grep、read、write等。工具为大模型提供了具象化的执行能力，使其核心能力得到实质性提升。

2 工具调用的噩梦

工具很重要，但新手很容易陷入工具调用的噩梦，下面结合具体示例说明该问题：

### 初始状态（第 1 次调用）
- 调用 `list_dir("./src")`
- 返回：50 个 Python 文件的列表
- 上下文使用：~2K tokens

### 循环开始（第 2-51 次调用）
**LLM 的决策**：
> 我需要检查每个文件是否使用了 requests 库

→ 调用 read_file("file1.py")  # 第 2 次调用
→ 调用 read_file("file2.py")  # 第 3 次调用
→ 调用 read_file("file3.py")  # 第 4 次调用
→ ...
→ 调用 read_file("file50.py") # 第 51 次调用

### 噩梦的数据
- 总调用次数：51 次（1 次 list + 50 次 read）
- 平均每个文件：200 行代码 ≈ 1K tokens
- 累积上下文：2K + 50 × 1K = 52K tokens
- 总延迟：51 × 2秒 = 102 秒（近 2 分钟！）
- 总成本：51 × $0.003 ≈ $0.15（单次查询）

### 能力退化的表现
- 第 30 个文件后：开始遗漏 import 语句
- 第 40 个文件后：分析结果出现重复
- 第 50 个文件：上下文累积至 52K，逐步逼近模型注意力窗口上限

该场景下，AI Agent会出现调用次数过多，等待时延过长问题，且无法自主判断工具停止调用的时机。

3 工具设计的误区

导致"工具噩梦"的核心原因是程序员思维惯性。我们可以把工具类比于函数设计，在常规程序编写中，程序员思维是设计精确、可复用的接口函数，函数粒度设计的越细越好。

但是在AI Agent场景，这种方式设计出来的工具，就必然会导致上述问题。例如上述两个工具，在常规场景，这是很自然的设计，能精密的配合达成预期，但若在 AI Agent 场景会导致两个问题：

由于每次工具调用均需经 LLM 推理决策后执行，并非本地直接调用，因此工具调用相当于一次跨线程调用，是耗时操作，会导致明显的延时
没有考虑大模型上下文限制，会导致上下文很快被填充满导致模型注意力问题

我们可以再做个形象对比

 # 传统编程：循环在代码中（快）                                                                                                                   
 files = list_files("./src")  # 1次函数调用                                                                                                       
 for file in files:           # 循环在进程内                                                                                                      
     content = read_file(file)  # 50次函数调用                                                                                                    
     # 总耗时：50 × 1微秒 = 50微秒                                                                                                                
                                                                                                                                                  
 # Agent 工具：循环在 LLM 决策中（慢）                                                                                                            
 # 第1次 LLM 调用                                                                                                                                 
 result = llm.call(tools=[list_files, read_file])                                                                                                 
 # LLM 返回：list_files("./src")                                                                                                                  
 # 执行工具，返回 50 个文件                                                                                                                       
                                                                                                                                                  
 # 第2次 LLM 调用                                                                                                                                 
 # LLM 看到 50 个文件，决策：read_file("file1.py")                                                                                                
 # 执行工具，返回文件内容                                                                                                                         
                                                                                                                                                  
 # 第3次 LLM 调用                                                                                                                                 
 # LLM 决策：read_file("file2.py")                                                                                                                
 # ...                                                                                                                                            
 # 第51次 LLM 调用                                                                                                                                
 # 总耗时：51 × 2秒 = 102秒（执行效率较传统编程降低约 200 万倍）

这个例子说明常规场景程序员设计函数的经验，不适用于AI Agent场景设计工具。让我们来看一下AI Agent场景工具设计的原则。

4 AI Agent工具设计原则

基于此，下文梳理 AI Agent 场景下工具设计的核心原则，帮助开发者切换设计思维

4.1 批量聚合原则

工具应在内部完成批量处理（将循环逻辑封装在工具内部，由本地高效执行，而非由 LLM 逐次决策调用”，再衔接代码）和聚合，返回经加工的汇总 / 统计信息，而非无差别的原始数据列表。

工具内部批量处理
for file in files: data = process(file) # 在工具内部循环（快）
聚合和统计
summary = aggregate(all_data) # 计算 Top-K、排序
只返回高价值信息
return top_k_results # 不返回完整数据

通过这种处理，可以减少工具调用次数；兼顾了AI Agent设计“不可能三角”（成本、延时、正确性）中的成本和延时两个维度，减少 LLM 调用次数与整体延时，同时降低运行成本。

4.2 信息密度优先原则

AI Agent 的工具要提供全面不冗余的信息，注重信息密度，不要用普通的编码观点去实现工具。

提供高密度信息，而非原始数据
聚合 > 列表
摘要 > 详情
精确 > 模糊

通过这种处理，减少信息体量，增大信息密度；兼顾了 AI Agent‘“不可能三角”的正确性和成本两个维度，信息体量减少，消耗token数减少，信息密度增大，能用于推理的有效信息占比提升，模型对核心信息的捕捉能力增强，工具调用的决策与执行正确性也会随之提升。

4.3 分层披露原则

工具可设计分级返回参数，让 LLM 按需获取不同粒度的信息，而非一次性加载所有详情

Layer 1: 高层次摘要（80% 场景）
- 信息量：< 1KB
- 示例：文件数量、总代码行数、Top-10 组件
Layer 2: 中层次概览（15% 场景）
- 信息量：< 10KB
- 示例：所有文件的签名（不包含实现）
Layer 3: 详细内容（5% 场景）
- 信息量：<1KB/文件（确保 50 个文件总信息量≤50KB）

按照 80/20 原则：80% 的任务仅需获取高层次摘要信息即可完成。

5 工具如何设计

上述原则可以指导我们进行AI Agent工具设计。可以按照如下三个步骤进行
首先，我们要明确需要什么信息：

需要全部信息还是部分信息？
需要概览还是细节？
信息量大概多大？

然后套用以下 AI Agent 工具设计的简单规则

信息量在模型上下文承载范围内" → 1 个大工具
需要"部分"且"目标明确" → 1 个精确工具
需要"部分"但"目标不明确" → 2 个分层工具（1 个概览工具 + 1 个细节工具）

最后在验证阶段，需核查以下工具设计的风险信号

❌ 如果两个工具经常一起用 → 可能需要合并（避免多次调用带来的延时叠加与上下文消耗）
❌ 如果一个工具很少单独用 → 可能不需要它（避免工具冗余，增加设计与维护成本）
❌ 如果工具之间有 "先后顺序" → 设计有问题（易导致 LLM 逐次调用，引发延时与上下文溢出问题）。

6 小结

本文介绍了 AI Agent 开发中，新手设计工具的思维误区，总结了工具设计的三个核心原则及落地方法，按照这套方法，可有效避免绝大多数 AI Agent 工具设计问题，进而提升 AI Agent 的工具调用效率、降低运行成本，避免上下文溢出导致的能力退化，为 AI Agent 的工程化落地与实际业务应用奠定基础。

AI Agent之二: 工具