本文說明如何解決使用 [代理程式](/agent-builder/agent-engine/use/overview)時可能遇到的錯誤。
作業結構定義為空白
如果代理程式從 .operation_schemas() 傳回空白清單，可能是下列任一問題所致：
建立代理時無法產生結構定義
問題：
部署代理程式時，您會收到類似下列內容的警告：
WARNING:vertexai.agent_engines:failed to generate schema: issubclass() arg 1 must be a class
可能原因：
如果您在 1.49.0 之前的 google-cloud-aiplatform 版本上，使用預先建構的 LangchainAgent 範本部署代理程式，可能會發生這項警告。如要查看目前使用的版本，請在終端機中執行下列指令：
pip show google-cloud-aiplatform建議解決方案：
在終端機中執行下列指令，更新 google-cloud-aiplatform 套件：
pip install google-cloud-aiplatform --upgrade更新 google-cloud-aiplatform 套件後，請執行下列指令，確認版本為 1.49.0 以上：
pip show google-cloud-aiplatform如果您位於筆記本執行個體 (例如 Jupyter、Colab 或 Workbench)，可能需要重新啟動執行階段，才能使用更新後的套件。確認 google-cloud-aiplatform 版本為 1.49.0 以上後，請嘗試再次部署代理程式。
查詢代理時發生 PermissionDenied 錯誤
如果沒有必要權限，查詢可能會失敗。
Vertex AI 擴充功能權限
問題
您可能會收到類似下列內容的 PermissionDenied 錯誤：
Permission 'aiplatform.extensions.get' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/extensions/
{EXTENSION}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.extensions.get"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/extensions/{EXTENSION}"
}
]
您的代理程式沒有 Vertex AI 擴充功能權限。如要搭配 Vertex AI Agent Engine 使用 Vertex AI 擴充功能，請將 Vertex AI 使用者 (roles/aiplatform.user) 角色授予代理程式身分服務帳戶。詳情請參閱「為代理程式設定身分和權限」。
LLM 權限
問題：
您可能會收到類似下列內容的 PermissionDenied 錯誤：
PermissionDenied: 403 Permission 'aiplatform.endpoints.predict' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/
google/models/{MODEL}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.endpoints.predict"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL}"
}
]
可能原因：
您的代理程式身分服務帳戶可能沒有適當的權限，無法查詢大型語言模型 (LLM)。
建議解決方案：
請確認服務帳戶具備錯誤訊息中列出的適當身分與存取權管理 (IAM) 權限。您可能缺少的 IAM 權限範例為 aiplatform.endpoints.predict。詳情請參閱「為代理程式設定身分和權限」。
Reasoning Engine 執行失敗
查詢代理程式時，如果收到「Reasoning Engine Execution failed」錯誤訊息，可能是本節所述的問題所致。
.query() 的輸入內容無效
問題：
您可能會收到類似下列內容的 FailedPrecondition 錯誤：
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"Invalid request: `{'query': ...}`"}
可能原因：
如果您將查詢的輸入內容指定為位置引數，而非關鍵字引數，就會發生這個錯誤。舉例來說，您會呼叫 agent.query(query_str)，而不是 agent.query(input=query_str)。
建議解決方案：
查詢已部署的推理引擎執行個體時，請將所有輸入內容指定為關鍵字引數。
Gemini 模型配額用完
問題：
您可能會收到類似下列內容的錯誤訊息，表示錯誤是因呼叫 Gemini 而引發：
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.ResourceExhausted: 429 Unable to submit request because the service is temporarily out of capacity. Try again later."}
或顯示其他錯誤訊息：
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.InternalServerError: 500 Internal error occurred."}
可能原因：
如果最近傳送的要求過多，導致 Gemini 模型配額用盡，就可能發生這種情況。
建議解決方案：
請按照 Gemini 模型配額管理程序提高配額。 或者，您也可以限制測試頻率，然後再試一次。
Reasoning Engine ID 錯誤
問題：
您可能會收到錯誤訊息，指出「Reasoning Engine Execution failed with a detail of Not Found」。
可能原因：
如果查詢代理程式時使用的 Reasoning Engine ID 不正確，就可能發生這個錯誤。
建議解決方案：
確認您為代理程式使用正確的 Reasoning Engine ID。
資源用盡或達到頻率限制錯誤 (錯誤 429)
問題：
部署作業失敗，狀態為 Error 429 或 RESOURCE_EXHAUSTED。
可能原因：
專案已超過 API 頻率限制或並行要求配額。
建議的解決方案：
- 在部署指令碼中實作指數輪詢和重試策略。
- 在「Vertex AI API」的「配額」頁面 Google Cloud 中，確認目前的用量是否超出限制。
- 減少並行部署的頻率。
支援資源
如果問題仍未解決，請參閱支援指南尋求協助。