Harness 理論篇 Part 11｜可觀測性與營運：如何看懂 Agent 發生了什麼？

假設一個退款 Agent 接到任務：找出一筆狀態不一致的退款，核對訂單、付款供應商與稽核紀錄，必要時建立修復工單。

幾分鐘後，畫面只留下兩行訊息：

Run failed.
Tool execution error.

營運人員現在還不知道：

問題發生在哪一個 Turn？
Agent 當時拿到哪一版 Context 與 Policy？
哪個 Tool Call 失敗，參數是否合法？
Tool 是真的失敗，還是回應遺失但副作用已經發生？
Agent 為什麼重試？重試了幾次？
哪個 Worker 消耗最多時間與成本？
Verifier 是否執行？為什麼沒有攔下問題？
這次異常是否只出現在某個 Model、Prompt、Tool 或 Config Version？

只有最終錯誤訊息，這些問題都答不出來。

Agent 的一次任務可能跨過 Model Call、Retrieval、Tool、Approval、Worker、Background Job、Verifier 與多次狀態轉移。要營運這種系統，不能只記一條 HTTP Request Log，也不能只看 Token 數與最後答案。

需要的是一條能把 Intent、Decision、Action、Evidence、Version 與 Outcome 關聯起來的證據鏈。

Agent causal evidence graph

Figure 11-1｜穩定 Domain ID、Trace Context 與 Causal Link 串起 Thread、Turn、Run、Worker、Operation、State、Audit 與 Evidence，而不是假設所有事件形成一棵樹。

Observability 回答「發生了什麼」，不負責宣布「做得好」

Part 10 已經區分 Quality Control 與 Evaluation。Observability 位於另一層。

Quality Control 決定這一次 Run 能不能通過。
Evaluation 衡量一套 Agent System 在多個 Case、Trial 與版本上的表現。
Observability 收集、關聯與查詢執行訊號，讓人與系統能定位、比較、調查與重建。
Canonical State 決定 Run 現在處於哪個合法狀態。
Audit Record 保存需要被追責、合規或事後證明的關鍵決策與操作。

這五者會引用同一批 ID，但不能互相取代。

問題	主要責任
這次 Tool Call 發生了什麼？	Observability
Run 現在是 `running`、`paused` 還是 `failed`？	Canonical RunState
哪個 Actor 在哪版 Policy 下批准了操作？	Audit Record
這次輸出是否符合 Completion Contract？	Quality Control
這個版本在退款任務上的通過率是否退步？	Evaluation

Trace 可以顯示 Verifier 回傳了什麼，卻不能自動決定 Verifier 是否可信。Metric 可以顯示通過率下降，卻不能替團隊定義可接受品質。

更重要的是，Telemetry 可能被 Sample、延遲送達、Export 失敗或依 Retention Policy 刪除。需要作為狀態權威或不可繞過稽核證據的資料，不能只存在 Best-effort Trace Pipeline。

因此：

Observability 是證據介面，不是狀態資料庫、品質裁判或合規賬本。

把「看得到」和「判得對」混成一件事，Dashboard 很容易變成一台昂貴的自信製造機。

傳統 Request Log 為什麼不夠

一般 Web Service 常用一個 Request ID 串起 Gateway、Application 與 Database。Agent Run 的生命週期更長，也更容易分岔。

一次使用者要求可能包含：

建立或恢復 Thread
啟動 Turn
組裝 Context
呼叫 Model
發現需要 Tool
等待 Approval
Tool 在另一個 Worker 或外部服務執行
回傳 Observation
Model 重新規劃
啟動 Background Work
執行 Verification
產生 Artifact 與 Terminal Status

其中任何一步都可能 Retry、Pause、Reconnect、Fork、Timeout 或轉交另一個 Agent。

若所有內容只被壓成：

POST /agent/run 500 18423ms

這條 Log 可以證明 Request 失敗，也能顯示耗時。它無法證明是哪個 Tool、哪個 Turn、哪一版 Policy 或哪個副作用出了問題。

OpenAI Codex App Server 將互動拆成 Thread、Turn 與 Item，並持續串流狀態與事件。這種 Protocol Model 本身就是 Observability 的重要基礎，因為一次 Client Request 可能產生多個有序事件，而不是一個單一 Response。¹

Runtime Observability 與 Process Observability 是兩種真相

Agent Harness 需要同時觀察系統執行與任務決策。

Runtime Observability

回答系統層問題：

Service 是否可用？
Queue 是否阻塞？
Model 與 Tool Latency 在哪裡增加？
Dependency 回傳什麼 Error？
CPU、Memory、Connection Pool 與 Worker Saturation 如何？
External Side Effect 是否真的發生？
Retry、Timeout 與 Recovery 是否依 Policy 執行？

