工具執行記錄

概述

工具執行記錄讓您能追蹤 AI 助理調用外部工具的完整歷史，包含 API 呼叫、資料庫查詢、網頁爬取等操作。當 AI 助理需要執行超出對話範圍的任務時，會透過工具來完成，工具執行記錄能幫助您了解工具使用狀況、發現執行失敗的原因並優化工具配置。

透過完整的執行記錄，您可以在 5 分鐘內找出工具失敗原因，縮短 80% 的問題排查時間，確保 AI 助理能穩定提供進階功能服務。

功能特色

藉由工具執行記錄功能，您可以：

📋 完整記錄執行歷史

系統自動記錄每一次工具調用，包含輸入參數、執行結果、耗時、成功或失敗狀態。

• 使用場景：電商平台的訂單查詢工具每天被調用 500 次，需要追蹤成功率和回應時間

• 實際效益：發現 10% 的查詢因逾時失敗，調整逾時設定後成功率提升至 98%

🔍 快速定位失敗原因

當工具執行失敗時，系統記錄詳細錯誤訊息，幫助您快速了解問題出在哪裡。

• 使用場景：天氣查詢 API 突然開始頻繁失敗，需要快速找出原因

• 實際效益：透過錯誤記錄發現 API 金鑰過期，5 分鐘內完成更新恢復服務

📊 統計工具使用情況

查看每個工具的調用次數、成功率、平均執行時間等統計資訊。

• 使用場景：企業配置了 10 個工具，想了解哪些工具最常被使用、哪些工具問題最多

• 實際效益：發現 3 個工具從未被使用，移除後減少系統複雜度，其他工具回應速度提升 15%

🎯 優化工具配置

基於執行記錄分析，調整工具參數、優化調用邏輯、改善錯誤處理。

• 使用場景：資料庫查詢工具經常因為查詢範圍太大而逾時

• 實際效益：根據記錄分析調整查詢限制，執行時間從平均 8 秒降至 3 秒

工具類型說明

MaiAgent 支援多種工具類型，工具執行記錄會追蹤所有類型的執行狀況：

API 工具

調用外部 API 取得即時資料，例如天氣查詢、匯率查詢、庫存查詢等。

常見執行問題：

• API 金鑰過期或無效

• 請求參數格式錯誤

• API 服務逾時或無回應

• 超過 API 調用次數限制

Text-to-SQL 工具

將自然語言問題轉換為 SQL 查詢，從資料庫取得數據。

常見執行問題：

• SQL 語法錯誤

• 查詢範圍過大導致逾時

• 資料庫連線失敗

• 權限不足無法存取特定資料表

爬蟲工具

從指定網站抓取即時資訊，例如最新新聞、產品價格等。

常見執行問題：

• 目標網站無法連線

• 網頁結構變更導致解析失敗

• 被目標網站封鎖或限流

• 爬取逾時

自訂工具

企業自行開發的特定功能工具，例如訂單處理、會員驗證等。

常見執行問題：

• 內部服務異常

• 參數驗證失敗

• 業務邏輯錯誤

• 系統整合問題

使用步驟

步驟 1：進入工具執行記錄

1. 進入後台管理介面，點選左側選單「AgentOps」

2. 點選「工具執行記錄」分頁

3. 查看最近的工具執行記錄列表

步驟 2：篩選查看記錄

使用篩選條件找出需要關注的執行記錄：

1. 時間範圍：

   • 今天、近 7 天、近 30 天

   • 或自訂起始和結束日期

2. 工具類型：

   • 全部工具

   • API 工具

   • Text-to-SQL

   • 爬蟲工具

   • 自訂工具

3. 執行狀態：

   • 全部

   • 成功

   • 失敗

   • 執行中

4. 特定工具：

   • 從下拉選單選擇特定工具名稱

5. 點擊「套用篩選」查看符合條件的記錄

優先查看項目

建議優先檢查：

1. 執行失敗的記錄

2. 執行時間超過 10 秒的記錄

3. 高頻使用的工具的執行狀況

步驟 3：查看執行詳情

1. 在記錄列表中點擊任一筆記錄

2. 展開詳細資訊，包含：

基本資訊：

• 工具名稱

