故障診斷 - Amazon Q Developer
組態錯誤自訂代理程式載入問題工具許可問題對自訂代理程式行為偵錯取得其他協助

故障診斷

本節涵蓋使用自訂代理程式時可能遇到的常見問題，以及如何解決這些問題。

組態錯誤

無效的 JSON 語法

問題：自訂代理程式載入失敗且顯示 JSON 剖析錯誤。

徵狀：

  • 提到「無效的 JSON」或「語法錯誤」的錯誤訊息

  • 自訂代理程式未出現在 /agent list 中

  • 回復到預設代理程式行為

解決方案：

  • 使用 JSON 驗證程式或 linter 驗證您的 JSON

  • 檢查是否有常見的 JSON 錯誤：

    • 陣列元素或物件屬性之間缺少逗號

    • 最後一個元素後方有逗號

    • 括弧或括號不成對

    • 字串值中有未逸出的引號

  • 使用 /agent schema 驗證您的組態結構

結構描述驗證錯誤

問題：自訂代理程式組態與預期的結構描述不相符。

徵狀：

  • 關於未知組態欄位的警告

  • 自訂代理程式行為與組態不符

  • 缺少必要欄位錯誤

解決方案：

  • 使用 /agent schema 比對您的組態與結構描述

  • 檢查欄位名稱是否有錯字 (例如 allowedTools 與 allowedTool)

  • 確認資料類型符合結構描述需求 (陣列與字串、布林值與字串)

  • 檢閱補充 Amazon Q Developer CLI 文件中的代理程式格式文件，了解語法是否正確

自訂代理程式載入問題

找不到自訂代理程式

問題：自訂代理程式未出現在清單中或無法使用。

徵狀：

  • /agent list 未顯示您的自訂代理程式

  • /agent use [name] 失敗並顯示「找不到代理程式」

  • 回復到預設代理程式且未顯示警告

解決方案：

  • 確認自訂代理程式檔案位於正確位置：

    • 全域：~/.aws/amazonq/cli-agents/[name].json

    • 本機：amazonq/cli-agents/[name].json

  • 檢查檔案許可 - 確認檔案可讀

  • 確認檔案名稱與您嘗試使用的自訂代理程式名稱相符

  • 確認檔案副檔名為 .json

載入錯誤的自訂代理程式版本

問題：載入與預期不同的自訂代理程式版本。

徵狀：

  • 自訂代理程式行為與您最近的組態變更不相符

  • 有關自訂代理程式衝突的警告訊息

  • 非預期的工具可用性或許可

解決方案：

  • 檢查本機目錄與全域目錄之間是否有自訂代理程式名稱衝突

  • 請記住，本機自訂代理程式優先順序高於全域自訂代理程式

  • 使用 /agent list 查看載入哪個版本

  • 必要時，移除或重新命名衝突的自訂代理程式檔案

工具許可問題

工具無法使用

問題：自訂代理程式無法存取您設定的工具。

徵狀：

  • 有關未知或無法使用工具的錯誤訊息

  • 自訂代理程式使用 allowedTools 要求工具的許可

  • MCP 伺服器工具無法運作

解決方案：

  • 確認 tools 陣列中的工具名稱拼寫正確

  • 對於 MCP 工具，確定已在 mcpServers 中正確設定伺服器

  • 檢查 MCP 伺服器是否正在執行且可存取

  • 使用 MCP 工具的正確語法：@server_name/tool_name

  • 對照補充 Amazon Q Developer CLI 文件中的內建工具文件，確認內建工具名稱

/tools 命令傳回空的清單

問題：/tools 命令顯示沒有可用工具，或可用工具數低於預期。

徵狀：

  • /tools 傳回空的清單

  • 工具清單中缺少預期的工具

  • 自訂代理程式似乎沒有功能

常見原因：

  • 自訂代理程式組態中包含空的 tools 陣列

  • tools 陣列內的工具名稱有錯字

  • MCP 伺服器工具名稱不正確 (缺少伺服器字首)

  • MCP 伺服器組態問題阻止工具載入

解決方案：

  • 檢查您的自訂代理程式組態內的 tools 陣列是否包含有效的工具名稱

  • 確認工具名稱拼寫正確 (區分大小寫)

  • 對於 MCP 工具，確定您使用正確的伺服器字首格式：server-name___tool-name

  • 使用預設代理程式進行測試，以確認工具可用：q chat 接著 /tools

  • 若是使用外部工具，查看 MCP 伺服器狀態

非預期的許可提示

問題：自訂代理程式針對您認為已預先核准的工具提示許可。

徵狀：

  • allowedTools 中所列工具的許可提示

  • 儘管有自訂代理程式組態，工作流程仍中斷

解決方案：

  • 確認 tools 和 allowedTools 陣列中都有列出工具

  • 檢查兩個陣列之間的工具名稱是否有錯字

  • 對於 MCP 工具，請在 allowedTools 中使用加上伺服器字首的完整名稱

  • 確認已正確套用 toolAliases

對自訂代理程式行為偵錯

缺少內容或資源

問題：自訂代理程式似乎無法存取預期的檔案或內容。

解決方案：

  • 確認 resources 陣列中的檔案路徑正確且檔案存在

  • 檢查資源中的 glob 模式是否與期望的檔案相符

  • 確定 hook 命令成功執行且產生輸出

  • 手動測試 hook 命令，確認其在您的環境中正常運作

  • 如果命令遭到切斷，請查看 hook 逾時設定

MCP 伺服器問題

問題：MCP 伺服器無法運作或工具無法使用。

解決方案：

  • 驗證 MCP 伺服器命令是否正確，且可執行檔位於 PATH 中

  • 檢查是否已設定必要的環境變數

  • 單獨測試 MCP 伺服器，確認其正常運作

  • 檢閱 MCP 伺服器日誌中的錯誤訊息

  • 如果伺服器啟動速度緩慢，請增加逾時值

  • 如需更多 MCP 故障診斷的資訊，請參閱使用 MCP 搭配 Amazon Q Developer

測試自訂代理程式組態

若要系統化地測試您的自訂代理程式組態：

  1. 使用 JSON 驗證程式驗證 JSON 語法

  2. 使用 /agent schema 對照檢查組態與結構描述

  3. 使用 /agent list 測試自訂代理程式載入

  4. 使用 /agent use [name] 切換至自訂代理程式

  5. 個別測試每一項工具，以驗證存取權和許可

  6. 驗證資源和關聯是否提供預期的內容

  7. 測試常見的工作流程，確認自訂代理程式的行為如預期

取得其他協助

如果您持續遇到代理程式的問題：

  • 檢閱補充 Amazon Q Developer CLI 文件中完整的代理程式組態文件

  • 查看內建工具參考以了解工具特定組態

  • 參閱 MCP 文件以了解 MCP 相關問題

  • 從較簡單的代理程式組態開始著手，並逐步增加複雜性

  • 比較您的組態與代理程式範例和使用案例中的範例

  • 請記住，代理程式切換和編輯需要啟動新的聊天工作階段，而非使用工作階段內命令