如何使用AgentSight

產品簡介

AgentSight 是基於 eBPF 的 AI Agent 可觀測性工具，在零侵入商務邏輯的前提下，實現對 Agent 運行全鏈路的細粒度資料擷取與關聯分析。

核心能力

AgentSight 主要包含以下能力：

Token 消耗分析：對 Agent 運行過程中的 Token 消耗進行全方位度量與歸因。支援按時間段或最近 N 小時靈活查詢，可自動環比對比。支援按智能體、任務、角色等多維度拆分消耗來源，分析粒度可精確至單次 LLM 調用。
行為審計：對 Agent 的 LLM 調用及進程執行行為的全鏈路記錄與追蹤。在資料擷取中，完整留存每次 LLM 調用的供應商、模型版本等關鍵中繼資料，並同步捕獲進程的命令列參數。此外，系統支援按時間維度、進程標識及事件類型進行多維度靈活篩選，並提供可視化的匯總統計分析能力。
Dashboard 可視化：Web 可視化介面，提供 Token 消耗、Agent 狀態監控與 Session 詳情的直觀展示。支援在瀏覽器中即時查看資料重新整理，可將 Dashboard 部署在遠程伺服器上，通過本地瀏覽器直接存取，無需登入伺服器。通過 Dashboard 可按時間段查看機器的 Token 消耗趨勢，即時監控 Agent 進程狀態並提供異常重啟能力，同時支援深入查看每次 Session 的完整 Trace 鏈路，包括使用者輸入、模型提示詞、推理思考過程及每一步的 Token 消耗分布，協助精準分析模型調用效率與最佳化成本控制。

使用範圍

本工具適用於 OpenClaw 以及Copilot Shell （非 AK/SK 認證情境）

安裝方式

詳情請參考快速入門。

對話式互動使用方式

AgentSight 提供了對話式互動 Skill，支援在各類 AI Agent 中安裝使用，使用者無需記憶 CLI 命令，直接通過自然語言即可完成操作：

查看 Token 消耗：如"今天 Token 用了多少？"
查詢審計日誌：如"幫我查一下今天的 LLM 調用記錄"

如果你使用的是 Copilot Shell（cosh），該 Skill 已內建，可直接使用以上自然語言指令，系統會自動調用 AgentSight 完成查詢並返回分析結論。

CLI 命令詳細說明

agentsight trace — 啟動 eBPF 追蹤

註：該服務已在系統中預設啟動，無需手動執行。

啟動基於 eBPF 的 AI Agent 活動追蹤。

agentsight trace #需要root許可權執行

agentsight serve — 啟動 API 及 Dashboard

註：該服務已在系統中預設啟動，預設綁定 0.0.0.0:7396，無需手動執行。

啟動 HTTP API 伺服器，提供嵌入式 Dashboard UI。

agentsight serve --host 0.0.0.0 --port 7396 #需要root許可權執行

該命令將綁定所有網路介面，可通過伺服器公網 IP 訪問：http://<伺服器公網IP>:7396

請確保伺服器防火牆 / 安全性群組已允許存取 7396 連接埠。

agentsight token — 查詢 Token 用量

查詢 Token 用量資料。

# 查看今日用量
agentsight token

agentsight audit — 查詢審計事件

查詢審計事件（LLM 調用、進程操作）。

# 查看最近事件
agentsight audit
# 按 PID 和類型過濾
agentsight audit --pid 12345 --type llm
# 匯總統計
agentsight audit --summary

agentsight discover — 掃描 Agent

發現系統上啟動並執行 AI Agent。

# 掃描 Agent
agentsight discover
# 列出已知類型
agentsight discover --list-known

Dashboard 可視化介面

Dashboard 是AgentSight 的 Web 可視化介面，用於查看對話歷史、Trace 詳情和 Token 統計資料。

Dashboard 功能

Dashboard 提供以下核心功能：

Token 消耗總覽：查看當前機器在所選時間段內的 token 消耗情況。Dashboard 頂部提供時間範圍選取器，可切換不同時間段；下方以統計卡片形式分別展示輸入 Token、輸出 Token 及總 Token 用量

