Agent 到底做了什麼？把模型、工具與產品請求接起來 | HCYTLOG

產品中的 Agent 回答一個問題，背後可能查了記憶、呼叫兩個工具、重試模型，或停在等待核准。產品介面看見的最後一句回答，不足以說明這段過程是否符合預期。觀測需要把使用者的任務，接到每一次實際執行的操作。

使用者說「剛才那次回答等很久」，你打開監控：CPU 正常、程序沒有重啟，整體 HTTP 成功率也沒掉。這些資料有用，但還不知道剛才那次請求在做什麼。Agent 可能排隊、等資料庫連線、遇到供應商重試，或已經開始串流但後續中斷；也可能根本停在等待使用者核准。

要回答這個問題，需要把整體趨勢與單次請求接起來。指標告訴我們哪段時間、哪類操作受到影響；事件紀錄提供某個階段的結果；追蹤展示同一個請求跨階段的時間關係。只增加一張儀表板，未必增加足以辨認原因的資訊。

同一件事，留下三種可查的資料

Metrics 是一段時間內的量化資料，適合觀察請求數、錯誤率與延遲分布。Logs 記錄事件，應讓人能查到固定事件名稱與結果。Trace 由多個 span 組成，每個 span 表達一個操作的起訖與屬性，讓我們檢查請求經過哪些步驟。OpenTelemetry 可觀測性入門

對一個產品任務，可以讓 agent.task 包住驗證、資料檢索、工具與模型呼叫，再用任務 ID 關聯前端的進度與背景工作。模型呼叫 span 記錄的是我們可觀察的請求邊界，不代表讀到了模型內部思想。工具選擇的結果可以留下受控的操作資訊，也不需要保存模型的推理文字。

互動圖解 · 教學模型 同一個 request，三種不同的證據

注入固定故障情境，從 metrics 看影響、從 trace 找慢在哪裡，再用相同 request_id 的 log 看事件。

注入教學故障

request_id=demo-001 的範例 trace 共 1100 ms。這個請求沒有注入故障。

單次請求延遲: 1100 ms
最終結果: 成功
上游錯誤事件: 0

01
Metrics：看影響完成
這次延遲 1100 ms；聚合趨勢還需要其他樣本。
02
Trace：找位置完成
各 span 以開始時間排列，屬於同一個 trace_id=demo-trace。
03
Logs：看事件完成
request_id=demo-001 event=request.completed；不記錄提示全文、金鑰或使用者個資。

輸入驗證0–40 ms（耗時 40 ms）
span=request.validate
記憶查詢40–220 ms（耗時 180 ms）
span=memory.query
政策檢查220–280 ms（耗時 60 ms）
span=safety.check
LLM 供應商280–1080 ms（耗時 800 ms）
span=provider.request；回應成功
回應序列化1080–1100 ms（耗時 20 ms）
輸出結果

圖中的資料只用來說明流程，不是實際服務的測試結果。瀑布圖是一個簡化的循序請求，不是即時遙測或完整的分散式追蹤。單一 trace 不能推導整體 p95、錯誤率或根因；需另收集觀察期間與樣本。

圖解可以切換無故障、資料庫、供應商或上游速率限制情境。觀察瀑布圖中哪個階段拉長、哪裡發生錯誤，以及後續工作是否仍有執行；再比較旁邊的指標與文字摘要。這是一個請求路徑的教學例，畫面中的耗時與結果不構成正式系統的統計樣本。

圖中的速率限制發生在上游：供應商 A 回覆 429，系統等待退避時間，再切換供應商 B，最後完成回答。這個錯誤事件沒有使整個請求失敗。若把每次上游錯誤都算進最終請求失敗率，就會誤判使用者受到的影響；需要分開記錄嘗試與最終結果。

入口速率限制則是另一種情境，可以在進行更多工作之前拒絕請求。它與圖中的上游 429 不在同一個位置，恢復方式也不同。完整追蹤可以告訴我們，是入口拒絕、上游重試後恢復，還是所有嘗試都沒有成功。

span 要結束，錯誤要能被辨識

以下是框架無關的示意介面，展示操作紀錄需要如何包住成功與失敗。正式 OpenTelemetry 整合還需要 SDK 初始化與作用中的追蹤脈絡，不可把這段當成可直接替換的完整設定：

interface OperationSpan {
  setOutcome(value: "ok" | "error"): void;
  addEvent(name: string, attrs: Record<string, string>): void;
  end(): void;
}

async function traced<T>(
  span: OperationSpan,
  run: () => Promise<T>,
): Promise<T> {
  try {
    const result = await run();
    span.setOutcome("ok");
    return result;
  } catch (error) {
    span.setOutcome("error");
    span.addEvent("operation.failed", { code: "DEPENDENCY_ERROR" });
    throw error;
  } finally {
    span.end();
  }
}

這段保留原錯誤供上層分類，只在紀錄中使用受控錯誤碼，正式版本可以再細分錯誤種類。finally 很重要，否則例外可能留下沒有結束的 span，讓時間軸看起來像工作仍在進行。對外回覆也應使用公開契約中的錯誤，不暴露內部堆疊。

若每個服務都各自產生新的 trace ID，單次請求就會散成多個片段。HTTP 服務間可依 W3C Trace Context 傳遞追蹤脈絡，建立呼叫關係；佇列則要把必要追蹤脈絡隨工作交接。W3C Trace Context

