上下文工程之构建自己的工具框架:和AI＂签合同＂的艺术

工具设计：和AI”签合同”的艺术

我让Agent调用工具，它经常干出这种事：

• 该调用A工具，调用了B工具
• 参数格式不对，报错后不知道怎么办
• 工具返回错误，Agent把错误信息当成答案告诉用户

问题不在Agent，在工具设计。现在也有一个新的方向Harness工程，也值得深入研究。

我后来意识到：工具设计本质是和AI”签合同”——你必须明确告诉它”什么时候用、怎么用、出错了怎么办”。

I一、命名清晰：描述越完整，调用越准确

早期我的工具描述：

name: get_logs

Agent的理解：”这个工具可能获取日志，也可能获取配置，不确定的时候先用用看。”

现在的工具描述：

name: query_application_logs
描述：仅用于查询应用程序运行日志。当需要排查应用错误、追踪请求链路时使用。不用于查询系统日志或配置文件。
参数：
  - app_name: 应用名称（必填）
  - time_range: 时间范围，格式"1h"/"1d"/"7d"（必填）
  - log_level: 日志级别，可选"ERROR"/"WARN"/"INFO"（默认ERROR）
返回值：JSON格式日志列表
错误处理：
  - 应用不存在 → 返回空列表，提示"请检查应用名称"
  - 时间范围超长 → 返回"最大支持7天，请缩小范围"

Agent现在几乎不会调用错工具——因为我把所有模糊空间都消除了。

二、合并原则：减少选择的痛苦

如果人类工程师都无法明确说”这种情况下该用哪个工具”，那AI也不可能做到。

我有过8个日志查询工具：

• query_app_logs
• query_system_logs
• query_access_logs
• query_error_logs
• …

Agent经常选错。后来合并成2个：

• query_application_logs（应用日志）
• query_infrastructure_logs（基础设施日志）

错误率直接下降70%。

比如Anthropic的元技能skills-create就经过改版，增加技能的评估校验能力

工具数量不是越多越好，边界清晰比功能细分更重要。

三、错误恢复友好：告诉AI怎么修

工具报错后的处理，是最容易被忽略的部分。

早期设计：

返回值：{ "error": "connection timeout" }

Agent看到这个，只会复读”连接超时”给用户。

现在的设计：

返回值：{ 
  "error": "connection timeout",
  "recovery_hint": "数据库连接超时，建议：1) 检查网络连通性 2) 确认连接池配置 3) 如持续发生，考虑扩容",
  "next_action": "请调用check_database_connectivity工具排查"
}

Agent不仅能告诉用户发生了什么，还能给出下一步操作建议。

四、我的工具设计模板

每个工具必须有：

1. 清晰的命名：动词+对象，如 query_application_logs
2. 明确的触发条件：”当…时使用”
3. 完整的参数定义：类型、必填、默认值、示例
4. 返回值结构：成功时返回什么，失败时返回什么
5. 错误处理指南：每种错误对应的恢复策略
6. 示例调用：给AI参考正确用法

五、工具设计的核心认知

工具是Agent能力的延伸，但也是错误的来源。

设计好的工具，不是让Agent”能调用”，而是让它”知道什么时候调用、知道调用错了怎么办“。

上下文工程专题

这是关于Context Engineering的系列文章第6篇。

系列文章：

• 第1篇：我花了三个月才明白：为什么我的AI Agent总是”聊着聊着就崩了”
• 第2篇：我的AI Agent为什么越用越”傻”？四个踩过的坑
• 第3篇：我给AI的”记忆”做了减法——上下文压缩实战
• 第4篇：为什么我把单Agent拆成了团队协作？
• 第5篇：我给Agent装了”长期记忆”——记忆系统设计
• 第7篇：我用代码给AI Agent打分——评估体系搭建（待续）

#上下文工程 #AIAgent #ToolDesign #大模型应用 #运维自动化