第 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.