這一層延續傳統分散式系統的 Logs、Metrics 與 Traces。Google SRE 將 Latency、Traffic、Errors 與 Saturation 列為常用的四個 Golden Signals；Agent Runtime 仍然需要這些基本訊號。²

Process Observability

回答任務與控制層問題：

Agent 收到什麼 Goal、Scope 與 Completion Contract？
它採用了哪個 Plan？
為什麼選這個 Tool？
哪個 Policy Decision 允許或阻擋操作？
Retry、Fallback、Escalation 的理由是什麼？
哪些 Evidence 支持完成判定？
哪一輪開始偏離原始目標？
人類在哪個 Gate 介入？

Process Observability 不要求保存模型的私密推理。系統應記錄可觀察的 Input、Decision、Action、Result、Evidence 與 State Transition，而不是把不可依賴的內部思考文字當成事實來源。

一條完整的 Task Trace 可以表示為：

Intent
→ Contract and policy
→ Context and plan
→ Model decision
→ Tool or action
→ Runtime evidence
→ Verification
→ Repair or escalation
→ Completion or stop

只有 Runtime Observability，團隊可能知道 Tool Timeout，卻不知道 Agent 為什麼呼叫它。只有 Process Observability，團隊可能看懂 Plan，卻不知道 External API 已經回傳 429 或 Database Connection Pool 已飽和。

兩條線要在同一個 Trace 裡會合。

Correlation Model：Agent 工作通常是一張因果圖，不是一棵整齊的樹

Agent Telemetry 最先要解決的不是 Dashboard，而是 Identity、Scope 與 Causality。

Thread、Turn 與 Item 描述互動 Protocol；Task、Run、Worker 與 Operation 描述執行；Trace／Span 描述一次觀測視圖。它們不是同一套階層，也不應被硬塞進一個萬用 ID。

一個常見關係可以表示為：

Tenant / Actor
        │
      Task
        │
     Thread ── contains ── Turn ── contains ── Item
        │                    │
        └──── linked to ─── Run
                             │
                    fan-out / fan-in
                   ┌─────────┼─────────┐
                Worker A  Worker B  Background Work
                   │         │           │
                Model      Tool       Completion Event
                   └─────────┴──── causal links ─────┘
                             │
                    Verification / Artefact

Stable identity 和 trace context 各有責任

常見欄位包括：

tenant_id
actor_id 或 delegated principal
task_id
thread_id
turn_id
run_id
item_id
trace_id／span_id
worker_id／worker_role
tool_call_id
approval_id
checkpoint_id
artifact_id
operation_id
work_id
event_id

trace_id 適合串起一次觀測範圍，不必成為業務或 Runtime 的永久 Primary Key。能跨 Trace、跨重啟或跨 Retention Window 存活的工作，應有自己的 Stable Domain ID。

Parent／Child 以外還需要 Link

以下情況通常不是單純 Parent／Child：

一個 Coordinator 同時派出多個 Worker
多個 Worker 結果匯入同一個 Synthesis
Background Work 在原 Turn 結束後才完成
Retry 建立新的 Attempt，但仍屬於同一 Logical Operation
A2A 或 Queue 跨 Process 傳遞工作
Verification 同時讀取多個 Artefact 與 External State

這些關係應使用明確 Link，例如：

caused_by
continues
retries
forked_from
produced
verified_by
supersedes

跨 Process、Queue、Background Worker 或 Agent Message 時，應傳遞 Trace Context，並同時保留 Stable Domain ID。只靠相近 Timestamp 猜關係，不叫 Correlation，比較像事故現場的星座連線。

Telemetry Contract 要分清 Signal、Cardinality、Sampling 與 Audit

隨意命名的 Span 可以先工作，但很快會產生：

agent_call
agent_request
llm_run
model_execution_v2
call_agent_final

五個名稱可能代表同一 Operation，也可能具有不同邊界。

OpenTelemetry 的核心 Semantic Conventions 在 2026 年 7 月為 1.43.0；GenAI Conventions 已移至獨立 Repository，而 Agent／Framework 相關 Convention 仍有多項標示為 Development。實作應 Pin 使用的 GenAI Convention Revision、Instrumentation Version 與內部 Mapping，不能只寫「我們符合 OTel」。³⁴

Span、Event／Log、Metric 與 Audit Record 不同

Signal	適合回答	不適合承擔
Span／Trace	一次 Operation 的邊界、耗時、因果與依賴	永久 State Authority
Event／Log	某個離散事實、狀態改變、錯誤與診斷	高頻聚合趨勢
Metric	聚合率、分布、容量、SLO 與趨勢	單一 Run 的完整歷史
Audit Record	需要追責的 Actor、Decision、Operation 與 Evidence Reference	大量除錯內容
Artefact／Payload Vault	大型輸出、敏感證據與可控內容	直接當 Dashboard Label

