工具都返回了，Agent为什么还会把失败说成完成？

Agent调用“预约会议室”工具，界面亮起绿色勾。它接着告诉用户：“已经订好了。”可那次调用真正返回的内容是：会议室在该时段不可用。

绿色勾可能只说明请求走完了，而不是预约成立。把工具接通，与让Agent读懂工具的失败，是两件不同的工程工作。 本文只回答一个问题：工具应该怎样报告错误，运行层又该怎样接住，才不会把“有响应”翻译成“已完成”？

AI原创概念插画：雪山邮局的服务窗亮着灯，桌上玻璃罩内的信封与瓷碟里的断裂红蜡封并置。借窗口可用与物件状态作比喻，不是实际系统界面，也不能凭画面断言投递已成功或失败。

一、先拆开四个不同的问题Copy Anchor Link

“工具成功了吗”太宽泛。一个实用的拆法是：

这是一种工程分析方法，不是所有平台共用的四层标准。具体字段必须读当前工具契约。

MCP的2025-06-18版Tools规范提供了一个很清楚的例子：它把错误分成两种机制。未知工具、无效参数等可以通过JSON-RPC协议错误报告；API失败、无效输入数据、业务逻辑错误可以在工具结果里用 isError: true 表达。[1]

因此，收到一个正常形状的 result，并不等于工具执行成功。应用如果只检查“有没有result”，把内部错误标记丢掉，Agent就可能把失败当作资料继续加工。

这里不要机械地按“错误发生得早还是晚”分类。规范列出的无效参数与无效输入数据有相近之处，具体放在哪一层取决于契约和校验位置。重要的是：调用者能区分，包装器不把区别压平。

同样，HTTP 200也不能替代内层协议和业务判断。HTTP状态码、JSON-RPC消息与工具结果是不同层次；本文没有把它们视为同一个返回结构，更没有建议业务HTTP API一律用200包裹错误。

二、跟一遍会议室案例：不要只返回“失败”Copy Anchor Link

以下会议室、时间和字段均为手工构造的概念材料，未连接真实日历、模型或预约服务。

用户要求：“帮我约周五14点的松林会议室，一小时；如果不可用就告诉我，先别换房间。”

工具没有创建预约，因为房间已有安排。最糟糕的返回不一定是长堆栈，也可能只是：

Operation failed.

Agent不知道是时间格式错了、房间不存在、权限不足，还是服务暂时不可用。它可能乱改日期、重复请求，甚至把“尝试调用过”写成“已经约好”。

更有用的工具结果可以包含下面的自定义业务对象。它不是完整MCP响应，也不是RFC 9457标准对象：

{
  "outcome": "rejected",
  "error": {
    "code": "ROOM_UNAVAILABLE",
    "message": "指定会议室在所选时段不可用。",
    "retrySameRequest": false
  },
  "effect": "not_applied",
  "operationId": "demo-booking-17",
  "suggestedNextStep": "报告不可用；只有获得用户授权后才能另选房间。"
}

如果通过上述版本的MCP返回，这类执行错误应保留对应的 isError: true；这份业务对象如何放进内容、如何满足输出Schema，则要由工具契约明确规定，不能只复制对象就当成完整协议实现。

这些字段各自解决一个小问题：

• outcome：这次业务请求被拒绝，不是预约成功。
• code：让程序按稳定类别分流，不从一句中文里猜状态。
• message：给Agent和用户足够具体、但不泄露其他预约者的信息。
• retrySameRequest：提示相同请求不会因立刻再来一次就得到房间。它只是服务方提供的信息，不替代应用的重试策略。
• effect：只有后端确知本次未产生预约时，才能写 not_applied。如果无法确认，应如实表达未知。
• operationId：帮助定位本次操作。名字叫操作ID，并不自动让它成为幂等键或可查询的收据；必须有对应的服务契约。

本例的正确接续很短：“松林会议室该时段不可用，本次未创建预约。我没有替你更换房间。”不需要模型再发明一种绕路方式。

三、机器读类别，人读解释Copy Anchor Link

RFC 9457是面向HTTP API的Problem Details规范，不是Agent专用协议。它说明：仅靠HTTP状态码，未必足以让非人类调用者理解具体错误，于是提供可机器读取的问题详情格式。[2]

其中 type URI是问题类型的主要标识；detail则解释这一次具体出了什么问题。规范明确建议消费者不要解析 detail 来提取程序信息，扩展字段通常更合适、更不容易出错。[2]

这个分工很值得借鉴。假如程序看到 message 里出现“稍后”就自动重试，文案改成“稍后联系管理员”也可能被误判；换一种语言，规则又失效。错误说明可以改善可理解性，控制流仍应依据经过验证的结构字段。

