Retry、Idempotency 与结果控制

1. 为什么这组知识要一起学

把 Tool 视为确定性系统与非确定性模型之间的契约，覆盖设计、发现、执行、可靠性与评估。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Tool 是模型建议与现实世界副作用之间的契约。Tool 设计同时影响选择准确率、token 成本、安全边界和可测试性。

Tool Catalog → Exposure/Discovery → Model Tool Call → Schema Validate → Permission/Approval → Execute → Normalize → Result Policy → Context

3. 核心机制

Retry / Backoff / Jitter

区分 validation、permission、not-found、transient upstream、timeout、semantic failure。Retry 只对明确可恢复错误，并受 deadline/retry budget 约束。

Side Effects / Idempotency

写操作需 idempotency key、execution record 或业务唯一约束；否则 network timeout 后“到底成功没成功”会导致重复副作用。

Token-efficient Tool Results

返回字段投影、分页、聚合、artifact ref 通常比让模型总结海量 raw result 更稳定、更便宜。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

class ToolExecutor:
    async def execute(self, call, ctx):
        tool = self.registry.require(call.name)
        args = tool.validate(call.arguments)
        self.policy.authorize(ctx, tool, args)
        return await self.runner.run(tool, args, deadline=ctx.deadline)

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

ToolDefinition/Registry/Executor/ResultPolicy 分层；Local、MCP、Shell、Agent-as-Tool 统一到内部 Tool contract。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 按读/写/不可逆副作用分类
• 工具名和 description 避免重叠
• 大 catalog 动态暴露
• timeout/retry/idempotency 属于 Runtime policy

7. Failure Modes

7.1 工具越多越好

当出现「工具越多越好」时，检查 tool contract、选择歧义、args validation、permission、execution attempt 与 result size；不要只改 description。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 无分页返回海量结果

当出现「无分页返回海量结果」时，检查 tool contract、选择歧义、args validation、permission、execution attempt 与 result size；不要只改 description。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 写工具盲目 retry

当出现「写工具盲目 retry」时，检查 tool contract、选择歧义、args validation、permission、execution attempt 与 result size；不要只改 description。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 远程 schema 更新而本地 cache 过期

当出现「远程 schema 更新而本地 cache 过期」时，检查 tool contract、选择歧义、args validation、permission、execution attempt 与 result size；不要只改 description。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

粗粒度 tool 调用少但输出大；细粒度可组合但规划成本高；规模大时 discovery/deferred loading 优于全暴露。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

建立 tool-selection eval，记录 expected/selected/args/success/unnecessary calls，观察 confusion matrix。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Retry / Backoff / Jitter 最容易被误解的点是什么？

区分 validation、permission、not-found、transient upstream、timeout、semantic failure。Retry 只对明确可恢复错误，并受 deadline/retry budget 约束。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Tool Catalog → Exposure/Discovery → Model Tool Call → Schema Validate → Permission/Approval → Execute → Normalize → Result Policy → Context 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• Anthropic — Writing effective tools for AI agents
• Anthropic — Advanced tool use
• OpenAI Agents SDK — Tools

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。