OpenTelemetry 在 2026 年也開始將新的事件慣例逐步轉向 Log-based Events，而不是把所有離散事件都塞成 Span Event。這不會讓既有資料失效，但提醒實作者不要把 UI 中的一種 Timeline 表示法當成永久 Signal Contract。⁵

一個最小 Tool Span 可以包含：

{
  "schema_version": "agent-telemetry-2.0",
  "semantic_convention": "otel-genai@pinned-revision",
  "trace_id": "tr_8a1f",
  "span_id": "sp_42",
  "span_type": "tool.execute",
  "task_id": "refund-reconcile-204",
  "run_id": "run_8a1f",
  "worker_role": "refund-investigator",
  "tool_name": "payment.lookup_refund",
  "tool_version": "3.4.0",
  "operation_id": "op_771",
  "policy_decision_id": "pd_19",
  "status": "error",
  "error_class": "dependency_timeout",
  "effect_state": "unknown",
  "latency_ms": 3120,
  "content_recording": "metadata_only",
  "redaction_class": "payment_restricted"
}

這段能說明觀測身分、版本、結果與資料政策。它不能證明 Tool Result 正確，也不能證明 Span 成功送達 Collector。

高 Cardinality 資料不要塞進 Metric Label

run_id、user_id、完整 Tool Argument、Prompt Digest 或每個 Artifact ID 適合放在 Trace、Log、Billing Record 或 Exemplars，不適合直接成為無界 Metric Label。

Metric Label 應使用受控維度，例如：

bounded model family
worker role
tool class
status class
tenant tier
deployment version
risk class

否則時序資料庫會先替你示範一次資源飽和 Incident。

Sampling 與 Audit Retention 要分開

Trace Sampling 可以依：

Error／Unknown Outcome
High-risk Operation
SLO Breach
High Latency／Cost
Rare Path
Random Baseline

採 Head 或 Tail-based Sampling。

但以下資料通常不能因 Trace 未被抽中就消失：

Approval／Denial
Credential／Policy Change
External Side-effect Operation ID
Completion Decision
Security Incident
Required Compliance Record

這些應進 Durable Audit／State Path，再由 Trace 引用。

內容預設不應全量保存

Prompt、Tool Arguments、Retrieved Documents 與 Tool Results 可能包含個資、Secret、Payment Data、Source Code 或跨 Tenant 資料。

較安全的策略是：

Metadata by default
Content opt-in
Field-level Redaction
Sensitive Payload 進獨立 Vault，以 Reference 連結
Tenant-aware Access Control
Purpose-bound Access
Retention Class 與 Legal Hold
Trace Access Audit
Region／Encryption Policy
Redaction Failure Alert

不要為了 Debug 直接把完整 Prompt 永久塞進每個 Span。Observability 不應在半夜悄悄長成第二套資料湖。

Trace 要回答因果、等待與狀態改變

一條有用的 Agent Trace 至少要覆蓋：

Request／Run Start
Policy Resolution
Context Build
Model Call
Retrieval
Tool Proposal、Authorisation、Execution 與 Result
Approval Wait 與 Decision
Retry、Fallback 或 Recovery
Background Acceptance、Completion 與 Delivery
Checkpoint／Resume
Verification
State Transition
Artefact Creation
Terminal Status 與 Stop Reason

OpenAI Agents SDK 目前會為 Run、Agent、Model Generation、Function Tool、Guardrail 與 Handoff 建立 Trace／Span。Codex 也公開了 Turn、Tool、Approval、MCP、Hook 與 Multi-agent 相關的 OTel Metrics。這些產品例子證明 Agent Observability 已超過單一 Model Request，但它們的欄位形狀仍是產品實作，不是所有 Harness 的 Universal Schema。⁶⁷

Agent causal trace timeline

Figure 11-2｜同一個 Run 應能同時用 Span Tree 觀察依賴與耗時，用 Event Timeline 觀察順序、等待與狀態變更，並以 Causal Link 串起非樹狀工作。

Span Tree 與 Event Timeline 各有用途

Span Tree 適合看：

巢狀 Operation
Inclusive／Exclusive Latency
Dependency Chain
Fan-out Worker
外部 Service 耗時

Event Timeline 適合看：

Approval 等待
Queue Delay
Reconnect Catch-up
Pause／Resume／Cancel
Background Completion Delivery
Policy 或 Config 變更前後的順序

底層應共享 Stable ID 與 Causal Link，不應由兩套互不相干的 Instrumentation 各畫各的宇宙。

Timestamp 不能單獨建立因果

分散式事件可能因 Clock Skew、Batch Export、Queue 或網路延遲而晚到。只按 Wall-clock Timestamp 排序，可能把 Result 畫在 Request 前面。

Event Contract 應保留：

globally unique event_id
stream-scoped monotonic sequence
occurred_at
observed_at／ingested_at
parent span 或 causal links
attempt／generation
event／payload version
terminal status
acknowledgement／delivery state

