前面 20 天，我們已經把一個 Agent 從最小 Loop 一路擴展到：

• Tool Runtime
• Permission / Approval / Sandbox
• Hooks
• Planning
• Subagents
• Skills
• Context Management
• Memory
• Prompt Assembly
• Error Recovery
• Task System
• Background Execution
• Scheduling
• Worktree Isolation
• Multi-Agent Coordination
• Protocols
• Autonomy
• MCP / Plugins / Channels

系統越來越像 Production Agent。

但也會開始出現一個很現實的問題：

Agent 昨天失敗了，你知道它「為什麼」失敗嗎？

很多系統會回答：

有 Log 啊

但「有 Log」和「可觀察」是兩件不同的事。

如果你只能看到：

Agent failed.

或者：

Tool error.

你仍然無法回答：

• 模型當時看到了什麼？
• 選了哪個 Tool？
• Tool Arguments 是什麼？
• Permission 有沒有拒絕？
• Retry 幾次？
• Context 多大？
• 哪個 Subagent 花最多成本？
• 任務到底在哪一步偏離？
• Model 換版後是不是更差？
• 昨天成本突然增加，是哪一類 Task 造成？

這就是 Observability 要解決的問題。

今天的核心觀念是：

Logging 記錄事件，Observability 讓你從事件重建系統行為。

Observability 不是「多印一些 Log」

傳統 Log 常常是程式碼作者想到什麼就印什麼：

starting task
calling model
calling tool
done

它可以幫助 Debug 小程式。

但 Agent 的問題更複雜。

一次 Task 可能包含：

User
↓
Model Call
↓
Tool A
↓
Tool Error
↓
Retry
↓
Model Call
↓
Subagent
↓
Tool B
↓
Approval
↓
Resume
↓
Verification
↓
Completed

如果每一段 Log 沒有：

• task_id
• turn_id
• parent_id
• model
• tool
• duration
• tokens
• cost
• result
• error_type

那你最後只有很多字串，卻沒有一條可以重建的 Trajectory。

所以第一個設計原則是：

Agent Observability 要以「一次執行軌跡」為中心，而不是以單一 Log Line 為中心。

第一層：Event

最基本的單位可以是 Event。

例如：

task_started
model_called
tool_requested
tool_completed
permission_denied
subagent_started
approval_required
task_completed

每個 Event 至少要帶上共同欄位：

event_name
timestamp
task_id
turn_id
parent_task_id
duration
status

再依事件類型加入不同資料。

例如 model_called 可以記：

model
input_tokens
output_tokens
cost
stop_reason

tool_completed 可以記：

tool_name
duration
success
error_type
output_size

這樣才能回答：

哪個 Tool 最常失敗？

而不是到幾萬行 Log 裡用 grep 猜。

第二層：Trace

Event 是點。

Trace 是整條路。

例如：

Task 123
├── Turn 1
│   ├── Model Call
│   └── Tool: search
├── Turn 2
│   ├── Model Call
│   └── Tool: read_file
├── Turn 3
│   ├── Model Call
│   ├── Tool: run_tests
│   └── Error
└── Turn 4
    ├── Model Call
    └── Completed

有了 Trace，我們才能問：

• 任務在哪一輪開始偏離？
• 哪個 Observation 讓模型改變策略？
• 哪個 Tool Result 導致 Replan？
• Retry 是否真的增加新資訊？
• 是否在同一個 Step 反覆打轉？

這些問題都不是單一 Log 能回答的。

Trace 不等於把所有 Prompt 全部存下來

這裡有一個很大的陷阱。

Agent Debug 很需要 Context。

所以很多團隊會直接把：

• System Prompt
• User Message
• Tool Result
• File Content
• Model Output

全部送進 Observability Backend。

這非常方便。

也非常危險。

因為裡面可能包含：

• Source Code
• API Key
• Customer Data
• File Path
• Email
• Private Document
• Database Result

所以 Observability 的第二個重要原則是：

可觀察不等於可以無限制記錄。

第三層：Scrubbing

在 Telemetry 送出去之前，要先處理 Sensitive Data。

最簡單的策略不是建立一張超長 Blocklist。

而是反過來：

