第 76 天：Agent 运行状态、检查点与幂等副作用

01 120 分钟

Agent 运行状态机与动作/观测轨迹

Agent 辅助工程检查

前置要求

第 73-75 天的 Agent 循环与工具协议学习，以及 Ticket 22 的有界 Agent 项目（projects/agent_learning）。

学习目标

识别有界 Agent 所携带的完整运行状态——动作/观测轨迹、步数计数器与重试计数器——并枚举其三种合法终止状态：goal_reached、tool_failure、step_budget。

操作指引

1. 打开 projects/agent_learning/agent.py 阅读 run_task。
- 每次运行的可变状态：trace（{action, observation} 对的只追加列表）、retries（ok=false 的观测计数）、隐式步数计数器 len(trace)。
- 终止迁移：write_report 返回 ok=true -> status=completed, termination=goal_reached；retries 超过 max_retries(=2) -> status=failed, termination=tool_failure；两者皆未发生而循环结束 -> status=budget_exhausted, termination=step_budget。
2. 注意被刻意省略的内容：没有思维链字段，也没有隐藏草稿板——轨迹就是全部持久化状态（project.json 的 evidence.forbidden_fields 列出 thought 与 chain_of_thought）。
3. 与生产级检查点机制对比：LangGraph 的 checkpointer 在每个超步持久化图状态；Temporal 通过重放事件历史重建状态。我们的轨迹正是同一思想的最小事件日志。
4. 运行 python -m projects.agent_learning.cli evaluate --fixture summarize-notes --output /tmp/agent-run.json，检查 result.status 与 result.termination。

自主演练与记录

先预测正常运行四步轨迹，再执行 CLI 并标注每步迁移（提出动作 -> 记录观测 -> 更新计数器）。确认运行以 steps=4、retries=0、termination=goal_reached 结束。

标记为已完成

独立掌握标准

不运行代码即可说出：失败观测时递增的计数器（retries）、结束健康运行的上限（max_steps=6）、唯一成功即提前终止的动作（write_report）。

权威源资源与权利证明

linking MIT (LangGraph project) / documentation site terms

LangGraph Persistence: Checkpoints, Threads, and State Snapshots

作者 / 机构: LangChain / LangGraph Documentation Team | 原始出处链接 ↗

对应章节 / 时间戳: Persistence: Checkpointer vs. store (checkpoints keyed by thread_id); the page now redirects to docs.langchain.com

验证版本与日期: LangGraph documentation (Verified: 2026-10-30)

入选理由:

Primary reference for agent-run checkpointing: LangGraph checkpointers persist graph state at every super-step so interrupted runs resume from the last committed snapshot, the production analogue of this project's action/observation trace.

来源前置条件:

Agent loop fundamentals, tool calling, and JSON state serialization.

安全回退方案（离线弹性）:

The checkpoint/replay exercise is implemented directly against the projects/agent_learning trace JSON; no framework installation is required.

对比候选资源与选型分析 (2)

Temporal Durable Execution documentation ↗ compared_alternative [MIT / documentation terms]

Temporal persists event histories for replay-based recovery of arbitrary workflows; LangGraph targets agent graphs specifically and stays closer to the learner's tool-loop mental model.

OpenAI Agents SDK session/state documentation ↗ compared_alternative [MIT / documentation terms]

Provider-scoped SDK sessions; LangGraph's explicit checkpoint model exposes the underlying state-transition semantics more transparently.

linking Temporal Technologies copyright (documentation; Temporal server code is MIT) / documentation site terms

Temporal Documentation: Durable Execution and Event History Replay

作者 / 机构: Temporal Technologies Documentation Team | 原始出处链接 ↗

对应章节 / 时间戳: What is Temporal?: Durable Execution

验证版本与日期: Temporal documentation (Verified: 2026-10-30)

入选理由:

Standard industrial reference for durable execution: workflow state is rebuilt by replaying a persisted event history through deterministic code, exactly the checkpoint/replay mechanism learners reproduce against the agent trace.

来源前置条件:

State machines, event logs, and deterministic replay concepts.

安全回退方案（离线弹性）:

Replay semantics are exercised offline against the deterministic adapter; Temporal itself is never installed.