不要宣稱整個分散式系統存在一個完美 Global Sequence。較實際的做法是對 Thread、Run、Work Unit 或 Event Stream 維持局部順序，再用 Link 組出 Partial Order。

Trace Gap 也必須可見

Instrumentation 會壞、Collector 會掉資料、Sampling 會省略 Span。若 UI 直接把缺口折疊掉，使用者會誤以為中間沒有發生任何事。

Trace Viewer 應能標示：

missing parent
incomplete export
sampling boundary
clock uncertainty
redacted payload
unavailable artefact
instrumentation version change

「沒有 Span」只能證明目前沒有 Span，不能證明 Operation 沒有發生。

Metrics 要從服務健康一路連到任務結果

Agent Dashboard 不應只顯示 Total Tokens。至少要分成四組指標。

Service Metrics

Availability
Queue Time
Turn Latency
Time to First Model Item
Model／Tool Latency
Error Rate
Saturation
Recovery Time
Event Export／Collector Health

Process Metrics

Turns per Task
Tool Calls per Task
Retry／Repair Iterations
Approval Wait Time
Human Intervention Rate
Context Growth
Goal Drift／Escalation Count
Background Work Completion Delay
Result Delivery／Acknowledgement Delay

Quality Evidence Metrics

Verified Completion Rate
Evidence Completeness
Verifier fail／needs_review／unresolved
Correction／Rejection Rate
Unsafe Action Attempt
Duplicate Side Effect
Completion Decision Latency

這些是 Observability Signal，不是 Quality Authority。Turns 變少可能代表流程有效，也可能代表 Agent 太早停止；Verifier Failure 上升也可能是 Verifier Version 改變。

Economic Metrics

Cost per Run
Cost per Verified Successful Task
Wasted Retry Cost
Evaluator Overhead
Human Review Minutes
Retrieval／Tool Data Volume
Artefact Storage Cost
Telemetry Collection Cost

「平均每次 Request 成本」對 Agent 往往沒有足夠解釋力。更好的分母通常是 Eligible Task、Verified Successful Task 或已完成的 Business Unit。

Metric 需要 Definition，不只需要名稱

每個重要 Metric 應保存：

Numerator
Denominator
Eligible Population
Window
Aggregation
Unit
Missing／Late Data Policy
Version
Owner

verified_completion_rate 若沒有說明哪些 Task Eligible、needs_review 怎麼計算、Decision 可延遲多久，圖表再平滑也無法比較。

用 Exemplars 把聚合數字連回 Trace

Metric Label 應維持 Bounded Cardinality。需要從 P95 Spike 找到具體 Run 時，可以使用 Exemplars、Trace Link 或查詢索引，而不是把每個 run_id 直接放進 Time Series。

Metric 告訴你「哪裡可能有問題」，Trace 與 Evidence Record 才幫你回答「是哪一批 Run、哪一個 Operation、哪一版 Contract」。

Multi-agent Attribution 要避免重複計費與時間幻覺

Coordinator、Research Worker、Tool Worker、Reviewer 與 Evaluator 的成本不能全部揉成一個總數，也不能把所有 Worker Duration 直接相加後稱為 End-to-end Latency。

每個 Worker 至少應獨立記錄：

Role
Model／Profile
Input、Output、Reasoning 與 Cached Tokens
Queue、Wall-clock、Active、Idle 與 Tool Latency
Tool Call 與 Raw Data Volume
Retry／Repair Iteration
Artefact Bytes
Outcome Status
Direct Monetary Cost

還要區分：

End-to-end wall-clock：使用者實際等待多久。
Summed worker time：所有 Worker 活躍時間加總。
Critical-path time：真正決定完成時間的路徑。
Inclusive cost：包含 Child Work 的成本。
Exclusive cost：只屬於目前 Worker 的成本。
Shared cost allocation：共同 Context Build、Cache、Coordinator 或 Verifier 成本如何分攤。

若 Coordinator Span 已包含 Child Span，而 Billing 又把兩者都算一次，Dashboard 會產生一個成本複製機。

Per-worker Attribution 應回答：

哪個 Worker 重複讀取同一份 Context？
Parallelism 真的縮短時間，還是只增加總成本？
哪個 Role 位於 Critical Path？
Reviewer 是否反覆要求沒有價值的修改？
哪些 Worker 可以改用較便宜的 Model？
哪個 Worker 產生了可驗證的 Artefact 或 Evidence？

成本比較必須使用相同 Task、Completion Contract 與 Verification Rigor。便宜的 Worker 若只是更早放棄，不是一個更有效率的 Worker。

Replay 不是一個按鈕，它至少有三種語意

「Recorded Reconstruction」很容易讓人誤以為模型與外部世界可以被精確重現。對多數 Agent System，更誠實的名稱是 Recorded Reconstruction、Controller Replay 與 Sandbox Re-execution。

Recorded Reconstruction

