《Agent Runtime 工程化》为什么 Tool 必须支持 Idempotency？

如果一个工具没有写 idempotency，默认应该按 non_idempotent 处理。

保守一点没坏处。

三类工具，三种策略

第一类：天然幂等。

read_file
list_files
search_code
get_order_status
pure_compute

这些工具重复执行，通常不会改变外部状态。它们可以 replayPolicy: "auto"。

第二类：条件幂等。

write_file
apply_patch
update_config
run_command("npm test")

它们是否能重放，要看条件。

写文件要检查 base hash。应用 patch 要检查 patch 是否已经应用。npm test 理论上是只读，但测试脚本可能写 coverage、cache、snapshot。命令工具尤其不能只看工具名。

第三类：非幂等。

send_email
create_order
charge_customer
create_issue
merge_pull_request
npm publish
run_migration

这些默认不能自动重放。要么需要业务级 idempotency key，要么需要人工确认，要么只能走补偿动作。

命令工具最容易骗人

很多 Agent 项目会有一个 run_command。

这工具不能简单标成幂等或非幂等。

run_command("ls src")              幂等
run_command("npm test")            条件幂等
run_command("npm install")         有副作用
run_command("npm publish")         非幂等
run_command("rm -rf dist")         破坏性
run_command("prisma migrate deploy") 非幂等

所以 run_command 的幂等性要在计划阶段按参数分类。

function classifyCommandIdempotency(command: string): {
  idempotency: Idempotency;
  replayPolicy: ReplayPolicy;
  reason: string;
} {
  if (/^(pwd|ls|find|rg|cat|sed|wc)\b/.test(command)) {
    return {
      idempotency: "idempotent",
      replayPolicy: "auto",
      reason: "只读命令",
    };
  }

  if (/^npm test\b|^pnpm test\b|^yarn test\b/.test(command)) {
    return {
      idempotency: "conditional",
      replayPolicy: "ask",
      reason: "测试命令可能写 coverage、cache 或 snapshot",
    };
  }

  return {
    idempotency: "non_idempotent",
    replayPolicy: "never",
    reason: "命令可能产生不可恢复副作用",
  };
}

不要把 shell 当普通函数。

shell 是副作用入口。

Tool Ledger 要记录幂等性

工具执行前就要记账。

type ToolLedgerEntry = {
  callId: string;
  stepId: string;
  toolName: string;
  inputHash: string;
  status:
    | "planned"
    | "approved"
    | "started"
    | "succeeded"
    | "failed"
    | "uncertain";
  idempotency: "idempotent" | "conditional" | "non_idempotent";
  replayPolicy: "auto" | "ask" | "never";
  idempotencyKey?: string;
  sideEffects: string[];
  startedAt?: string;
  finishedAt?: string;
};

最重要的是 started 和 uncertain。

如果工具请求已经发出，但响应没回来，状态不能写成普通失败。应该写：

status = uncertain

恢复时看到 uncertain，再结合 idempotency 判断：

idempotent + auto：可以重放
conditional + ask：先检查条件或问用户
non_idempotent + never：禁止自动重放

没有 ledger，就没有恢复。

Idempotency Key 不能交给模型自由发挥

创建订单、扣款、创建 issue 这类工具，往往需要 idempotency key。

这个 key 不应该由模型随便编。

模型可以说明业务意图，但 key 的生成应该在 runtime 或业务服务里完成。

function buildIdempotencyKey(input: {
  userId: string;
  runId: string;
  toolName: string;
  businessObjectId: string;
}) {
  return [
    "agent",
    input.userId,
    input.runId,
    input.toolName,
    input.businessObjectId,
  ].join(":");
}

这里有取舍。

如果 key 绑定 runId，同一个 run 内 retry 安全，但跨 run 不会被当作同一业务动作。

如果 key 绑定用户和购物车，用户刷新后仍能恢复同一个下单动作，但要小心用户真的想再下一单。

幂等 key 是业务设计，不是随机字符串。

条件幂等要有检查函数

写文件工具可以设计成条件幂等。

执行前记录 base hash：

type FileWritePlan = {
  path: string;
  beforeHash: string;
  afterHash: string;
  patchRef: string;
};

恢复时检查：

async function canReplayFileWrite(plan: FileWritePlan) {
  const currentHash = await hashFile(plan.path);

  if (currentHash === plan.afterHash) {
    return { ok: true, action: "already_applied" as const };
  }

  if (currentHash === plan.beforeHash) {
    return { ok: true, action: "apply_again" as const };
  }

  return {
    ok: false,
    action: "conflict" as const,
    reason: "文件已被用户或其他工具修改",
  };
}

这才叫条件幂等。

没有 base hash 和 after hash，你只能靠感觉判断能不能重放。

MCP 工具也要重新分类

MCP Server 暴露的工具描述里可能写着 safe、read only、search。

Runtime 不能直接相信。

外部工具进入本地 Tool Registry 时，要重新分类：

function classifyMcpTool(tool: {
  name: string;
  description?: string;
  inputSchema: unknown;
}) {
  const text = `${tool.name} ${tool.description ?? ""}`.toLowerCase();

  if (/read|list|search|get/.test(text)) {
    return { idempotency: "idempotent", replayPolicy: "auto" };
  }

  if (/create|send|charge|delete|publish|merge|write/.test(text)) {
    return { idempotency: "non_idempotent", replayPolicy: "never" };
  }

  return { idempotency: "conditional", replayPolicy: "ask" };
}

真实实现还要看 server trust level、resource scope、用户授权、组织策略。

协议让工具更容易接入，不代表工具更安全。

给模型看的错误要明确

非幂等工具超时，不能只返回：

{ "error": "timeout" }

应该返回：

{
  "ok": false,
  "code": "SIDE_EFFECT_UNCERTAIN",
  "content": "create_issue 请求已发出，但响应超时。该工具可能已经创建 issue，不能自动重试。请先调用 get_issue_by_idempotency_key 或让用户确认。",
  "metadata": {
    "retryable": false,
    "idempotency": "non_idempotent"
  }
}

模型看到这条 observation，才知道下一步要查状态，不是继续创建。

Eval 要覆盖幂等性

幂等性不是写完类型就完事。

Eval 里要测：

read_file timeout 后允许 retry。
create_order timeout 后禁止 retry，返回 SIDE_EFFECT_UNCERTAIN。
write_file base hash 一致时可 replay。
write_file 文件已变更时进入 conflict。
PERMISSION_DENIED 后不可重放。
MCP create_issue 工具默认 non_idempotent。
run_command("ls") 可自动 replay。
run_command("npm publish") 禁止 replay。

这些 case 最好用 mock tool 做。不要拿真实支付、真实邮件、真实 issue tracker 测。

Runtime 的危险行为要能在本地复现。

最后

Agent 能不能恢复，很多时候取决于工具能不能安全重放。

能安全重放，就可以 retry、resume、replay。

不能安全重放，就要查状态、问用户、走补偿，或者直接停。

幂等性不是后端老概念的复读。到了 Agent Runtime 里，它变成工具系统的基础字段。

每个工具都要回答：

重复执行一次，会发生什么？

答不上来，就不要自动重试。

参考资料

• HTTP Semantics RFC 9110: Idempotent methods
• Stripe Docs: Idempotent requests
• AWS Builders Library: Making retries safe with idempotent APIs
• Google Cloud Docs: Retry strategy
• Model Context Protocol Docs: Tools

推荐阅读

• 如何实现 Agent Checkpoint？
• 从 Agent Loop 重构成 Agent Runtime
• LangGraph 到底是不是 Agent Runtime？