AI Agent工具调用实战:如何设计工具、处理错误、评估效果

一个Agent能调用多少工具不是关键，关键的是每个工具是否真正"好用"。工具设计得不好，再强的模型也会翻车。这篇文章从工具定义、错误处理、效果评估三个维度，给你一套可落地的实战方法。

△ 工具调用是Agent能力的核心

先看一个真实案例

场景：让Agent帮用户预订餐厅。

工具设计A

{
"name": "book_restaurant",
"description": "预订餐厅",
"parameters": {
"restaurant": "餐厅名称",
"time": "用餐时间",
"people": "用餐人数"
}
}

运行结果：

• 用户说"帮我订今晚7点海底捞"，Agent调用工具
• 工具返回错误：参数"people"必填
• Agent追问用户"请问几位用餐？"
• 用户说"3个人"，Agent再次调用
• 工具返回错误：时间格式错误
• Agent再次追问...用户崩溃

💡 问题诊断：
1. 参数缺少类型定义，Agent不知道"今晚7点"不是合法格式
2. 没有默认值，people为null直接报错
3. 错误信息不友好，Agent不知道如何修正

工具设计B

{
"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轮对话

✦ 对比：工具设计A需要3轮对话还失败，工具设计B只需要1轮就成功。✦

工具设计的三个核心原则

原则一：参数类型要精确

❌ 错误做法

所有参数都定义为string。

问题：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}
}

错误处理：四层防护机制

工具调用失败是常态，关键是如何处理。

△ 四层错误处理防护机制

第一层：参数验证

在工具执行前，先验证参数合法性。

def validate_parameters(params, schema):
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

效果：在调用真实工具前，先拦截明显错误，避免浪费调用次数。

第二层：工具内部错误处理

工具执行时，要捕获所有可能的异常。

def book_restaurant(restaurant, time, people=2):
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应自动重试。

System Prompt规则

## 工具调用错误处理

如果工具返回以下错误，自动重试：
- 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

场景：帮用户查询订单、处理退款、查询物流。

指标	优化前	优化后	提升
工具调用成功率	78%	94%	+16%
单次成功率	52%	81%	+29%
平均调用次数	3.2次	1.4次	-56%
用户干预率	35%	18%	-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秒 ✦

📺 下期预告

《Agent调试与监控实战：如何追踪决策过程、排查问题、建立可观测体系》