使用保存的 Event、Result Summary、State Snapshot 與 Artefact Reference 重建原始 Timeline。

用途：

Incident Investigation
UI Playback
Decision／Evidence Review
檢查當時已知狀態

它不重新呼叫 Model 或外部系統，也不能證明當時每個未被記錄的細節。

Controller／Mocked Replay

重新跑 Controller、Workflow 或 Agent Loop，但以錄製的 Model／Tool Result 或 Test Double 取代外部依賴。

用途：

重現 Retry／Approval／Failure Branch
驗證 State Transition
測試 Client／UI Event Handling
比較 Controller Version

Replay Engine 應檢查：

Recorded Input Schema
Tool／Model Adapter Version
Event Ordering
Missing／Redacted Payload
Unsupported Historical Event
Expected Determinism Boundary

若 Controller 讀到今天的 Policy 或最新 Tool Catalog，這已經不是同一個 Replay Contract。

Sandbox Re-execution

在新的隔離 Environment 重新執行相同 Task 或部分 Step。

用途：

驗證修復
比較 Harness Version
執行 Regression Trial
重現 Dependency Interaction

需要處理：

Snapshot／Fixture
Pinned Version
Credential Scope
Time／Randomness Control
Idempotency
External Side-effect Suppression
Unknown Outcome Reconciliation
Output Comparison

付款、寄信、刪除或部署不能因為按下 Replay 就再次發生。若外部 Effect 狀態未知，先向真正的 Authority Reconcile，再決定是否允許新的 Operation。

Replay 結果也需要標籤：

recorded_reconstruction
controller_replay
sandbox_reexecution
diverged
incomplete_evidence

不要把「畫面看起來一樣」當成 Determinism Proof。

SLO、Hard Invariant 與 Operating Budget 不應混成同一種紅線

Agent System 若只設 Availability SLO，可能得到一個永遠在線、但經常做錯事又很貴的服務。

同時，把所有數字都稱為 SLO 也會失去精度。較實用的做法是分成三類。

Agent operations objective stack

Figure 11-3｜Service／Task-quality SLO、Hard Invariant 與 Economic／Attention Budget 使用不同的計算方式、時間窗口與 Breach Action。

Rolling Service SLO

適合用 Good Events／Eligible Events 與時間窗口定義：

Turn Availability
Queue Wait
Model／Tool Latency
Recovery Time
Background Result Delivery
Event Pipeline Availability

例如：

good terminal turns / eligible terminal turns
over 28 days

Rolling Task-quality SLO

可以追蹤：

Verified Completion Rate
Evidence Completeness
Rejection／Correction Rate
Escalation Rate
Completion Decision Latency

但要處理 Delayed Label。若 Completion Decision 或人工 Review 在數小時後才完成，Metric 不能把尚未成熟的 Task 當成 Fail 或排除得無影無蹤。

Hard Invariant／Zero-tolerance Gate

以下通常不適合被平均到 Rolling SLO 裡：

Cross-tenant Data Leak
Unauthorised Payment
Duplicate High-risk Side Effect
Approval Bypass
Secret Exposure

duplicate_refund = 0 更接近不可接受的 Invariant 或 Release／Runtime Gate，而不是「這個月允許消耗一點 Error Budget」。

Economic／Attention Objective 或 Budget

Cost per Verified Successful Task
Wasted Retry Budget
Evaluator Cost Ratio
Human Review Minutes
Synchronous Interrupt Count
Telemetry Storage／Ingestion Cost

若這些數字直接代表使用者承諾，可以納入 Service Objective；否則稱為 Operating Objective 或 Budget 往往比硬叫 SLO 更清楚。

一份可操作的 Objective Contract

profile: refund-agent-production-v5
window: 28d

service_slo:
  turn_availability:
    good: terminal_turn_without_platform_failure
    eligible: production_terminal_turn
    objective: ">= 99.5%"
  queue_wait_p95:
    objective: "<= 20s"

task_quality_slo:
  verified_completion:
    good: completion_decision == passed
    eligible: mature_eligible_task
    label_delay: "24h"
    objective: ">= 96%"

hard_invariants:
  cross_tenant_disclosure: "= 0"
  duplicate_refund: "= 0"

operating_budgets:
  cost_per_verified_task_p95: "<= 1.80 USD"
  synchronous_interrupts_per_task_p95: "<= 1"

on_breach:
  service_burn:
    - page on-call
  quality_regression:
    - hold risky promotion
    - sample evidence
  hard_invariant:
    - contain
    - revoke
    - declare incident

數字只是示意。真正重要的是每個 Objective 都定義：

SLI／Good Event
Eligible Population
Window
Target
Missing／Late Data Policy
Burn／Breach Rule
Owner
Action

