夜雨聆风一个Agent能调用多少工具不是关键，关键的是每个工具是否真正"好用"。工具设计得不好，再强的模型也会翻车。这篇文章从工具定义、错误处理、效果评估三个维度，给你一套可落地的实战方法。
先看一个真实案例
场景：让Agent帮用户预订餐厅。
"name": "book_restaurant",
"description": "预订餐厅",
"parameters": {
"restaurant": "餐厅名称",
"time": "用餐时间",
"people": "用餐人数"
}
}
运行结果：
• 用户说"帮我订今晚7点海底捞"，Agent调用工具
• 工具返回错误：参数"people"必填
• Agent追问用户"请问几位用餐？"
• 用户说"3个人"，Agent再次调用
• 工具返回错误：时间格式错误
• Agent再次追问...用户崩溃
💡 问题诊断：
1. 参数缺少类型定义，Agent不知道"今晚7点"不是合法格式
2. 没有默认值，people为null直接报错
3. 错误信息不友好，Agent不知道如何修正
"name": "book_restaurant",
"description": "预订餐厅，需要餐厅名称、用餐时间和人数。如果用户未提供人数，默认2人。",
"parameters": {
"type": "object",
"properties": {
"restaurant": {
"type": "string",
"description": "餐厅名称，如'海底捞(朝阳店)'"
},
"time": {
"type": "string",
"description": "用餐时间，格式：YYYY-MM-DD HH:MM"
},
"people": {
"type": "integer",
"description": "用餐人数，整数",
"default": 2
}
},
"required": ["restaurant", "time"]
}
}
运行结果：
• 用户说"帮我订今晚7点海底捞"
• Agent解析：restaurant="海底捞", time="2026-06-04 19:00", people=2（默认值）
• 调用成功，返回预订确认信息
• 用户只需1轮对话
工具设计的三个核心原则
原则一：参数类型要精确
问题：Agent可能传入"3个人"、"三个人"、"三人"，工具需要额外处理。
"people": {
"type": "integer",
"description": "用餐人数，整数，如2、3、4",
"minimum": 1,
"maximum": 20
}效果：Agent只能传入整数，减少格式问题。
原则二：描述要包含示例
"用餐时间"问题：Agent不知道该传什么格式，容易传错。
"description": "用餐时间，格式：YYYY-MM-DD HH:MM，
如'2026-06-04 19:00'"原则三：合理设置必填和默认值
问题：用户说"订海底捞"，Agent需要追问4次才能调用工具。
"required": ["restaurant", "time"],
"properties": {
"people": {"default": 2},
"phone": {"default": null}
}错误处理：四层防护机制
工具调用失败是常态，关键是如何处理。
第一层：参数验证
在工具执行前，先验证参数合法性。
errors = []
# 检查必填参数
for required_field in schema.get("required", []):
if required_field not in params:
errors.append(f"缺少必填参数：{required_field}")
# 检查类型
for field, value in params.items():
# 类型验证逻辑...
return errors
效果：在调用真实工具前，先拦截明显错误，避免浪费调用次数。
第二层：工具内部错误处理
工具执行时，要捕获所有可能的异常。
try:
# 验证时间格式
datetime.strptime(time, "%Y-%m-%d %H:%M")
except ValueError:
return {
"success": False,
"error": "TIME_FORMAT_ERROR",
"message": "时间格式错误，应为YYYY-MM-DD HH:MM"
}
try:
result = api.book(restaurant, time, people)
return {"success": True, "data": result}
except RestaurantNotFoundError:
return {
"success": False,
"error": "RESTAURANT_NOT_FOUND",
"message": f"未找到餐厅'{restaurant}'"
}
关键点：
• 每种错误都有明确的错误码
• 错误信息要具体，指导Agent如何处理
• 不要暴露技术细节给用户
第三层：Agent自动重试
当工具返回可恢复错误时，Agent应自动重试。
如果工具返回以下错误，自动重试：
- RATE_LIMIT_ERROR：等待2秒后重试，最多重试2次
- TIMEOUT_ERROR：等待1秒后重试，最多重试1次
如果工具返回以下错误，向用户说明：
- RESTAURANT_NOT_FOUND：提示用户确认餐厅名称
- SYSTEM_ERROR：提示用户稍后重试
同一工具调用失败超过2次，建议用户联系人工客服。
第四层：降级方案
当所有工具都失败时，提供替代方案。
1. 电话预订：400-xxx-xxxx
2. APP预订：下载海底捞APP
3. 现场排队：直接到店取号"
效果评估：五个关键指标
工具设计得好不好，要用数据说话。
| >90% | ||
| >80% | ||
| <2次 | ||
| <20% | ||
| <30秒 |
真实案例：电商客服Agent
场景：帮用户查询订单、处理退款、查询物流。
| +16% | |||
| +29% | |||
| -56% | |||
| -17% |
关键改进：
• 工具合并：一次调用获取完整信息
• 参数智能处理：模糊匹配、平台识别
• 错误信息优化：明确指导下一步操作
工具设计Checklist
参数设计
☐ 类型定义精确（string/integer/boolean/array/object）
☐ 描述包含格式说明和示例
☐ 必填参数控制在3个以内
☐ 次要参数有合理默认值
☐ 参数命名语义清晰
错误处理
☐ 每种错误都有明确的错误码
☐ 错误信息对用户友好，包含解决建议
☐ 工具内部有完整的try-catch
☐ Agent有重试规则
☐ 有降级方案
性能优化
☐ 工具粒度合理（一个任务1-2次调用）
☐ 接口响应时间<3秒
☐ 支持批量操作
☐ 有缓存机制
总结
工具调用是Agent的核心能力，工具设计得好，Agent才能"聪明"。
1. 参数类型要精确
2. 描述要包含示例
3. 必填和默认值要合理 ✦
1. 参数验证
2. 工具内部错误处理
3. Agent自动重试
4. 降级方案 ✦
1. 工具调用成功率 >90%
2. 单次成功率 >80%
3. 平均调用次数< 2次
4. 用户干预率< 20%
5. 任务完成时间< 30秒 ✦
