工具契约:区分选择、校验与执行错误
工具契约:区分选择、校验与执行错误,从执行机制、错误边界与可运行例子理解工程取舍。
模型请求调用“查询订单”,返回参数却是发票号码。修复之前要分清是选错了工具、选对工具但参数错误,还是参数正确而工具实现失败。把三种情况都包装成“工具调用失败”,会让模型盲目换参数或重复执行。
描述决定能否选对,Schema决定什么可以输入
工具名称宜表达明确动作,描述说明用途、适用边界、必要前置条件和与相似工具的差别。例如lookup_order只查询订单,issue_refund会产生退款副作用,不能只把两个工具都描述为“处理订单”。提供过多重叠工具会增加选择难度;可以按任务筛选候选,但不能借筛选绕过授权。
输入Schema明确类型、必填字段、枚举、范围、未知字段策略和嵌套结构。字符串形式的金额需要规定单位与精度,日期需要时区;null、字段缺失和空字符串应区别。模型输出结构合法之后,还要做业务校验:订单是否存在、金额是否在额度内、状态是否允许操作。
输出也应有契约:成功给出结果、来源和版本,失败给出稳定错误码、是否可重试及必要上下文。不要向模型泄漏堆栈中的凭证或用户隐私。结果较长时分页或返回可授权读取的引用,而不是静默截断关键字段。输出Schema能检查形状,不能判断事实是否准确。
错误来自哪一层
未知工具名称是路由或选择问题;缺少参数、类型错误是输入契约问题;余额不足属于业务拒绝;网络超时属于执行状态不确定,不能与明确失败合并。程序异常则需要内部追踪ID和告警。MCP中的协议错误与工具执行结果中的isError也不应混淆,客户端需按规范分层处理。
错误反馈尽量帮助下一步选择:缺少订单号可以请求用户补充,余额不足不应无限重试,已过期授权应走重新授权流程。模型能看懂错误并不意味着它有权修复,诸如提升权限不能通过自动换工具实现。
跟做:四种输入得到四种明确结果
保存为contracts.py,运行python -X utf8 contracts.py。标准库程序手写最小验证,不实现完整JSON Schema。Python中bool是int的子类,代码使用精确类型判断,避免True被当金额1。
"""区分未知工具、参数错误和执行失败;未调用模型。"""
def dispatch(name, args):
if name != 'divide_v1':
return {'ok': False, 'code': 'unknown_tool', 'retryable': False}
if not isinstance(args, dict) or set(args) != {'a', 'b'} or any(type(args[k]) not in (int, float) for k in args):
return {'ok': False, 'code': 'invalid_arguments', 'retryable': False}
if args['b'] == 0:
return {'ok': False, 'code': 'zero_divisor', 'retryable': False}
return {'ok': True, 'value': args['a'] / args['b'], 'version': 1}
if __name__ == '__main__':
for name,args in [('wrong',{}),('divide_v1',{'a':True,'b':2}),('divide_v1',{'a':8,'b':0}),('divide_v1',{'a':8,'b':2})]:
print(dispatch(name,args))实际运行输出:
{'ok': False, 'code': 'unknown_tool', 'retryable': False}
{'ok': False, 'code': 'invalid_arguments', 'retryable': False}
{'ok': False, 'code': 'zero_divisor', 'retryable': False}
{'ok': True, 'value': 4.0, 'version': 1}未知工具、布尔参数、零除数分别返回不同代码,最后8除2得到4.0。把b改成字符串"2"会得到invalid_arguments;执行器不擅自猜测转换。真实数字契约还应拒绝非有限浮点值,并根据业务使用整数分或Decimal,示例除法不适合作为金融计算器。
版本与副作用声明
改参数含义、单位或输出字段会破坏旧调用方。可采用版本化名称或显式契约版本,并为兼容迁移保留测试。只读、幂等、破坏性等描述能帮助宿主制定策略,但它们是声明,不是沙箱或安全证明。服务端仍要依据实际行为限制权限和审核日志。
定位问题时记录候选工具、最终选择、脱敏参数、验证结论和执行结果。对模型选择率、参数通过率、工具成功率分别统计,就能避免把数据库故障误归因提示词。
综合追问:同名退款工具收到字符串金额并返回一段报错,如何拆开故障?
这是给定条件下的机制推演;数值用于解释判断,不是新增线上或模型实测。先独立回答,再核对下面的推理。
展开推理、取舍与排错路径
名称和描述先说明查询还是退款、适用对象与副作用,减少选择混淆;工具越多不必越好,重叠描述会增加错选。输入规定单位、类型、必填和空值含义,输出规定成功字段/来源和稳定错误码;bool在Python中也是int子类,金额契约不能只用宽泛isinstance。结构通过后还需业务与权限检查。
先查是否选错工具,再查参数,最后看执行与外部状态:缺参数可补充,余额不足不能无限重试,超时要标结果未知。对外输出脱敏并带追踪ID,不让模型猜一段文本算成功。金额从元改分即使仍是number也破坏语义兼容,需要版本和回归;readOnly仅是声明,真实实现仍要受限。面试给出上述分层、失败恢复和版本迁移条件,比统一error字符串更可测试。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
如何区分三类调用错误?
参考思路与常见误区
先核对工具名称与任务,再校验参数结构和业务约束,最后检查执行器和外部系统状态。
常见误区:所有错误统一重试。
输入Schema正确就可以执行吗?
参考思路与常见误区
还需认证授权、对象范围与业务状态校验,结构合法不代表操作允许。
常见误区:把结构验证当授权。
为何输出也需要契约?
参考思路与常见误区
便于稳定回注、错误分类、版本迁移与下游校验,避免解析自由文本猜测成功。
常见误区:只定义输入。
readOnly标记能否保证安全?
参考思路与常见误区
只是行为声明,需核对实现和真实权限,不能替代隔离与审计。
常见误区:相信描述即可放行。
修改金额单位算兼容修改吗?
参考思路与常见误区
通常是语义破坏,需要版本或明确迁移和调用方回归,字段类型未变也不代表兼容。
常见误区:只检查JSON字段名称。
协议与接口细节请对照:官方资料1。