只允許已知安全欄位離開 Runtime。

例如：

允許：

task_id
event_name
model
token_count
duration
tool_name
status
error_type
cost

而：

prompt
source_code
file_content
secret
raw_tool_output

預設不送。

如果真的需要 Debug，可以把完整 Artifact 留在權限更嚴格的 Storage，而不是一般 Metrics Backend。

第四層：Sampling

Production Agent 每一輪都產生大量 Event。

如果 100% 全部送到 Backend，成本可能很高。

例如：

100K Tasks / day
× 20 Events
=
2M Events / day

所以可以 Sampling。

但不是所有 Event 都適合相同 Sampling Rate。

例如：

model_call
10%

successful_tool
5%

permission_denied
100%

task_failed
100%

security_event
100%

成功案例可以抽樣。

Failure 與 Safety Event 通常應該完整保留。

Telemetry 不能拖垮 Agent Loop

這是 Observability 很容易犯的架構錯誤。

假設每次 Tool Call 後都同步：

POST /telemetry

如果 Telemetry Backend Timeout，Agent Loop 也跟著卡住。

結果變成：

監控系統故障，讓被監控的系統一起故障。

所以 Telemetry 最好採用：

Agent Loop
↓
emit event
↓
Queue / Buffer
↓
Telemetry Worker
↓
Sink

也就是 Fire-and-forget。

核心原則：

Telemetry 是 Side Observer，不應該成為 Agent 的必要執行步驟。

Sink 也應該隔離

同一個 Event 可能送到：

• Console
• File
• Datadog
• OpenTelemetry
• Internal Dashboard

如果其中一個 Sink 壞掉，不應該影響其他 Sink。

可以把架構想成：

Event
↓
Scrub
↓
Sample
↓
Fan-out
├── File
├── Metrics
└── Trace Backend

每個 Sink 都有自己的 Error Boundary。

為什麼要先 Buffer？

Agent 啟動時，Telemetry Backend 可能還沒準備好。

如果 emit() 必須等 Sink Ready，Loop 就會被 Infrastructure 綁住。

所以可以先把 Event 放入本地 Queue。

等 Sink Attach 後再 Drain。

這個小設計可以讓：

Agent Runtime

和：

Observability Infrastructure

真正解耦。

第五層：Cost Observability

Agent 和一般 Backend 很不一樣的一點是：

每一次 Model Call 都直接花錢。

所以 Token 和 Cost 不是 Nice-to-have Metric。

它們應該是一級指標。

例如每個 Model Call 都記：

model
input_tokens
output_tokens
cache_tokens
cost_usd

再 Roll Up：

Turn Cost
Task Cost
User Cost
Model Cost
Feature Cost

這樣才能回答：

• 哪個 Model 最貴？
• 哪種 Task 最容易爆 Token？
• Subagent 是不是把成本乘了三倍？
• Context Compaction 有沒有真的省錢？
• 新 Prompt 是否增加 20% Input Token？
• Retry Policy 是否讓成本失控？

Cost 不能只看平均值

假設平均 Task Cost：

$0.08

看起來很好。

但 P99 可能是：

$4.20

原因是少數 Task：

• Infinite Retry
• 大量 Subagent
• Context Explosion
• Tool Output 過大

所以至少要看：

• Average
• Median
• P95 / P99
• Max
• Cost per Successful Task

最後一個尤其重要。

因為「很便宜但一直失敗」沒有意義。

第六層：Outcome

Observability 很容易只記系統行為：

• Token
• Tool
• Latency
• Error

但還缺一個重要問題：

這次 Task 最後到底怎樣？

至少應該記：

completed
failed
cancelled
human_handoff
verification_passed
verification_failed

這樣我們才能把 Process Metric 和 Outcome 連起來。

例如：

Tool Calls ↑
Success Rate 不變

表示 Agent 可能只是在做更多工作，沒有更好。

Observability 和 Evaluation 不一樣

這是今天最重要的邊界。

Observability 問：

Production 中發生了什麼？

例如：

• 這次 Task 用了多少 Token？
• Tool 為什麼失敗？
• 哪個 Step 最慢？
• 哪個模型最貴？
• 哪種 Permission 最常被拒絕？