• 執行時間（何時被調用）

• 執行耗時（花費多少秒）

• 執行狀態（成功/失敗）

輸入參數：

• AI 傳遞給工具的參數內容

• 可檢查參數是否正確

執行結果：

• 工具回傳的完整結果

• 成功時顯示取得的數據

• 失敗時顯示錯誤訊息

關聯對話：

• 觸發此工具調用的對話記錄

• 可追蹤使用者原始問題

錯誤訊息（如有）：

• 詳細的錯誤描述

• 錯誤代碼或異常類型

• 堆疊追蹤資訊（如適用）

步驟 4：分析失敗原因

當發現執行失敗記錄時，可依以下步驟分析：

1. 檢查錯誤訊息：

   • 閱讀詳細錯誤描述

   • 識別是配置問題、權限問題還是服務異常

2. 檢查輸入參數：

   • 確認 AI 傳遞的參數是否正確

   • 檢查參數格式是否符合工具要求

3. 查看關聯對話：

   • 了解使用者提出什麼問題

   • 判斷是否為特定問題類型導致失敗

4. 比對成功案例：

   • 找出相同工具的成功執行記錄

   • 比較成功和失敗案例的差異

步驟 5：優化工具配置

根據執行記錄分析結果，採取改善措施：

1. 更新工具設定：

   • 修正錯誤的 API 金鑰或連線資訊

   • 調整逾時時間設定

   • 優化查詢參數或限制條件

2. 調整 AI 提示詞：

   • 如果參數經常錯誤，在提示詞中加入明確指引

   • 說明工具的正確使用方式和參數格式

3. 改善錯誤處理：

   • 為常見錯誤情況加入友善的錯誤訊息

   • 設定自動重試機制

4. 移除無用工具：

   • 如果工具長期未被使用，考慮移除以簡化配置

步驟 6：匯出執行記錄

1. 在工具執行記錄頁面點擊「匯出」按鈕

2. 選擇匯出格式（CSV 或 Excel）

3. 選擇時間範圍和篩選條件

4. 下載報告供進一步分析或存檔

匯出的記錄可用於：

• 深度數據分析和趨勢追蹤

• 向技術團隊報告問題

• 定期檢討工具使用效率

• 合規性稽核和記錄保存

使用場景

場景 1：診斷工具故障

情境：電商平台的庫存查詢工具突然開始大量失敗，客服無法幫客戶查詢商品庫存。

操作方式：

1. 進入工具執行記錄，篩選「庫存查詢工具」+「失敗」

2. 發現過去 2 小時有 50 次失敗記錄

3. 查看失敗記錄的錯誤訊息：「資料庫連線逾時」

4. 檢查資料庫服務狀態，發現資料庫正在維護

5. 暫時停用工具並通知客服改用人工查詢

6. 資料庫恢復後重新啟用，監控成功率回升至正常

量化效益：

• 5 分鐘內定位問題根源

• 避免技術團隊花費數小時排查

• 及時通知客服改用備援方案，減少客戶等待時間

場景 2：優化工具效能

情境：訂單查詢工具經常執行緩慢，影響對話體驗。

操作方式：

1. 匯出近 30 天的訂單查詢工具執行記錄

2. 分析執行時間分布，發現：

   • 平均執行時間 7.5 秒

   • 25% 的查詢超過 10 秒

   • 最長達 18 秒

3. 檢視慢查詢的輸入參數，發現多數是查詢「近一年所有訂單」

4. 優化工具配置：

   • 限制查詢範圍為近 3 個月

   • 增加分頁機制每次最多回傳 20 筆

5. 優化後平均執行時間降至 3.2 秒

量化效益：

• 執行時間減少 57%（7.5 秒 → 3.2 秒）

• 超過 10 秒的查詢從 25% 降至 5%

• 對話體驗顯著改善，客戶滿意度提升

場景 3：發現未使用工具

情境：企業為 AI 助理配置了 12 個工具，想了解實際使用情況以簡化配置。

操作方式：

1. 匯出近 90 天的所有工具執行記錄

2. 統計每個工具的調用次數：

   • 訂單查詢：1,500 次

   • 會員查詢：800 次

   • 促銷活動查詢：300 次

   • 產品規格查詢：200 次

   • 其他 8 個工具：0 次