Google SRE 將 SLO Alert 建立在 Error-budget Consumption 上，並以 Precision、Recall、Detection Time 與 Reset Time 評估 Alert Strategy。Agent System 可以沿用這個原則，而不是看到一筆普通 Failure 就立刻 Page。⁸⁹

Alert、Notification 與 Human Attention 是三個不同問題

Event 被記錄，不代表它需要通知人；Notification 被送出，也不代表它值得即時打斷。

可以把事件路由成三層：

Immediate interrupt

只用於：

Hard Invariant Violation
Security Incident
Imminent Data Loss
Policy-required Approval on a Critical Path
高速消耗 Error Budget
無法自動 Contain 的高風險 Unknown Outcome

Batched review／Ticket

適合：

Completed Background Work
一般 PR 或 Research Report
Evaluator Findings
Low-risk Ambiguity
緩慢 Quality Regression
可在下一個工作時段處理的 Budget Burn
多個同類 Escalation

Recorded only／No notification

適合：

Routine Progress
Heartbeat
Budget 內的 Retry
Intermediate Worker Result
Expected Cleanup
成功的 Auto-recovery
已被更高層 Incident Group 吸收的重複事件

Human attention routing and event tiers

Figure 11-5｜Event 先經 Risk、Urgency、Actionability、Deduplication 與 Ownership 判斷，再路由到 Page、Batch／Ticket 或 Recorded-only；Silent 不等於不記錄。

一個可營運的 Alert Contract

至少包含：

Detection Rule／SLI
Severity
Risk／Blast Radius
Owner／On-call Route
Dedupe／Grouping Key
Suppression／Maintenance Window
Acknowledgement
Escalation Deadline
Runbook Link
Evidence／Trace Query
Resolution／Reset Condition

SLO Alert 應偏向顯著 Error-budget Burn；Security 或 Hard Invariant 則可能一筆就必須 Page。兩種 Alert 不能用同一個閾值模板。

Google SRE 將 Page、Ticket 與其他通知分開，並強調只有需要立即人工行動的顯著事件才值得打斷 On-call。²⁹

Human Attention 也要有 Budget

可以追蹤：

Interrupt Count
Synchronous Approval Count
Alert Dedupe Ratio
Review Queue Size／Age
Average Review Time
Clarification Turns
Result Rejection Rate
Escalation Reason
Time to Natural Checkpoint
Abandoned Run

也可以限制：

每個 Task 同步中斷上限
哪些事件必須批次
Review Artefact 的最大閱讀成本
無 Evidence／無 Owner 的 Escalation 不進人工 Queue
重複 Alert 必須 Group，而不是複製人類焦慮

Mitchell Hashimoto 對背景 Agent 的工作方式強調由人選擇自然時機查看結果，而不是讓 Notification 持續切碎工作。這不是唯一模式，但它精確指出 Attention 也是受限 Runtime Resource。¹⁰

Incident Response 要保留控制、證據與學習

當事故發生時，Runbook 不應只寫「重新啟動 Agent」。

每個重要 Failure Class 至少應定義：

Detection／Declaration Criteria
Severity
Incident Commander／Operations／Communication／Subject-matter Roles
Immediate Containment
Kill／Pause／Revoke
Telemetry／State／Artefact Evidence Freeze
External Side-effect Reconciliation
Customer／Operator Communication
Safe Recovery
Owner 與 Escalation Path
Exit／Resolution Criteria

Google SRE 的 Incident Guidance 強調清楚指揮鏈、明確角色、持續工作紀錄，以及及早宣告 Incident。這些要求對 Agent 事故尤其重要，因為 Model、Tool、Policy、Worker 與外部 Side Effect 可能同時參與。¹¹

一個完整 Incident Loop 可以是：

Detect and declare
→ establish command and communication
→ contain
→ freeze state and evidence
→ reconcile external side effects
→ restore safely
→ identify causal factors and control gaps
→ create regression and harness repair
→ verify effectiveness
→ update runbook and ownership

Agent incident response and learning loop

Figure 11-4｜Incident 的終點不是服務恢復，而是經過 Evidence Preservation、Causal Analysis、Harness Repair 與 Effectiveness Verification，降低同類事故再次發生的機率。

不要把 Root Cause 壓成單一「模型不穩」

一個事故可能同時包含：

Model 在模糊 Context 下提出錯誤 Operation
Tool Contract 缺少 Operation ID
Retry Policy 將 Unknown Outcome 當普通 Timeout
Policy 未覆蓋某個 Resource
Verifier 看不到 External State
Alert 沒有 Owner
Rollout 同時改了四個 Version
Runbook 沒有 Reconciliation Step

比起尋找唯一 Root Cause，更有用的是記錄：

Trigger
Causal／Contributing Factors
Failed／Missing Controls
Detection Gap
Containment Gap
Recovery Gap
Organisational／Process Factor
Corrective Action
Owner／Deadline
Verification Evidence