Evaluation 問：

這個 Agent 好不好？

例如：

• 新版本成功率有沒有提升？
• 是否更可靠？
• 是否開始產生危險 Side Effect？
• 同一 Task 跑五次，結果是否穩定？
• 新 Harness Mechanism 是否值得？

Observability 提供 Evidence。

Evaluation 提供 Judgment。

兩者不能互相取代。

Production Trace 可以反過來養 Eval Dataset

這兩套系統真正有價值的地方是可以形成 Loop。

例如 Production Trace 發現：

大量 Task 都在「缺少 order number」時失敗

那可以把這種 Failure Pattern 做成 Eval Case：

使用者一開始不提供 order number
Agent 必須先問

再測下一版 Agent 是否改善。

流程變成：

Production Failure
↓
Trace
↓
Scrub
↓
Convert to Eval Case
↓
Fix
↓
Run Evaluation
↓
Deploy
↓
Observe Again

這才是完整 Improvement Loop。

Metrics 要分成三層

一個實用方式是分：

1. System Metrics

系統是否健康？

例如：

• latency
• error rate
• queue depth
• worker failure

2. Agent Process Metrics

Agent 怎麼執行？

例如：

• turns
• tool calls
• retries
• context size
• subagents
• permission denials

3. Outcome Metrics

任務結果如何？

例如：

• completion
• verification
• user correction
• handoff
• cost per success

如果只看 System Metrics，你只知道服務沒掛。

但不知道 Agent 是否做對。

Agent Trace 最值得記什麼？

第一版不需要把所有東西都塞進 Trace。

可以從這些開始：

task_id
turn
model
stop_reason
input_tokens
output_tokens
cost
tool_name
tool_success
error_type
latency
permission_result
verification_result
final_status

這些已經足以回答大量 Production 問題。

真的需要完整 Prompt / Tool Output 時，再從受控 Artifact Store 查。

Failure Modes

1. Telemetry 在 Hot Path

Logging Backend 一慢，Agent 也跟著慢。

2. 把所有內容原文送出去

造成 Code、PII、Secret 外洩。

3. 只有成功 Log，沒有 Failure Trace

真正需要 Debug 時資料反而不完整。

4. 只有 Token，沒有 Cost

換 Model 後很難比較。

5. 只有 Process，沒有 Outcome

Agent 做了很多事，但不知道是否完成。

6. Event 沒有 Task / Turn ID

無法重建 Trajectory。

7. 只看 Average

少數失控 Task 被平均值藏掉。

8. Observability 和 Evaluation 混在一起

看到「發生什麼」就以為知道「好不好」。

如何設計第一版 Agent Observability？

第一版可以先做到五件事。

1. 統一 Event Schema

所有 Event 都有：

task_id
turn_id
event_name
timestamp
status

2. Fire-and-forget Telemetry

Log Failure 不影響 Agent Loop。

3. Safe-field Allowlist

敏感資料預設不送。

4. Token + Cost Tracker

每輪、每 Task 都能算成本。

5. Reconstructable Trace

可以從 Event 還原：

Task → Turns → Model → Tools → Errors → Outcome

這已經比「到處 print()」前進很多。

今天新增了什麼能力？

Day 20 我們已經能連接大量外部 Capability。

今天加入：

• Event
• Trace
• Telemetry Queue
• Sampling
• Scrubbing
• Sink Isolation
• Cost Tracking
• Process Metrics
• Outcome Metrics
• Production Trace

從今天開始，我們不只是讓 Agent 執行。

我們開始可以回答：

它剛剛到底做了什麼？

今天的結論

Observability 的核心不是多收集資料。

而是：

在不影響 Agent 執行與安全的前提下，保留足夠資訊重建一次 Task 的行為與成本。

最重要的原則是：

看得到發生什麼，才有資格討論要改什麼。

但 Observability 仍然不能回答：

這個結果到底好不好？

這就是下一篇 Evaluation 要處理的問題。

下一篇：

Agent Evaluation 為什麼不能只準備一份 Prompt Dataset，再算 Pass Rate？

完整系列與程式碼範例收錄於 https://github.com/hardness1020/awesome-agent-architecture