# 工具執行記錄
## 概述
工具執行記錄讓您能追蹤 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. 查看最近的工具執行記錄列表
工具執行記錄列表頁面
### 步驟 2：篩選查看記錄
使用篩選條件找出需要關注的執行記錄：
1. **時間範圍**：
* 今天、近 7 天、近 30 天
* 或自訂起始和結束日期
2. **工具類型**：
* 全部工具
* API 工具
* Text-to-SQL
* 爬蟲工具
* 自訂工具
3. **執行狀態**：
* 全部
* 成功
* 失敗
* 執行中
4. **特定工具**：
* 從下拉選單選擇特定工具名稱
5. 點擊「套用篩選」查看符合條件的記錄
{% hint style="info" %}
**優先查看項目**
建議優先檢查：
1. 執行失敗的記錄
2. 執行時間超過 10 秒的記錄
3. 高頻使用的工具的執行狀況
{% endhint %}
### 步驟 3：查看執行詳情
1. 在記錄列表中點擊任一筆記錄
2. 展開詳細資訊，包含：
**基本資訊**：
* 工具名稱
* 執行時間（何時被調用）
* 執行耗時（花費多少秒）
* 執行狀態（成功/失敗）
**輸入參數**：
* AI 傳遞給工具的參數內容
* 可檢查參數是否正確
**執行結果**：
* 工具回傳的完整結果
* 成功時顯示取得的數據
* 失敗時顯示錯誤訊息
**關聯對話**：
* 觸發此工具調用的對話記錄
* 可追蹤使用者原始問題
**錯誤訊息**（如有）：
* 詳細的錯誤描述
* 錯誤代碼或異常類型
* 堆疊追蹤資訊（如適用）
### 步驟 4：分析失敗原因
當發現執行失敗記錄時，可依以下步驟分析：
1. **檢查錯誤訊息**：
* 閱讀詳細錯誤描述
* 識別是配置問題、權限問題還是服務異常
2. **檢查輸入參數**：
* 確認 AI 傳遞的參數是否正確
* 檢查參數格式是否符合工具要求
3. **查看關聯對話**：
* 了解使用者提出什麼問題
* 判斷是否為特定問題類型導致失敗
4. **比對成功案例**：
* 找出相同工具的成功執行記錄
* 比較成功和失敗案例的差異
### 步驟 5：優化工具配置
根據執行記錄分析結果，採取改善措施：
1. **更新工具設定**：
* 修正錯誤的 API 金鑰或連線資訊
* 調整逾時時間設定
* 優化查詢參數或限制條件
2. **調整 AI 提示詞**：
* 如果參數經常錯誤，在提示詞中加入明確指引
* 說明工具的正確使用方式和參數格式
3. **改善錯誤處理**：
* 為常見錯誤情況加入友善的錯誤訊息
* 設定自動重試機制
4. **移除無用工具**：
* 如果工具長期未被使用，考慮移除以簡化配置
### 步驟 6：匯出執行記錄
1. 在工具執行記錄頁面點擊「匯出」按鈕
2. 選擇匯出格式（CSV 或 Excel）
3. 選擇時間範圍和篩選條件
4. 下載報告供進一步分析或存檔
{% hint style="info" %}
匯出的記錄可用於：
* 深度數據分析和趨勢追蹤
* 向技術團隊報告問題
* 定期檢討工具使用效率
* 合規性稽核和記錄保存
{% endhint %}
## 使用場景
### 場景 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 天未被使用（檢查是否需要）
### 文檔記錄建議
為每個工具建立使用文檔，記錄：
* 工具用途和適用場景
* 輸入參數說明和範例
* 預期輸出格式
* 常見錯誤和解決方式
* 優化歷史記錄
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.maiagent.ai/agent-ops/tool-execution-records.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.