Google SRE 也指出同一 Incident 可能有多個 Root Causes；修復其中每個因素，才足以建立「不會以同樣方式再次發生」的信心。²

從 Incident 到 Harness Change 需要 Review Gate

Observability 可以產生：

Candidate Regression Case
Diagnostic Improvement
Policy／Tool Contract Change
SLO／Alert Update
Runbook Patch
Architecture Constraint

但不能讓一個異常 Trace 自動改寫 Production Prompt 或 Policy。改進項目要經過 Triage、Owner、Version、Evaluation 與 Promotion。

OpenAI 的 Tax Agent 案例將 Product Trace 中的專業修正轉為結構化差異，聚類成重複失敗，再建立 Eval Target 與工程修復。這說明 Observability 可以驅動改進，但中間仍有資料處理、評估與工程 Review。¹²

Version Correlation 讓事故可比較，不承諾魔法式重現

每條重要 Trace 應能關聯：

Model Identifier、Provider 與 Inference Profile
SDK／API／Adapter Version
Prompt／Agent Config Digest
Context Builder／Compaction Policy
Tool Schema、Tool Runtime、Server 與 Capability Snapshot
Policy／Approval Rule 與 Decision ID
Retriever／Reranker／Dataset Snapshot
Verifier／Grader／Completion Contract Version
Sandbox／Container Image
Feature Flag／Deployment／Region
Budget、Timeout、Retry、Concurrency
Telemetry Schema、Convention 與 Instrumentation Version
Redaction／Sampling／Retention Policy

可以建立 Content-addressed Run Manifest：

run_id: run_refund_8a1f
task_id: refund-reconcile-204
started_at: 2026-07-08T04:12:31Z
deployment: refund-prod-eu-2026.07.08.3

model:
  provider: example-provider
  id: provider/model-version
  inference_profile: balanced-v3

harness:
  agent_config: refund-agent-31
  prompt_digest: sha256:8e2f...
  context_policy: progressive-disclosure-7
  tool_catalog: payments-tools-12
  capability_snapshot: sha256:48ad...
  permission_policy: refund-policy-19
  completion_contract: refund-completion-5
  verifier: refund-release-verifier-8

runtime:
  sandbox_image: refund-worker@sha256:71b...
  retry_policy: transient-v5
  timeout_policy: production-v4
  feature_flags: sha256:19a0...

telemetry:
  internal_schema: agent-telemetry-2.0
  genai_convention_revision: otel-genai@pinned-revision
  instrumentation_version: 0.19.0
  sampling_policy: risk-tail-sampling-3
  redaction_policy: payment-restricted-6

Manifest 讓團隊比較「哪些條件不同」，但不能保證：

Model Sampling 完全一致
外部資料仍保留當時版本
未記錄的 Payload 可以被恢復
Clock／Randomness／Provider 行為不變
Side Effect 可以重新執行

若一個版本 Reference 已失效，應將 Manifest 標成 partially_reconstructable，而不是假裝仍能 Recorded Reconstruction。

Version Correlation 的價值，是把「模型最近怪怪的」改寫成可測的假設：

只發生在 tool_catalog@12？
只出現在某個 Region？
Policy 19 上線後 Approval Wait 增加？
Instrumentation 0.19 是否漏掉某類 Event？
Model A 搭配舊 Prompt 才產生回歸？

事故調查需要的是可比較的條件，而不是一張充滿箭頭卻沒有版本的 Trace 截圖。

用退款異常案例走一次

回到開頭的退款 Agent。

1. Identity 與 Manifest 被固定

系統建立：

task_id
thread_id
turn_id
run_id
trace_id
operation_id

Run Manifest 保存 Agent Config、Model、Tool Capability Snapshot、Policy、Completion Contract、Verifier、Sandbox 與 Telemetry Convention Revision。

2. Context Build 遵守資料政策

Trace 保存：

Context Source ID
Version／Freshness
Selection Reason
Token Count
Redaction Class

完整客戶文件沒有直接進 Span，而是以受控 Artefact Reference 連結到短期 Payload Vault。

3. Model 提出 Tool Operation

Span 記錄 Tool Name、Schema Version、Arguments Digest、Policy Decision ID 與 Operation ID。

Audit Path 另行保存：

Actor
Canonical Resource
Authorisation Result
Approval Reference
Policy Version

即使 Trace 被 Sample 或 Collector 暫時失效，關鍵授權紀錄仍在 Durable Path。

4. Payment Tool Timeout

Runtime Trace 顯示 Dependency Timeout。

Canonical RunState 將 Effect 標成：

unknown

而不是把它壓成普通 failed。

一個 Export Gap 也被標記：Payment Client Span 已建立，但外部 Response Event 沒有成功送到 Collector。這個缺口不能被解讀成「Provider 沒有回應」。

5. Recovery 先做 External Reconciliation

Controller 使用 operation_id 查詢付款供應商。