对比候选资源与选型分析 (2)

LangGraph Persistence documentation ↗ compared_alternative [MIT / documentation terms]

Agent-specific checkpointing; Temporal supplies the general event-sourced replay model that motivates the exercise.

Cadence workflow documentation ↗ compared_alternative [MIT / documentation terms]

Temporal's predecessor with equivalent replay semantics; Temporal's docs are more actively maintained.

02 120 分钟

检查点与重放：从持久化轨迹重建运行状态

独立掌握检查（无 AI 辅助）

前置要求

第 76 天活动 1 的运行状态模型；JSON 序列化。

学习目标

将运行轨迹持久化为 JSON 检查点，并证明确定性重放：把每个已记录前缀喂回 adapter.next_action，能够精确重现已记录的动作。

操作指引

1. 设计检查点文档：{'task_id': 'summarize-notes', 'steps': 4, 'retries': 0, 'trace': [...]}，写入 run_checkpoint.json。
2. 实现 replay(trace_prefix, adapter)：返回 adapter.next_action(list(trace_prefix))。由于 DeterministicModelAdapter 仅凭历史选择下一动作，重放前缀 k 必然产出 trace[k].action。
3. 对 0..steps-1 的每个 k 验证。这是事件溯源恢复的微缩版：state = fold(history)，与 Temporal 为 durable execution 记录的恢复形态一致。
4. 记录诚实的局限：重放重建的是适配器的决策状态，并不回滚外部副作用——report.txt 依然保持已写入，因为文件存在于轨迹之外。

自主演练与记录

实现 save_checkpoint(result, path) 与 replay(trace_prefix, adapter)。对正常运行的每个 k 断言 replay(trace[:k]) == trace[k]['action']，再对 invalid_arguments 故障运行（5 步）重复验证。

标记为已完成

独立掌握标准

演示从检查点前缀逐一重放出全部已记录动作，并指出一条现实限制：轨迹之外的副作用不会被回滚。

权威源资源与权利证明

linking Temporal Technologies copyright (documentation; Temporal server code is MIT) / documentation site terms

Temporal Documentation: Durable Execution and Event History Replay

作者 / 机构: Temporal Technologies Documentation Team | 原始出处链接 ↗

对应章节 / 时间戳: What is Temporal?: Durable Execution

验证版本与日期: Temporal documentation (Verified: 2026-10-30)

入选理由:

Standard industrial reference for durable execution: workflow state is rebuilt by replaying a persisted event history through deterministic code, exactly the checkpoint/replay mechanism learners reproduce against the agent trace.

来源前置条件:

State machines, event logs, and deterministic replay concepts.

安全回退方案（离线弹性）:

Replay semantics are exercised offline against the deterministic adapter; Temporal itself is never installed.

对比候选资源与选型分析 (2)

LangGraph Persistence documentation ↗ compared_alternative [MIT / documentation terms]

Agent-specific checkpointing; Temporal supplies the general event-sourced replay model that motivates the exercise.

Cadence workflow documentation ↗ compared_alternative [MIT / documentation terms]

Temporal's predecessor with equivalent replay semantics; Temporal's docs are more actively maintained.

linking MIT (LangGraph project) / documentation site terms

LangGraph Persistence: Checkpoints, Threads, and State Snapshots

作者 / 机构: LangChain / LangGraph Documentation Team | 原始出处链接 ↗

对应章节 / 时间戳: Persistence: Checkpointer vs. store (checkpoints keyed by thread_id); the page now redirects to docs.langchain.com

验证版本与日期: LangGraph documentation (Verified: 2026-10-30)

入选理由:

Primary reference for agent-run checkpointing: LangGraph checkpointers persist graph state at every super-step so interrupted runs resume from the last committed snapshot, the production analogue of this project's action/observation trace.

来源前置条件:

Agent loop fundamentals, tool calling, and JSON state serialization.

安全回退方案（离线弹性）:

The checkpoint/replay exercise is implemented directly against the projects/agent_learning trace JSON; no framework installation is required.

对比候选资源与选型分析 (2)

Temporal Durable Execution documentation ↗ compared_alternative [MIT / documentation terms]

