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

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

故障診斷

本節涵蓋使用自訂客服人員時可能遇到的常見問題，以及如何解決這些問題。

組態錯誤

無效的 JSON 語法

問題：自訂代理程式無法載入 JSON 剖析錯誤。

徵狀：

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

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

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

解決方案：

  • 使用 JSON 驗證器或 linter 驗證您的 JSON

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

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

    • 在最後一個元素之後追蹤逗號

    • 不相符的括號或括號

    • 字串值中的未逸出引號

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

結構描述驗證錯誤

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

徵狀：

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

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

  • 缺少必要欄位錯誤

解決方案：

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

  • 檢查欄位名稱是否有錯字 （例如， allowedTools vs 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 模式是否與預期檔案相符

  • 確保勾點命令成功執行並產生輸出

  • 手動測試勾點命令，以確認它們在您的環境中運作

  • 如果命令正在中斷，請檢查勾點逾時設定

MCP 伺服器問題

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

解決方案：

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

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

  • 獨立測試 MCP 伺服器，以確保它們正常運作

  • 檢閱 MCP 伺服器日誌是否有錯誤訊息

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

  • 如需 MCP 疑難排解的詳細資訊，請參閱搭配 Amazon Q Developer 使用 MCP

測試自訂代理程式組態

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

  1. 使用 JSON 驗證器驗證 JSON 語法

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

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

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

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

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

  7. 測試常見的工作流程，以確保自訂代理程式如預期般運作

取得其他協助

如果您持續遇到客服人員的問題：