Agent 狀態：右側狀態列可以查看當前 Agent 進程狀態，並提供 Agent 進程 hang 住重啟功能
會話中斷診斷：針對長時間會話無輸出或對話無響應的問題，自動識別 LLM 錯誤與 Agent 進程崩潰，輸出詳細原因分析，輔助快速定位與解決。會話列表展示各 Session 的 SESSION ID、AGENT、MODEL、對話數及 TOKEN 用量等資訊。展開某條會話可查看 CONVERSATION ID 子表，中斷列以標籤形式（如 1高危）標識異常。底部 Interruptions 面板顯示未處理的中斷詳情，例如 LLM Error 類型錯誤（錯誤資訊 invalid access token or token expired，狀態代碼 401），可通過 Resolve 或 Hide 按鈕進行處理。
Session 詳情：點擊"詳情"查看每個 session 和 trace的 token 使用詳細情況

在 Trace 詳情面板中，頂部通過按 Trace和按 Session標籤頁切換視圖，輸入 Trace ID 後單擊載入查看詳情。左側 Agent 資訊卡片展示名稱、版本、模型及工具定義數量，右側統計卡片分別展示總步驟數、總輸入 Token和總輸出 Token。下方互動軌跡地區按步驟列出每次互動的角色標籤、時間戳記和內容，包括系統 Prompt 文本及工具定義列表（如 read、write、edit、exec）。

模型分析：查看使用者輸入後的模型提示詞與思考過程，定位 Token 主要消耗環節
Token節省：查看當前已經節省的Token數量，支援點擊SESSION ID查看每個最佳化項，點擊詳情可查看最佳化前後的內容對比。

Token 節省頁面支援按時間範圍和 Agent 篩選查詢。頁面頂部以匯總卡片展示總 Token 消耗（含輸入/輸出分類）、已降低 Token（含工具/MCP 分類）及降低率（附等級評價）。下方表格按會話列出各 Session 的輸入/輸出 Token、已降低數量和降低率。

例如，MCP輸出 分類下可查看每條最佳化項的最佳化前後 token 數量（如最佳化前 734、最佳化後 182），展開詳情後左側 原始內容（紅色背景）顯示完整 JSON，右側 最佳化後（綠色背景）顯示精簡結果，冗餘中繼資料欄位會被截斷以節省 token。

資料管理

資料庫管理

自動限容與清理：為防止資料庫無限增長佔用過多磁碟空間，系統預設設定資料庫最大容量為 200 MB。當資料庫大小達到上限時，會自動觸發清理流程。

使用者可通過環境變數 AGENTSIGHT_GENAI_DB_MAX_SIZE_MB 自訂最大容量（單位：MB），例如設定為 500 MB。

export AGENTSIGHT_GENAI_DB_MAX_SIZE_MB=500

清理歷史資料

如需清理歷史資料，執行以下操作：

rm -rf /var/log/sysak/.agentsight

然後重啟 AgentSight 即可。

常見問題

Q1：為何無法擷取 OpenClaw 的 Token 消耗資料？
A： AgentSight 監控的是 openclaw-gateway 守護進程。請檢查用戶端與 Gateway 的串連狀態是否正常。若出現以下異常日誌，表明配對未成功：
Gateway agent failed; falling back to embedded: Error: gateway closed (1008): pairing required
建議執行命令 openclaw devices approve 完成裝置配對。

Q2：為何 Token 節省頁面未顯示當前 Session ID，或顯示的 Token 節省量為 0？
A：可能由以下兩種原因導致：

目前的版本暫不支援 Cosh 的 AK/SK 認證方式；
Session ID 格式非標準 UUID，導致系統匹配失敗。

Q3：為何 Token 節省頁面顯示的“最佳化項節省量”大於“最佳化前 Token 數”減去“最佳化後 Token 數”的差值？

A：這是因為 Agent 在每次對話時會將歷史訊息納入上下文。因此，目前的交談的統計結果中包含了歷史訊息的最佳化收益，導致累計節省量大於單次對話的即時差值。