Temporal persists event histories for replay-based recovery of arbitrary workflows; LangGraph targets agent graphs specifically and stays closer to the learner's tool-loop mental model.

OpenAI Agents SDK session/state documentation ↗ compared_alternative [MIT / documentation terms]

Provider-scoped SDK sessions; LangGraph's explicit checkpoint model exposes the underlying state-transition semantics more transparently.

03 120 分钟

幂等工具副作用与“恰好一次”错觉

Agent 辅助工程检查

前置要求

第 76 天活动 1-2；write_report 载荷契约。

学习目标

解释为何重发 write_report 是安全的——其副作用幂等——并与需要去重键或唯一约束的非幂等副作用（追加、扣费）对比。

操作指引

1. 幂等副作用：以相同内容两次应用 write_report，report.txt 状态不变——通过对每次调用后的文件做哈希来验证。
2. 非幂等反例：append_note 工具在重试下会重复写入行；charge_card 副作用会重复扣费——这正是 Stripe 用幂等键解决的故障模式。
3. 预算视角：至少一次投递（重试）+ 幂等副作用 = 等效的恰好一次结果。但重试会在系统降级时放大负载（SRE 级联故障模型），因此即使重试安全，预算也必须有限。
4. 为每个项目工具分类：list_notes（只读，幂等）、read_note（只读，幂等）、write_report（覆盖写，按内容一致而幂等）。

自主演练与记录

现场验证幂等性：用相同内容两次调用 _tool_call 的 write_report，每次调用后对 report.txt 做哈希。然后设计一个 append_note 工具及恢复安全性的去重键（filename+content 的 sha256）。

标记为已完成

独立掌握标准

能将副作用分类为幂等/非幂等，并说出让各自在重试下安全的机制（去重键、唯一约束或覆盖语义）。

权威源资源与权利证明

linking Stripe site content / linked reference noncommercial

Stripe API Documentation: Idempotent Requests

作者 / 机构: Stripe, Inc. | 原始出处链接 ↗

对应章节 / 时间戳: Idempotent requests (Idempotency-Key header; keys can be removed after at least 24 hours)

验证版本与日期: Stripe API documentation (Verified: 2026-10-30)

入选理由:

Standard production definition of idempotency keys: Stripe guarantees safe client retries by deduplicating POST requests on a caller-supplied key, the exact mechanism that turns at-least-once retries into effectively-once effects.

来源前置条件:

HTTP APIs, retries, and side-effect semantics.

安全回退方案（离线弹性）:

Idempotency semantics are demonstrated locally with repeated write_report calls and a sha256 dedupe key, no Stripe account needed.

对比候选资源与选型分析 (2)

IETF draft: The Idempotency-Key HTTP Header Field ↗ compared_alternative [IETF Trust / open access]

Standardization-track header specification; Stripe's live documentation is the more concrete deployed example.

AWS Builder's Library: Making retries safe with idempotent APIs ↗ compared_alternative [Amazon site content]

Deep design treatment of idempotent server design; Stripe provides the tighter client-visible contract cited in the exercise.

linking CC BY-NC-ND 4.0 noncommercial no-derivatives

Site Reliability Engineering, Chapter 22: Addressing Cascading Failures

作者 / 机构: Mike Ulrich, in Site Reliability Engineering (eds. Betsy Beyer, Chris Jones, Jennifer Petoff, Niall Richard Murphy; Google) | 原始出处链接 ↗

对应章节 / 时间戳: Preventing Server Overload: Retries

验证版本与日期: O'Reilly 2016 free online edition (Verified: 2026-10-30)

入选理由:

Primary analysis of how unbounded retries amplify partial outages into cascading failures, motivating hard retry budgets and deadlines in agent runtimes.

来源前置条件:

Retries, queueing, and load-shedding basics.

安全回退方案（离线弹性）:

The retry-amplification scenario and budget arithmetic are fully reproduced in the lesson's worked example.

对比候选资源与选型分析 (2)

Release It! (Michael Nygard) - Stability patterns ↗ compared_alternative [Commercial book]

Broader stability-pattern catalog (circuit breakers, bulkheads); the SRE chapter is free and directly quantifies retry amplification.

AWS Builder's Library: Timeouts, retries, and backoff with jitter ↗ compared_alternative [Amazon site content]

