本文档介绍了如何解决在为代理运行时设置环境时可能遇到的错误。本文档介绍了针对软件包导入问题的排查步骤。
导入 Agent Platform SDK 时出错
如果您无法导入 Agent Platform SDK for Python，可能是因为以下问题之一：
过时的 Agent Platform SDK for Python 版本
问题：
您收到类似于以下内容的错误消息：
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 的已知问题。