本文說明如何解決設定 Agent Runtime 環境時可能遇到的錯誤，並涵蓋套件匯入問題的疑難排解步驟。
匯入 Agent Platform SDK 時發生錯誤
如果無法匯入 Agent Platform SDK for Python，可能是因為發生下列任一問題：
Python 專用 Agent Platform SDK 版本過舊
問題：
您會收到類似以下的錯誤訊息：
ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'
或
ImportError: cannot import name 'agent_angines' from 'vertexai'
可能原因：
如果 google-cloud-aiplatform 套件版本早於 1.82.0 (適用於 agent_engines) 或 1.47.0 (適用於 reasoning_engines)，就可能發生這種情況。如要查看 google-cloud-aiplatform 套件版本，請在終端機中執行下列指令：
pip show google-cloud-aiplatform建議解決方案：
在終端機中執行下列指令，更新 google-cloud-aiplatform 套件：
pip install google-cloud-aiplatform --upgrade執行下列指令，確認更新後的版本為 1.82.0 以上：
pip show google-cloud-aiplatform如果您位於筆記本執行個體 (例如 Jupyter、Colab 或 Workbench)，可能需要重新啟動執行階段，才能使用更新後的套件。
401 授權錯誤
問題：
您會收到類似以下的錯誤訊息：
Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"
或
Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
可能原因：
根據預設，當您將代理程式身分與代理程式執行階段搭配使用時，系統會使用憑證繫結存取權杖進行驗證，防止權杖遭竊。在下列兩種情況中，執行階段可能會發生 401 錯誤：
- 使用者或代理嘗試在核發存取權杖的環境外使用權杖，例如在代理之間傳遞權杖。
- 代理程式呼叫不相容於 mTLS 的 API 端點，例如 telemetry.googleapis.com，而非 telemetry.mtls.googleapis.com。
建議解決方案：
在情境 1 中，如果您有正當理由要在代理之間共用權杖，可以選擇停用預設的情境感知存取權 (CAA) 政策。強烈建議不要這麼做，因為這會導致代理程式容易遭竊憑證。
建立 Agent Runtime 執行個體時，請設定下列環境變數，選擇不採用預設的 CAA 政策：
config={
"env_vars": {
"GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
}
}
在情境 2 中，您同樣可以將 GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES 變數設為 False，允許代理程式使用非 mTLS API 端點做為暫時的因應措施。在這種情況下，根本問題可能是 ADK 的已知問題。