結果顯示 Refund 已被接受，因此 Runtime：

不再重送
提交 External Receipt Reference
更新 Canonical State
建立 Late Result Event
將原 Timeout 分類為 Response Lost after Acceptance

6. Worker 成本與時間被正確拆解

Dashboard 顯示：

End-to-end Wall-clock：48 秒
Summed Worker Time：79 秒
Critical Path：Payment API＋Reconciliation
Coordinator Exclusive Cost：低
Research Worker 重複載入 Context，產生不必要 Token Cost

這比「本次 Run 花了 79 秒」更接近真相。

7. Verifier 阻止錯誤 Completion

External State 與 Internal Ledger 尚未一致，因此 Completion Authority 將 Run 保持在 needs_review。

Trace 記錄 Verifier Result；Completion Decision Record 才是 Pass-state Authority。

8. Alert 被正確路由

事件不是因普通 Timeout 直接 Page。

真正觸發 Incident 的條件是：

High-risk Unknown Outcome
External Refund 已發生
Internal Ledger 尚未提交
Reconciliation Deadline 接近

Alert 帶有 Owner、Runbook、Trace Query、Operation ID 與 Dedupe Key。

9. Incident 形成可驗證改進

團隊發現：

Tool Result Contract 缺少 Receipt Recovery Guidance
Reconciliation Span 沒有標準 Link
Payment Client Instrumentation 偶爾漏 Export
Runbook 未要求檢查 Late Result Queue

改進項目包括：

更新 Tool Result Contract
增加 Unknown Outcome Diagnostic
新增 Regression Case
修正 Instrumentation
更新 Alert Rule 與 Runbook
驗證同類 Incident 是否停止復發

Observability 的工作不是替團隊宣布「已修好」，而是提供足夠證據，讓修復、驗證與營運判斷不再靠猜。

用十二個問題審查 Agent Observability

能否從使用者 Outcome 追到 Task、Thread、Turn、Run、Worker、Operation 與 Evidence？
Correlation Model 是否支援 Fan-out、Fan-in、Retry、Fork 與 Background Completion，而不只是一棵樹？
Canonical State、Audit Record、Telemetry 與 Quality Decision 是否分開？
Span、Event／Log、Metric、Artefact 與 Audit 是否有各自的 Contract？
Metric Label 是否維持 Bounded Cardinality，並可透過 Exemplar 回到 Trace？
Sampling、Redaction 或 Export Failure 是否會留下可見 Gap？
敏感內容是否 Metadata-first，並有 Vault、Access Audit、Retention 與 Region Control？
Replay 是否分成 Recorded Reconstruction、Controller Replay 與 Sandbox Re-execution？
Service／Task-quality SLO、Hard Invariant 與 Cost／Attention Budget 是否分開？
Alert 是否依 Error-budget Burn、Risk、Urgency、Actionability 與 Owner 路由？
Incident 是否保存 Command、Evidence、External Reconciliation、Causal Factors 與 Corrective-action Verification？
能否用 Version Manifest 回答「哪一版 Model、Tool、Policy、Contract、Sandbox 與 Instrumentation 造成差異」？

若 Dashboard 很漂亮，但 Trace 被 Sample 後 Approval 就消失，或每個 run_id 都被塞進 Metric Label，那套系統只是把不可觀測性換成比較昂貴的不可觀測性。

理論轉實作：Part 11 檢查表

Part 12 會收束整個系列，討論哪些 Harness Pattern 應建立、哪些 Anti-pattern 應拆除，以及模型能力提升後，哪些控制可以被簡化或刪除。

References

OpenAI, Codex App Server, accessed 8 July 2026; and Unlocking the Codex harness: how we built the App Server, 4 February 2026. ↩
Rob Ewaschuk, Google SRE, Monitoring Distributed Systems. ↩ ↩² ↩³
OpenTelemetry, OpenTelemetry GenAI Semantic Conventions, accessed 8 July 2026. Agent and framework conventions include Development-status surfaces and should be pinned by revision. ↩
OpenTelemetry, Semantic Conventions 1.43.0, accessed 8 July 2026. The core documentation notes that GenAI conventions have moved to a separate repository. ↩
OpenTelemetry, Deprecating the Span Events API, 17 March 2026. ↩
OpenAI, Tracing in the OpenAI Agents SDK, accessed 8 July 2026. ↩
OpenAI, Codex Advanced Configuration: OpenTelemetry metrics and events, accessed 8 July 2026. ↩
Chris Jones, John Wilkes and Niall Murphy, Google SRE, Service Level Objectives. ↩
Steven Thurgood et al., Google SRE Workbook, Alerting on SLOs. ↩ ↩²
Mitchell Hashimoto, My AI Adoption Journey, 5 February 2026. ↩
Google SRE Workbook, Incident Response. ↩
OpenAI, Building self-improving tax agents with Codex, 27 May 2026. ↩