背景任務與原請求的關聯可依生命週期使用 parent 關係或 span link，不能只靠相近時間拼接。Link 可以記錄跨 trace 的關係，適合表達不直接嵌在原 HTTP 請求內的後續工作。OpenTelemetry：Span links

SDK 看見 Agent 步驟，後端補齊產品路徑

OpenAI Agents SDK（@openai/agents）在一般伺服器端執行路徑預設啟用 tracing，涵蓋模型呼叫、工具、角色轉交與防護規則。若一個產品工作流程要呼叫 Agent 好幾次，可以用 withTrace 把它們放進同一條 SDK trace，檢查多次執行之間的關係。OpenAI：Integrations and observability

但 SDK trace 不會自動知道產品 HTTP 的排隊時間、資料庫連線等待，或背景工作何時交接。應用程式仍要記錄產品任務 ID、外層 trace ID 與 SDK trace 的對應，再依實際匯出方式串接查詢。SDK 內建追蹤與既有 OpenTelemetry 追蹤是需要整合的兩個觀測範圍，不能只因兩邊都有 trace 就假定已經接成同一條路徑。OpenAI：Integrations and observability

Claude Agent SDK（@anthropic-ai/claude-agent-sdk）目前也支援 OpenTelemetry 與 OTLP 匯出，但 telemetry 預設關閉，tracing 仍是 beta。啟用時要設定 exporter、把應用程式的追蹤脈絡傳入子程序，並確認 collector 確實收到資料；SDK 以標準輸出傳送訊息，不適合使用 console exporter。Claude：Observability

接入前也要確認追蹤會保存哪些資料。工具輸入、模型輸出與交接內容可能包含使用者資料；先決定要遮蔽或停用哪些內容，再確認追蹤查閱權限與保留期限。除錯方便不代表每一種內容都適合匯出。OpenAI：Integrations and observability、Claude：Observability

限制觀測資料的成本與暴露範圍

指標能分類，但不適合逐人索引

一個請求 ID 對故障調查很有用，卻不適合作為每筆指標的 label。每一種 label 組合都會形成時間序列；把使用者 ID、任務 ID 或完整問題放進去，序列數量會隨請求增長，增加記憶體、儲存與查詢成本。Prometheus：Instrumentation

指標可以先保留有限種類的 route、結果與供應商分類。單次事件以 traceId、spanId 或 request ID 串接到紀錄，查詢權限則由紀錄系統控制。這也能避免把個人識別資訊散布到每張可見的儀表板。

LLM 的成功條件要另外定義。HTTP 連線完成，不一定代表已產生完整回答；政策拒絕也不該算成供應商故障。可以統計 completed、refused、timeout、cancelled 等結果，把 pending_approval 另記為等待中的狀態，並記錄第一段內容與完整結束的時間。串流斷線後沒有結束事件，不能直接計為成功。

追蹤取樣會影響能查到哪些請求。少量取樣可以降低成本，但罕見故障可能沒被留下；只保留失敗又會失去正常路徑的比較。取樣策略與涵蓋範圍需要一併呈現在調查結果中，「查不到慢請求」不能被解讀成「沒有慢請求」。

紀錄內容越多，不代表越容易定位

全文 prompt、回答、檢索片段與工具參數可能含個資、憑證或公司資料。一般效能調查可以先記錄長度、token 數、階段名稱、版本、結果與耗時。需要內容才能重現時，再走有權限、保留期限與可稽核的受控流程，不必把全部內容預設寫進 log。

供應商錯誤原文也可能原樣帶回輸入內容或 URL。固定分類、允許的屬性清單與遮蔽規則，要涵蓋錯誤路徑。把 user ID 雜湊不表示整個紀錄匿名，若還能連回其他資料，仍然需要權限與保留控制。

故障定位時，瀑布圖指出哪裡等待，相關指標提供當時的負載，事件紀錄補充錯誤結果。這些證據仍可能只支持假說。例如資料庫 span 拉長，可能包含等待連線與真正查詢，必須再拆出連線取得時間，才能決定要查容量還是 SQL。不能從兩條曲線同時上升就宣稱因果關係。

怎樣驗證這套觀測能回答問題

準備一組可控制的測試請求，分別讓資料庫變慢、供應商失敗與上游 429 觸發，確認三者產生可區分的紀錄。檢查嘗試失敗與最終結果是否分開計數、span 是否結束、沒有執行的階段是否真的沒有紀錄，以及請求 ID 能否查回同一條路徑。

再測試跨服務、背景佇列與串流中斷，確認追蹤脈絡沒有遺漏。監控匯出端不可用時，主請求不應無限等待；但也要留下資料遺漏的計數，避免儀表板因缺資料而呈現假正常。量測觀測本身的額外耗時與資料量，才能決定取樣和保留的預算。

警示則回到具體行動：誰接手、先查哪裡、什麼時候恢復。政策拒絕增加可能適合日報；完整回答失敗率持續超出目標，才可能需要即時通知。圖解的下一步，是把相同的區別變成測試可檢查的事件與指標，而不是先堆出更多圖表。

系列導覽

上一篇：Agent 任務 API。下一篇：產品口吻與使用者偏好。也可以從產品架構開始。