把错误提示当成 API 来写，这才是给大模型工具设计的正确姿势

一个极其低级但代价极高的设计决定，就是把错误提示写给那些根本不会去读它的“人类”，而不是写给正在调用它的 Agent。

在公司内部推行自动化工作流这段时间，我发现 Agent 踩坑最严重的地方不是 Schema 定义错了，也不是接口响应慢，而是那些“误导性”的报错信息。人类看到报错会习惯性地在周围寻找线索：检查服务状态、回想昨天是不是改了配置、或者问问同事。但对 Agent 来说，报错字符串就是它感知到的全部世界。如果报错说错了，它不会怀疑，而是会极其自信地花十分钟去解决一个根本不存在的问题。

我之前在跑一个浏览器自动化任务时就被坑惨了，所有页面加载都报 NS_ERROR_UNKNOWN_HOST。我第一反应是 DNS 挂了，结果在 shell 里 ping 哪个域名都能通。折腾了一小时才发现是 SOCKS 代理失效了，但浏览器却把代理连接失败报告成了“目标域名未知”。这种对人类来说勉强及格、对 Agent 来说却是“谎言”的报错，是最浪费研发时间的。

如果我们要给大模型写工具，错误提示必须满足这三点：

• 明确指出故障层级，而不是目标对象。 不要只说“无法访问 example.com”，而要说“无法连接到 10.200.0.2:1080 的上游代理”。Agent 看不到你的内部架构，报错信息就是它唯一的窗口。
• 明确告诉它重试是否有意义。 这是价值最高的信息。如果是因为参数传错了，重试五次也是浪费，得直接告诉它“除非修改参数，否则请求将持续失败”；如果是瞬时抖动，就告诉它“临时故障，稍后可重试”。
• 区分“空结果”和“执行失败”。 很多工具在查询失败时会直接返回一个空列表 []。Agent 拿到空列表会认为该对象不存在，然后把这个错误结论写进笔记里，直接污染后续的任务记忆。

以前的开发逻辑是：给运维写详细日志，给客户端返回简短错误码（比如 ERR_7734），因为客户端是程序，程序只认代码。但现在客户端变成了 LLM，它对自然语言的理解力极强，却对错误码完全没辙。

现在的逻辑得反过来：把报错信息写成你给一个能力很强、但看不见你屏幕的同事留的便签。描述得越详细、越自然，信息的带宽就越高，Agent 的实操效率才会真正提升。