← 返回首页

Agent 工具设计最佳实践

工具是 Agent 的手和脚。工具定义得好，模型如虎添翼；定义得差，模型不断调错工具、传错参数、陷入死循环。以下是实际踩坑后的总结。

1. 工具描述：告诉模型「什么时候用」

不只是说工具做什么，关键要说清楚使用场景。好的描述包含：触发条件、适用场景、典型输入输出。

# ❌ 太模糊
"description": "Search the web"

# ✅ 有触发条件
"description": "Search the web for current information. Use when the answer requires real-time or recent data that may not be in training. Returns top 10 results with titles and URLs."

2. 参数命名：用自然语言

参数名就是给模型看的提示词。用 search_query 而不是 q，用 file_path 而不是 fp。每个参数都要有清晰的 description。

3. 工具粒度：不要太细也不要太粗

太细：一个工具只做一件事的十分之一，模型需要连续调用 10 次 → 容易迷路。

太粗：一个工具做所有事，参数爆炸 → 模型不知道传什么。

黄金法则：一个工具完成一个完整操作。读文件、写文件、搜索——分开但完整。

4. 返回格式：结构化 + 可解析

工具的返回值是模型的输入。纯文本可以，但 JSON 更好——模型能更准确地提取关键信息。错误时返回结构化的错误信息而非空字符串。

5. 错误处理：让模型知道失败了

工具执行失败时，不要返回模糊的错误。返回具体的失败原因和建议的下一步动作：

# ✅ 有帮助的错误
{"success": false, "error": "File not found: /data/report.csv",
 "suggestion": "Try listing /data/ to see available files"}

6. 限制工具数量

超过 20 个工具，模型的选择准确率显著下降。如果工具太多，考虑分层：先给核心工具，复杂任务才暴露高级工具。