Strong companion article; the SRE chapter frames the failure mode (cascading overload) that the retry budget defends against.

04 120 分钟

评估：运行状态迁移审计与台账校验

独立掌握检查（无 AI 辅助）

前置要求

第 76 天活动 1-3。

学习目标

构建审计函数，从轨迹重新推导任何已记录运行的终止状态并标记非法迁移，然后在全部四次观测到的运行上加以验证。

操作指引

1. audit_run(result) -> {'steps': int, 'retries': int, 'status': str, 'termination': str, 'violations': []}。
2. 规则：steps <= max_steps(6)；retries <= max_retries+1(3)，且 retries>2 必须对应 status='failed'/termination='tool_failure'；status='completed' 要求最后一个动作为 write_report 且观测 ok；status='budget_exhausted' 要求 steps==6 且无终止成功。
3. 输入正常运行与全部三条故障轨迹，断言期望的 (status, termination) 对。
4. 故意损坏一条轨迹（例如清掉 write_report 观测的 ok 标志），证明审计会标记不匹配，而不是盲信声明的 status 字段。

自主演练与记录

实现 audit_run，为每次已记录运行输出一行 JSON 台账。确认台账重现：completed/goal_reached（4 步）、completed/goal_reached（5 步、1 次重试）、failed/tool_failure（3 步、3 次重试）、budget_exhausted/step_budget（6 步、0 次重试）。

标记为已完成

独立掌握标准

提交一份迁移审计：其推导判定与全部已记录运行一致，并在故意损坏的轨迹上触发违规标记。

权威源资源与权利证明

linking MIT (LangGraph project) / documentation site terms

LangGraph Persistence: Checkpoints, Threads, and State Snapshots

作者 / 机构: LangChain / LangGraph Documentation Team | 原始出处链接 ↗

对应章节 / 时间戳: Persistence: Checkpointer vs. store (checkpoints keyed by thread_id); the page now redirects to docs.langchain.com

验证版本与日期: LangGraph documentation (Verified: 2026-10-30)

入选理由:

Primary reference for agent-run checkpointing: LangGraph checkpointers persist graph state at every super-step so interrupted runs resume from the last committed snapshot, the production analogue of this project's action/observation trace.

来源前置条件:

Agent loop fundamentals, tool calling, and JSON state serialization.

安全回退方案（离线弹性）:

The checkpoint/replay exercise is implemented directly against the projects/agent_learning trace JSON; no framework installation is required.

对比候选资源与选型分析 (2)

Temporal Durable Execution documentation ↗ compared_alternative [MIT / documentation terms]

Temporal persists event histories for replay-based recovery of arbitrary workflows; LangGraph targets agent graphs specifically and stays closer to the learner's tool-loop mental model.

OpenAI Agents SDK session/state documentation ↗ compared_alternative [MIT / documentation terms]

Provider-scoped SDK sessions; LangGraph's explicit checkpoint model exposes the underlying state-transition semantics more transparently.

linking Stripe site content / linked reference noncommercial

Stripe API Documentation: Idempotent Requests

作者 / 机构: Stripe, Inc. | 原始出处链接 ↗

对应章节 / 时间戳: Idempotent requests (Idempotency-Key header; keys can be removed after at least 24 hours)

验证版本与日期: Stripe API documentation (Verified: 2026-10-30)

入选理由:

Standard production definition of idempotency keys: Stripe guarantees safe client retries by deduplicating POST requests on a caller-supplied key, the exact mechanism that turns at-least-once retries into effectively-once effects.

来源前置条件:

HTTP APIs, retries, and side-effect semantics.

安全回退方案（离线弹性）:

Idempotency semantics are demonstrated locally with repeated write_report calls and a sha256 dedupe key, no Stripe account needed.

对比候选资源与选型分析 (2)

IETF draft: The Idempotency-Key HTTP Header Field ↗ compared_alternative [IETF Trust / open access]

Standardization-track header specification; Stripe's live documentation is the more concrete deployed example.

AWS Builder's Library: Making retries safe with idempotent APIs ↗ compared_alternative [Amazon site content]

Deep design treatment of idempotent server design; Stripe provides the tighter client-visible contract cited in the exercise.