邮件 Agent 如何留证并避免重复执行

邮件 Agent 最难处理的故障，往往发生在模型决定发送之后：邮件服务商已经接收请求，HTTP 响应却丢了。此时自动重试，可能把一封验证码邮件发成两封；只看 Agent 的最终回答，又无法确认到底发没发。

作者给出的办法是建立「证据队列」：把模型决策、实际请求和服务商回执分别保存。它讨论的重点是如何让一次有副作用的工具调用可追踪、可恢复。对准备把 AI 接入邮件流程的团队，这比继续打磨提示词更接近上线时的真实问题。

Agent 说已发送，为什么还不能算数

原文把邮件流程拆成几道边界：用户指令、Agent 决策、工具调用、邮件服务商，以及交付证据。每一道都可能单独失败。

例如，工具超时只能说明调用方没有按时拿到结果，不能证明服务商没有收到请求。worker 重启也一样：进程丢失了执行上下文，外部操作却可能已经生效。

因此，系统需要分别记录三个对象：

• 决策记录 Agent 想做什么，以及使用了哪个版本的指令。
• 动作记录发送给邮件适配器的规范化请求。
• 证据记录适配器返回的结果、外部标识和状态。

是否已经执行，必须由持久化记录回答，不能交给模型记忆。

作者给出的记录示例，把一次运行、其中一个发送步骤和外部回执关联起来：

{
  "run_id": "run_20261030_0822",
  "step_id": "send_01",
  "intent": "send_verification_email",
  "idempotency_key": "run_20261030_0822:send_01",
  "status": "accepted",
  "provider_message_id": "msg_abc123",
  "created_at": "2026-10-30T08:22:00Z"
}

关键是 idempotency_key 这一行：同一操作重试时，幂等键必须保持不变。每次生成新键，服务商就无法据此识别重复请求。run_id 则负责串起整次运行，step_id 定位具体动作。

还要分清证据的含义。这里的 accepted 表示服务商接受了请求，不能直接当作收件人已经收到邮件。原文没有展开后续投递状态如何跟踪。

队列真正要处理的是「不知道发没发」

作者认为，起步不必引入庞大的队列平台，一份事务记录加一个 worker 就能承接第一个场景。

下面这张表保存待执行请求、尝试次数和服务商返回的标识，为进程恢复提供依据：

CREATE TABLE email_steps (
  step_id text PRIMARY KEY,
  run_id text NOT NULL,
  idempotency_key text NOT NULL UNIQUE,
  payload jsonb NOT NULL,
  status text NOT NULL,
  provider_message_id text,
  attempts integer NOT NULL DEFAULT 0,
  next_attempt_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);

注意 idempotency_key 的唯一约束：它能阻止本地插入重复键，但还需要 worker 的并发控制和服务商的幂等机制配合，才能约束外部发送效果。

worker 领取一行记录，增加 attempts，再调用适配器；只有拿到能够保存的结果，才标记为 accepted。状态至少区分 pending、retryable、accepted、rejected、unknown，比一个成功布尔值更有用。

其中最关键的是 unknown。它承认系统暂时无法判断外部操作是否生效。

如果确认服务商已经接受，就不再发送；如果明确是接受之前的临时错误，就通过退避重试（backoff）安排下一次尝试；如果结果不明，就暂停并进入人工核查。操作人员查看服务商后台，再把动作关闭为 accepted 或 rejected。

原文提出，决定是否继续执行的条件必须是原子的，依据是稳定的幂等键与持久化状态。不过，具体如何领取记录、如何避免多个 worker 同时执行，以及如何处理外部接受后本地写入失败，文章没有给出完整实现。

这是一套处理原则，还不是可以直接复制上线的队列组件。

除了回执，还要留下哪些排障线索

模型输出合法 JSON，只能证明格式正确，不能证明这封邮件应该发送。作者要求在调用工具之前，用 schema 校验收件人、主题和正文；适配器还要拒绝意外字段、被禁止的域名，以及超出流程范围的动作。

排障信息也要覆盖整个执行过程。作者建议分别观测：

• 从决策到入队的耗时，以及每条 pending 记录的等待时长。
• 各服务商的重试率，以及 unknown 结果所占比例。
• 从动作开始到证据关闭的耗时，以及 schema 校验错误。

这些是建议采集的指标，原文没有提供实际测量值。

一次运行还应能串起决策、prompt 版本、所选工具、适配器响应和最终状态，无须保存每个 token。秘密信息应留在 prompts 和日志之外；邮件完整内容也只在确有需要时保存。

测试方面，作者提到可用 tempmailso 提供非生产环境的隔离邮箱。测试记录保存消息标识和测试结果即可。fixtures 或 QA 文档里的 temp mailid，也应与真实的 provider_message_id 明确区分，避免查错记录。

我的判断

我认可作者把「模型负责决策，系统负责证明」作为边界。邮件发送会产生外部效果，单靠聊天记录确实难以处理恢复和追责。

但文章没有给出吞吐量、重复发送率或故障恢复时间的对照数据。事务表加 worker 是否足够，仍是作者的经验之谈，取决于业务规模、服务商能力和团队运维条件。

尤其不能把本地唯一约束理解为外部操作只执行一次的保证。服务商是否支持幂等键、支持多久、能否查询历史结果，原文都没说清。缺少这些能力，证据队列仍能暴露不确定性，却未必能自动消除它。

与直接在工具调用外包一层重试相比，这套方案更适合需要核查发送结果的流程；代价是增加状态管理和人工处置。它的价值在于让故障有去处，而不是承诺故障不会发生。

能拿来做什么

• 如果正在用 Node 实现邮件 Agent，可以先把发送请求持久化，再由 worker 执行，并让同一动作在恢复和重试时复用幂等键。
• 给邮件工具定义输入、输出 schema，同时在适配器里落实字段、域名和动作范围校验，避免只依赖提示词约束。
• 把「服务商接受请求后响应超时」加入故障测试，检查 worker 恢复时是否沿用原记录，以及结果不明时是否进入 unknown。
• 如果要做运维页面，优先提供按 run_id 查看执行链路、筛选 unknown 和人工关闭记录的能力，让异常邮件有明确的处理入口。