可觀測性

可觀測性（observability）讓團隊知道 agent 做了什麼、呼叫了什麼工具、哪裡失敗、耗時在哪裡。沒有 trace 和日誌，自定義 agent 不能進入生產流程。

1. 官方能力邊界

GitHub 官方 observability 頁面說明：

• SDK 有內建 telemetry 支援。
• 可以配置 OpenTelemetry 到 CLI process。
• SDK 和 CLI 之間支援 W3C Trace Context 傳播。
• Outbound 方向可以透過 onGetTraceContext 提供 trace context。
• Inbound 方向，CLI 呼叫 tool handler 時，traceparent 和 tracestate 會出現在 ToolInvocation 物件上。

flowchart TD
    App["Your app span"] --> SDK["Copilot SDK"]
    SDK --> CLI["Copilot CLI process"]
    CLI --> Session["Session span"]
    Session --> Tool["Tool invocation"]
    Tool --> Handler["Your tool handler"]
    Handler --> Child["Child span"]
    Child --> Backend["Backend / API / DB"]

    style SDK fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Tool fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Child fill:#dcfce7,stroke:#16a34a,stroke-width:2px

2. 要記錄什麼

最小觀測欄位：

• session id。
• user id 或 tenant id。
• model。
• prompt metadata，不記錄原始敏感內容。
• tool name。
• tool args 摘要。
• tool result 狀態。
• duration。
• error category。
• trace id。
• cost 或 request metadata。

不要把原始 prompt、金鑰、客戶資料、完整檔案內容直接打進日誌。

3. Trace 怎麼用

推薦 span 層級：

1. HTTP request 或 job span。
2. SDK session span。
3. model response span。
4. tool invocation span。
5. downstream API / DB span。

這樣排障時可以回答：

• 這次 agent 為什麼慢？
• 哪個 tool 呼叫失敗？
• 是模型、SDK、CLI、MCP server，還是外部 API 出錯？
• 某個使用者或團隊是否觸發異常用量？

4. 觀測和 hooks 要配合

Hooks 捕獲事件，OpenTelemetry 負責串 trace。推薦組合：

• onSessionStart：寫入 session metadata 和 trace context。
• onUserPromptSubmitted：記錄 prompt 型別和長度，不記錄敏感原文。
• onPreToolUse：記錄工具申請和許可權決策。
• onPostToolUse：記錄結果狀態、耗時和錯誤。
• onErrorOccurred：記錄 error category 和降級路徑。

5. 上線檢查

上線前至少確認：

• 每個 session 都能查到 trace id。
• 每個 tool call 都能查到 tool name 和結果狀態。
• 錯誤有分類，不是隻記錄 stack trace。
• 日誌已脫敏。
• 高風險操作能關聯到使用者和審批。
• 監控系統能按模型、功能、團隊、工具聚合。

深讀：可觀測性不是事後補日誌

Agent 行為是多階段的：prompt、planning、tool call、MCP、外部 API、response。事後只看最終文本，無法解釋中間發生了什麼。

生產級 agent 必須在設計時就帶 trace，而不是出事故後再 grep 日誌。

本章自檢

1. 是否能把一次使用者請求追蹤到 SDK session？
2. 是否能定位每個 tool call 的耗時和結果？
3. 是否避免記錄原始敏感內容？
4. 是否把 hooks 和 trace 串起來？
5. 是否能區分模型失敗、工具失敗和外部系統失敗？

透過標準：任意一次 agent 執行都能查到 trace、工具呼叫、錯誤和成本線索。

官方來源

• OpenTelemetry instrumentation for Copilot SDK —— GitHub 官方 OpenTelemetry 和 trace context 說明。
• Quickstart for hooks —— GitHub 官方 hooks 事件入口。
• Streaming events with Copilot SDK —— GitHub 官方 streaming events。

接下來去哪