3. 檢視未使用工具的配置，發現：

   • 部分工具定義不清楚，AI 不知道何時使用

   • 部分工具功能重複

   • 部分工具已過時

4. 移除 6 個未使用工具，優化 2 個低使用率工具的描述

量化效益：

• 簡化配置，AI 選擇工具的準確度提升 20%

• 系統回應速度提升 10%（減少工具選擇的判斷時間）

• 降低維護成本

場景 4：監控 API 用量

情境：企業使用第三方天氣 API，每月有調用次數限制，需要監控用量避免超額。

操作方式：

1. 每週一匯出天氣查詢工具的執行記錄

2. 統計調用次數趨勢：

   • 第一週：320 次

   • 第二週：450 次

   • 第三週：680 次

   • 第四週：預估 900 次（月限額 2,000 次）

3. 發現調用量快速增長，分析原因：

   • 客戶詢問天氣的頻率增加

   • 部分不必要的重複查詢

4. 採取措施：

   • 加入快取機制，相同城市 1 小時內不重複查詢

   • 優化提示詞，避免 AI 過度依賴天氣工具

5. 優化後每週調用降至 400 次，確保不會超額

量化效益：

• 避免超過 API 限額導致服務中斷

• 減少 40% 的 API 調用成本

• 維持服務品質的同時控制成本

常見問題

Q: 工具執行記錄會保留多久？

A: 系統預設保留 3 個月的工具執行記錄。建議定期匯出重要數據進行長期保存和分析。如需更長的保留期限，請聯繫客服升級方案。

Q: 為什麼工具執行失敗，但對話看起來正常？

A: 當工具執行失敗時，AI 助理可能會：

1. 告知使用者「目前無法查詢，請稍後再試」

2. 改用知識庫資訊回答（如果有相關內容）

3. 請使用者提供更多資訊後重試

雖然對話繼續進行，但功能受限。建議透過執行記錄追蹤失敗原因並修正，確保工具穩定運作。

Q: 如何降低工具執行失敗率？

建議從以下方向優化：

配置層面：

• 確保 API 金鑰、資料庫連線等配置正確

• 設定合理的逾時時間（建議 10-15 秒）

• 加入錯誤重試機制

提示詞層面：

• 明確說明工具的使用時機和參數格式

• 加入範例幫助 AI 正確調用工具

監控層面：

• 定期檢查執行記錄

• 及時發現和修正問題

• 追蹤成功率趨勢

Q: 執行記錄中的輸入參數包含敏感資料怎麼辦？

A: 系統會自動遮蔽常見的敏感資料（如密碼、金鑰）。如果您的工具處理其他敏感資料（如客戶個資），建議：

1. 在工具配置中啟用「參數遮蔽」功能

2. 控制執行記錄的查看權限，僅授權必要人員

3. 定期清理過期的執行記錄

Q: 可以重新執行失敗的工具調用嗎？

A: 目前系統不支援直接重新執行歷史記錄。如果需要測試工具，建議：

1. 在對話平台直接提問觸發工具調用

2. 使用工具測試功能（如有提供）

3. 修正問題後等待真實使用者觸發

Q: 如何查看某個對話調用了哪些工具？

A: 有兩種方式：

1. 從對話記錄查看：在對話詳情中會顯示該對話調用的所有工具

2. 從工具記錄反查：在工具執行記錄中點擊「關聯對話」連結

最佳實踐

定期檢查建議

• 每日檢查：查看過去 24 小時的失敗記錄，確保關鍵工具運作正常

• 每週檢討：統計各工具的調用次數和成功率，識別需要優化的項目

• 每月分析：匯出完整報告，分析長期趨勢和使用模式

警示設定建議

建議設定以下警示（如系統支援）：

• 某工具在 1 小時內失敗超過 10 次

• 某工具成功率低於 80%

• 某工具平均執行時間超過 10 秒

• 某工具超過 7 天未被使用（檢查是否需要）

文檔記錄建議

為每個工具建立使用文檔，記錄：

• 工具用途和適用場景

• 輸入參數說明和範例

• 預期輸出格式

• 常見錯誤和解決方式

• 優化歷史記錄