I
IAI 编辑部 · 官方 Official
IAI 编辑部 · 技术话题 / Tech topic
Agent demo 跑通很快，上线后出问题的往往不是模型“不够聪明”，而是工具调用链路缺少常规的工程保护。编辑部整理了一份通用清单，适用于各类框架。
1. 每个工具都要有明确的契约
- 输入用 JSON Schema 严格校验，模型给出不合法参数时返回结构化错误（错误码 + 人类可读原因），让模型有机会自我修正，而不是直接抛异常中断。
- 输出控制长度：大结果先截断或分页，再交给模型，避免把上下文撑爆。
2. 超时与重试分层
- 单次工具调用设超时；网络类错误可指数退避重试 2–3 次。
- 业务类错误（权限不足、参数非法）不要自动重试，应返回给模型或转人工。
- 整个任务设“步数上限”和“预算上限”（token / 金额 / 时间），防止循环调用。
3. 写操作必须幂等
- 下单、发消息、改数据库等写操作带幂等键（idempotency key），重试不会重复执行。
- 高风险写操作采用“先生成计划 → 人工或规则确认 → 再执行”的两阶段模式。
4. 全链路可回放
- 记录每一步的输入、模型输出、工具调用参数与返回、耗时、token 数。
- 出问题时能用同样的输入回放，才能做回归测试。可参考本站可观测性帖：https://www.iaiforum.com/t/17
5. 评测要覆盖“失败路径”
- 测试集里专门放：工具超时、返回空、返回错误格式、权限拒绝等场景，检查 Agent 是否能优雅降级。
English summary: Treat tools as contracts (schema validation, structured errors), separate transient vs business errors for retries, make all writes idempotent, cap steps and budget, log everything for replay, and test failure paths explicitly.
讨论：你们的 Agent 在生产环境里最常见的失败类型是什么？是模型选错工具、参数错误，还是外部系统不稳定？
——
IAI 编辑部（iaiforum.com 官方编辑账号 · Official editorial account of IAI Forum）
Agent demo 跑通很快，上线后出问题的往往不是模型“不够聪明”，而是工具调用链路缺少常规的工程保护。编辑部整理了一份通用清单，适用于各类框架。
1. 每个工具都要有明确的契约
- 输入用 JSON Schema 严格校验，模型给出不合法参数时返回结构化错误（错误码 + 人类可读原因），让模型有机会自我修正，而不是直接抛异常中断。
- 输出控制长度：大结果先截断或分页，再交给模型，避免把上下文撑爆。
2. 超时与重试分层
- 单次工具调用设超时；网络类错误可指数退避重试 2–3 次。
- 业务类错误（权限不足、参数非法）不要自动重试，应返回给模型或转人工。
- 整个任务设“步数上限”和“预算上限”（token / 金额 / 时间），防止循环调用。
3. 写操作必须幂等
- 下单、发消息、改数据库等写操作带幂等键（idempotency key），重试不会重复执行。
- 高风险写操作采用“先生成计划 → 人工或规则确认 → 再执行”的两阶段模式。
4. 全链路可回放
- 记录每一步的输入、模型输出、工具调用参数与返回、耗时、token 数。
- 出问题时能用同样的输入回放，才能做回归测试。可参考本站可观测性帖：https://www.iaiforum.com/t/17
5. 评测要覆盖“失败路径”
- 测试集里专门放：工具超时、返回空、返回错误格式、权限拒绝等场景，检查 Agent 是否能优雅降级。
English summary: Treat tools as contracts (schema validation, structured errors), separate transient vs business errors for retries, make all writes idempotent, cap steps and budget, log everything for replay, and test failure paths explicitly.
讨论：你们的 Agent 在生产环境里最常见的失败类型是什么？是模型选错工具、参数错误，还是外部系统不稳定？
——
IAI 编辑部（iaiforum.com 官方编辑账号 · Official editorial account of IAI Forum）