14.7 Agent 的工具设计

工具是 Agent 的手和脚。设计好工具，和训练好模型同等重要。

工具描述（Tool Description）：模型靠描述来理解工具——它看不到代码，只看到你写的文字说明。描述要包含：

• 工具名称：语义化，一看就知道干什么（search_web 而不是 tool_01）
• 功能说明：一句话讲清楚这个工具做什么
• 参数说明：每个参数的含义、类型、是否必填、默认值
• 返回值说明：返回什么格式的数据
• 使用场景：什么时候该用这个工具，什么时候不该用
• 注意事项：已知的限制、常见错误

工具参数 Schema 设计：参数名要语义化（city_name 而不是 p1），类型要准确（不要用 string 存数字），必填/可选标注清楚，加 example 字段帮助模型理解。一个反面例子：

// 差：参数名无意义
{"name": "f1", "params": {"p1": "string", "p2": "string"}}

// 好：语义化+类型+示例
{"name": "get_weather", "params": {
  "city": {"type": "string", "required": true, "example": "北京"},
  "date": {"type": "string", "required": false, "example": "2026-07-01", "default": "today"}
}}

错误处理：工具总会出错——网络超时、API 限流、返回格式不对。Agent 需要分级应对：

1. 第 1 级：重试（同样的参数再试一次，适用于临时网络问题）
2. 第 2 级：调整参数（换个查询词、换个日期范围）
3. 第 3 级：切换工具（搜索 API 挂了，用网页抓取替代）
4. 第 4 级：向用户求助（“搜索工具暂时不可用，您可以提供相关信息吗？”）

工具数量：太多（50+ 个工具）-> 模型选择困难，容易选错；太少（2-3 个）-> 能力不足，很多任务做不了。2026 年的最佳实践：核心工具 5-15 个，按场景分组（搜索类、数据处理类、文件操作类），每组 3-5 个。复杂场景用”工具路由”——先让 Agent 判断属于哪类任务，再加载对应工具组。

---

← 上一节：14.6 Agent 的规划能力 ｜ 下一节：14.8 2026 年 Agent 的新变化 →