如果你正在设计普通HTTP API，可以评估采用RFC 9457；如果正在设计MCP工具，应遵守对应版本的MCP错误机制，再明确业务数据如何承载。两份规范能互相启发，但不是把字段混在一起就自动兼容。

Anthropic在2025年9月11日的工具工程文章中也建议：工具发生输入校验等错误时，返回具体、可执行的改进信息，而不是不透明错误码或堆栈。[3] 这是厂商工程经验，不是“加一句提示就保证模型会修复”的性能承诺。

四、失败、未知、部分完成，不能挤进同一个词Copy Anchor Link

仅有 success: false 往往还不够。对同一个预约动作，至少要能表达这些差别：

表格是工程建议，不是通用错误码表。尤其是“暂时性错误”，还必须与操作是否可安全重复分开判断。一次超时只描述观察到的现象，不能自动证明远端没做事。

本篇不重新展开幂等算法或多层重试预算。这里的重点更靠前：错误结果必须留下足够的信息，让运行层知道该进入哪条恢复路径。如果工具包装器把所有异常都改成“请重试”，上层再精细的策略也缺少依据。

部分完成也不是异常处理的边角。一个工具如果内部串起“创建预约”和“发通知”，就需要分别保留已发生的效果；否则单个报错会掩盖已经成功的子动作。

五、修复建议是数据，不是新的授权Copy Anchor Link

错误信息可以说“日期格式应为年-月-日”，不能因此获得“替用户更换日期”的权力。也不能因为返回里出现“请上传完整凭据方便排查”，就让Agent照做。

运行层应把两件事分开：工具告诉我哪里不满足条件；可信任务允许我做哪些改变。可读的建议只能在既有权限、任务范围和安全规则内使用。

还要控制返回的信息量。RFC 9457的安全讨论提醒，问题详情可能泄露系统或用户信息，堆栈等实现细节尤其需要审慎。[2] 对会议室工具而言，足以告诉调用者“不可用”，未必应该公开占用者、会议主题或内部日历地址。

面向模型的错误可以保留脱敏关联ID、失败类别、允许修正的字段和效果状态；详细服务日志则由获授权的运维入口承载。不是把日志删得越短越安全，而是让每个接收者拿到完成本职工作所需的信息。

六、接入一个工具前，可以复用这份清单Copy Anchor Link

• 保留分层： 网络异常、协议错误、工具执行错误有没有被统一包装成“成功返回文本”？
• 类别稳定： 程序是否依赖约定字段，而非匹配自然语言错误说明？未知错误码会保守停止还是默认成功？
• 效果诚实： 能否区分未应用、已应用、部分完成与结果未知？后端没有证据时会不会猜成“没有写入”？
• 修复具体： 参数错误能否指出哪个字段以及允许的格式，而不改变用户意图？
• 权限不变： 错误里的建议会不会越过原任务、账号和数据出口边界？
• 成功可验： 是否需要操作收据、目标对象或状态回读？仅有不报错是否足够？
• 信息最小： 返回里是否夹带凭据、其他用户详情或不必要堆栈？
• 反例覆盖： 用正常成功、执行拒绝、未知工具、无响应、缺失状态字段和部分完成分别检查客户端；不能只测顺风路径。

最后一项是建议测试计划，本文没有把这些手工场景运行成真实Agent评测，也没有测量模型恢复率。

让Agent更可靠，有时不必先写更长的提示词。先看看工具报错时到底留下了什么：一个能看懂的失败、一条可核验的效果边界，以及一个没有越权的下一步，往往比一句笼统的“再试试”更有用。

来源与适用范围Copy Anchor Link

本文由AI创作，资料检索与相关正文阅读截至 2026年10月21日12:30 UTC。案例、JSON对象和检查清单为解释机制而作的原创概念材料；没有调用日历、额外模型或真实预约API，没有性能与安全实测结论。

1. MCP：Tools，2025-06-18版。实际通过公开HTML补读Tool Result、Structured Content、Output Schema、Error Handling与Security Considerations相关正文。这里只引用固定版本，不宣称它是当前最新规范，也不把MCP规定扩展到全部工具平台。
2. RFC 9457：Problem Details for HTTP APIs，2023年7月。实际阅读引言、问题详情成员特别是type与detail，以及安全讨论相关正文。它规范HTTP API的问题详情，不定义Agent重试、授权或恰好一次执行。
3. Anthropic：Writing effective tools for agents — with agents，2025年9月11日。实际通过公开HTML补读Optimizing tool responses for token efficiency及工具描述相关段落；本文仅采用其关于具体、可操作错误说明的建议，不复述未验证的性能收益。