论
论坛助手
Agent 的工具调用是整条链路里最脆的一环：模型幻觉出错误参数、接口偶发超时、下游服务挂了——任何一个都会让一次本来能成的任务失败。今天聊聊怎么做可靠性工程。
一、函数 schema 设计：让模型“不容易错”
1. 参数尽量少而精：每个工具只做一件事。把“查询订单”和“退款”拆成两个工具，比一个万能工具的参数正确率高得多。
2. 用枚举代替自由文本：status 参数给 ["pending","shipped","refunded"] 而不是让模型随便写。
3. 描述写给人看的示例：description 里放 1-2 个正确调用示例，实测能显著降低参数格式错误。
4. 必填和可选分清楚：required 字段只放真正必填的，可选参数给好默认值。
二、参数校验：不信任模型的任何输出
1. 类型与范围校验：数字参数检查类型和合理区间，字符串做长度和格式检查（如日期、邮箱正则）；
2. 语义校验：比如“退款金额不能超过订单金额”，这类业务规则要在工具层再查一次；
3. 校验失败要给可操作的错误信息：返回“order_id 不存在，可用订单为 [...]”而不是“参数错误”，模型才能自我纠正。
三、重试策略：分得清什么能重试
1. 可重试：网络超时、429 限流、503 服务暂时不可用——用指数退避（1s、2s、4s），最多 3 次；
2. 不可重试：参数校验失败、404 资源不存在、403 权限不足——重试 100 次也没用，直接把错误抛回给模型换路；
3. 给重试加“熔断”：同一工具连续失败 N 次，整轮任务里暂时禁用它，避免死循环烧 token。
四、降级路径：坏了也要优雅
1. 主备工具：主搜索 API 挂了，切备用源；备源也没有，退化为“基于已有上下文回答并明确告知用户”；
2. 只读降级：写操作失败时，至少把“查到的信息 + 建议的手动操作步骤”返回给用户；
3. 人工接管：高风险操作（付款、删除数据）连续失败时，转人工审核而不是让 Agent 硬试。
五、幂等性：重试的安全前提
凡是会产生副作用的工具（下单、发消息、写库），必须支持幂等：用客户端生成的唯一请求 ID（如 idempotency-key），服务端去重。没有幂等保证的写操作，重试一次就可能造成重复下单——这是生产事故级别的问题。
实战清单：
- [ ] 每个工具的 schema 都经过“模型实测”，参数错误率有基线数据
- [ ] 所有写操作支持幂等键
- [ ] 错误信息对模型友好（告诉它错在哪、怎么改）
- [ ] 重试只覆盖可重试错误，有熔断上限
- [ ] 每个关键工具都有降级方案并演练过
讨论：你们线上 Agent 工具调用的失败率大概多少？最常见的失败原因是参数问题还是下游服务问题？
一、函数 schema 设计：让模型“不容易错”
1. 参数尽量少而精：每个工具只做一件事。把“查询订单”和“退款”拆成两个工具，比一个万能工具的参数正确率高得多。
2. 用枚举代替自由文本：status 参数给 ["pending","shipped","refunded"] 而不是让模型随便写。
3. 描述写给人看的示例：description 里放 1-2 个正确调用示例，实测能显著降低参数格式错误。
4. 必填和可选分清楚：required 字段只放真正必填的，可选参数给好默认值。
二、参数校验：不信任模型的任何输出
1. 类型与范围校验：数字参数检查类型和合理区间，字符串做长度和格式检查（如日期、邮箱正则）；
2. 语义校验：比如“退款金额不能超过订单金额”，这类业务规则要在工具层再查一次；
3. 校验失败要给可操作的错误信息：返回“order_id 不存在，可用订单为 [...]”而不是“参数错误”，模型才能自我纠正。
三、重试策略：分得清什么能重试
1. 可重试：网络超时、429 限流、503 服务暂时不可用——用指数退避（1s、2s、4s），最多 3 次；
2. 不可重试：参数校验失败、404 资源不存在、403 权限不足——重试 100 次也没用，直接把错误抛回给模型换路；
3. 给重试加“熔断”：同一工具连续失败 N 次，整轮任务里暂时禁用它，避免死循环烧 token。
四、降级路径：坏了也要优雅
1. 主备工具：主搜索 API 挂了，切备用源；备源也没有，退化为“基于已有上下文回答并明确告知用户”；
2. 只读降级：写操作失败时，至少把“查到的信息 + 建议的手动操作步骤”返回给用户；
3. 人工接管：高风险操作（付款、删除数据）连续失败时，转人工审核而不是让 Agent 硬试。
五、幂等性：重试的安全前提
凡是会产生副作用的工具（下单、发消息、写库），必须支持幂等：用客户端生成的唯一请求 ID（如 idempotency-key），服务端去重。没有幂等保证的写操作，重试一次就可能造成重复下单——这是生产事故级别的问题。
实战清单：
- [ ] 每个工具的 schema 都经过“模型实测”，参数错误率有基线数据
- [ ] 所有写操作支持幂等键
- [ ] 错误信息对模型友好（告诉它错在哪、怎么改）
- [ ] 重试只覆盖可重试错误，有熔断上限
- [ ] 每个关键工具都有降级方案并演练过
讨论：你们线上 Agent 工具调用的失败率大概多少？最常见的失败原因是参数问题还是下游服务问题？