本文档介绍了如何解决在将代理部署到 Agent Runtime 时可能遇到的错误。它涵盖了各种常见问题,包括序列化失败、权限错误和 VPC-SC 边界违规。
注意:如需搜索和过滤代理错误日志,请使用 Logs Explorer,将 RESOURCE TYPE 选择为“Vertex AI 推理引擎”,然后选择相应的 RESOURCE CONTAINER 值(即项目编号)和 REASONING ENGINE ID 值。
容器构建和启动错误
如果 Agent Runtime 在构建或启动智能体的容器时部署失败,则可能是以下某一问题导致的:
容器映像构建失败
问题:
部署失败,状态为 400、INVALID_ARGUMENT (REASONING_ENGINE_BUILD_FAILED),并显示类似于以下内容的消息:
The Reasoning Engine could not be deployed because its container image failed to build.
可能的原因:
当您从智能体对象、源文件或 Dockerfile 部署智能体时,Agent Runtime 会为智能体构建容器映像。如果以下任一步骤失败,则构建失败:
- 安装软件包要求:
requirements或源代码文件的要求文件中的软件包不存在、固定了不存在的版本、与其他软件包冲突,或者不支持代理的 Python 版本。 - 安装本地 wheel:
requirements中列出的 wheel 文件未包含在extra_packages中,因此无法安装。 - 运行安装脚本:
installation_scripts目录中的脚本退出并显示错误。 - 构建 Dockerfile:从 Dockerfile (
image_spec) 部署时,Dockerfile 中的指令失败。
推荐的解决方案:
- 检查错误元数据的
logs_url字段中关联的构建日志,找出失败的步骤。构建日志条目包含日志 IDreasoning_engine_build。如需查询日志,请参阅构建查询。 如需在本地重现失败,请在使用已部署智能体的 Python 版本的新虚拟环境中安装相同的要求,并修复
pip报告的所有错误:python -m venv agent-envagent-env/bin/pip install -r requirements.txt如需让 build 安装您在本地测试的版本,请固定软件包版本。请参阅定义软件包要求。
如果您安装本地 wheel,请将其同时包含在
requirements和extra_packages中。请参阅定义其他软件包。如果您使用安装脚本,请确保每个脚本在干净的环境中以根权限运行时都能成功退出。请参阅定义构建选项。
如果您从 Dockerfile 进行部署,请从相同的源文件在本地构建容器映像(例如,使用
docker build),并修复所有失败的指令。
不适用的解决方案:
- 在不更改要求、安装脚本或 Dockerfile 的情况下重试部署会以相同的方式失败,因为构建会运行相同的步骤。
容器映像构建超时
问题:
部署失败,状态为 504、DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT),并显示一条消息,指出智能体的容器映像未及时完成构建。
可能的原因:
当您从源文件部署时,Agent Runtime 会构建一个容器映像,用于安装您的代码及其依赖项。如果构建在允许的时间用尽时仍在运行,则部署会失败。构建通常会因安装的依赖项而耗时过长,例如:
requirements中的一长串软件包,包括代理不使用的软件包。- 没有针对构建环境的预构建 wheel 的软件包,这些软件包在构建期间从源代码编译。
- 未固定或松散固定的版本,这会减慢依赖项解析速度。
推荐的解决方案:
- 查看错误元数据的
logs_url字段中关联的构建日志,了解构建停止时正在运行哪个步骤。 - 移除不必要的依赖项,并固定所有必需软件包的版本。
- 优先考虑发布预构建 wheel 的软件包和版本,以便在构建期间不编译任何内容。
- 重试部署。由于与代码无关的原因,构建有时可能会比平时运行更长时间。
容器未能启动
问题:
部署失败,状态为 400、INVALID_ARGUMENT (REASONING_ENGINE_CONTAINER_FAILED_TO_START),并显示一条消息,指出代理的容器未在启动超时时间内开始提供服务。
可能的原因:
Agent Runtime 会在容器中启动智能体,并等待其接受请求。如果容器在启动超时之前退出或未响应,则部署会失败。常见原因可能包括:
- 缺少依赖项:您的智能体导入了未在
requirements或extra_packages中列出的软件包,因此加载智能体失败,并出现ModuleNotFoundError等错误。 - 软件包版本不匹配:部署的环境中安装的软件包与开发环境中的软件包不同,因此加载智能体失败,并显示
AttributeError: Can't get attribute等错误。请参阅序列化错误。 - 初始化期间出错:代理的
set_up()方法或在加载代理时运行的其他代码引发异常或等待无法访问的资源。 - 初始化缓慢:加载智能体所用的时间超过了启动超时时间。
- 自定义容器未监听:自定义容器必须在端口
8080上的0.0.0.0监听 HTTP 请求。请参阅运行时协定。 - Agent Gateway 阻止启动:当您通过 Agent Gateway 路由流量时,如果 Identity-Aware Proxy (IAP) 阻止初始化调用、智能体身份缺少所需角色,或者自定义容器不信任网关的根证书,则启动会失败。请参阅 Agent Runtime 启动期间出错和使用自定义容器 (BYOC) 部署的智能体无法连接到 Agent Gateway。
推荐的解决方案:
- 检查错误元数据的
logs_url字段中关联的代理日志,找出导致容器停止的错误。请参阅查看代理的日志。 - 将所有缺失的软件包添加到
requirements或extra_packages,并固定您在开发中使用的版本。 - 如需在本地重现故障,请在具有相同 Python 版本的干净环境中仅安装
requirements中列出的软件包,然后导入并实例化您的智能体。 - 将缓慢或容易出错的工作(例如连接到外部服务)移出代理初始化。
- 对于自定义容器,请确保服务器监听
0.0.0.0以及PORT环境变量中的端口(默认为8080)。
不适用的解决方案:
- 在不更改代理或其依赖项的情况下重试部署通常会以相同的方式失败,因为原因在于代理代码或其环境。
容器未能及时启动
问题:
部署失败,状态为 504、DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT),并显示一条消息,指出代理的容器未及时开始传送。
可能的原因:
构建映像后,Agent Runtime 会启动智能体的容器,并等待其准备好处理请求。如果容器在允许的时间用尽时仍在启动,则部署会失败。常见原因可能包括:
- 导入时工作缓慢,例如在导入代理模块时加载大型模型或文件。
- 代理的
set_up()方法中存在缓慢或阻塞的工作,例如等待无法访问的服务响应的网络调用。
推荐的解决方案:
- 检查错误元数据的
logs_url字段中关联的容器日志,了解启动在何处停滞。 - 将耗时的初始化操作移出模块导入时间,并尽量减少
set_up()fast 中的步骤数。推迟处理第一个请求不需要的工作。 - 确保代理在启动期间调用的任何服务都可从代理访问,并为这些调用设置超时,以便它们不会无限期地阻止启动。
- 如果容器日志显示代理正常启动,请重试部署。由于与代码无关的原因,启动有时可能需要比平时更长的时间。
预构建模板错误
如果您在部署期间遇到 LangchainAgent 模板方面的问题,可能是本部分中所述的某个问题所导致的。
内部服务器错误
问题:
您收到类似于以下内容的错误消息:
InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.
遗憾的是,这是针对运行时出现的任何容器相关问题的通用错误,可能的原因是可能发生的众多错误之一。
可能的原因:
LangchainAgent上的脏状态。如果在部署代理之前对LangchainAgent调用了.set_up(),则可能会发生这种情况。- 软件包版本不一致。如果开发环境中安装的软件包与 Agent Runtime 的远程环境中安装的软件包不同,则可能会发生这种情况。
推荐的解决方案:
LangchainAgent上的脏状态。实例化一个全新的LangchainAgent实例,或在部署代理之前从代码中移除agent.set_up()。- 软件包规范不一致。请参阅有关排查序列化错误的部分。
序列化错误
一般来说,在部署代理时,请务必确保“本地”环境和“远程”环境保持同步。您可以通过在部署代理时指定 requirements= 来确保这一点。
如果您遇到序列化方面的问题(与“pickle”或“pickling”相关的错误与“序列化”错误同义),则可能是由本部分中所述的某个问题所导致的。
Pydantic 版本
问题:
您收到类似于以下内容的错误消息:
PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator
可能的原因:
如果您的 pydantic 软件包低于版本 2.6.4,则可能会发生这种情况。如需检查您在使用的版本,请在终端中运行以下命令:
pip show pydantic推荐的解决方案:
在终端中运行以下命令以更新软件包:
pip install pydantic --upgrade在终端中运行以下命令,以验证您是否在使用 2.6.4 或更高版本:
pip show pydantic如果您在使用笔记本实例(例如 Jupyter、Colab 或 Workbench),则可能需要重启运行时才能使用更新后的软件包。
Cloudpickle 版本
问题:
您收到类似于以下内容的错误消息:
AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>
可能的原因:
如果开发环境和部署环境中的 cloudpickle 软件包版本不同,则可能会发生这种情况。如需检查您在开发中使用的版本,请在终端中运行以下命令:
pip show cloudpickle推荐的解决方案:
通过在部署代理时指定 requirements=,在两个环境(例如本地开发环境和远程部署的代理)中部署相同版本的 cloudpickle。
内部服务器错误
问题:
您收到类似于以下内容的错误消息:
InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.
可能的原因:
如果在部署代理时,sys_version= 与开发环境不同,则可能会发生这种情况。
推荐的解决方案:
部署代理后,请考虑从输入参数中移除 sys_version=。如果您仍然遇到问题,请提交 bug 报告。
Cloud Storage 存储桶错误
如果在部署时用于收集和上传代理的 Cloud Storage 暂存存储桶出现问题,则可能存在以下问题之一:
权限错误
推荐的解决方案:
如果您想使用预先存在的存储桶,请确保为使用 Agent Platform 而进行身份验证的主账号(您自己或某个服务账号)对此存储桶具有 Storage Admin 访问权限,并向服务账号授予权限。
或者,您可以在部署代理时指定新存储桶,SDK 将创建具有必要权限的存储桶。
如果您仍然遇到问题,请提交 bug 报告。
Cloud Storage 存储桶子目录未创建
问题:
您收到类似于以下内容的错误消息:
NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.
(当系统尝试复制到不存在的文件夹时,会发生 404 错误。)
可能的原因:
这可能是由于低于 1.49.0 版本的 google-cloud-aiplatform 版本中的字符串插值存在问题。此问题已在后续版本中得到修复。如需检查您在使用的 google-cloud-aiplatform 版本,请在终端中运行以下命令:
pip show google-cloud-aiplatform推荐的解决方案:
在终端中运行以下命令以更新软件包:
pip install google-cloud-aiplatform --upgrade在终端中运行以下命令,以验证您是否在使用 google-cloud-aiplatform 的 1.49.0 或更高版本:
pip show google-cloud-aiplatform如果您在使用笔记本实例(例如 Jupyter、Colab 或 Workbench),则可能需要先重启运行时,然后才能使用更新后的软件包。
VPC-SC 违规错误
如果您遇到 VPC-SC 方面的问题,则可能存在以下问题之一:
权限错误
问题:
您收到类似于以下内容的错误消息:
Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.
或者:
Request is prohibited by organization's policy.
可能的原因:
这很可能是因为 VPC-SC 边界中缺少必需的入站流量规则。
推荐的解决方案:
如果您在 VPC-SC 环境中使用 Agent Platform,则必须在边界中创建入站流量规则,以允许从 Reasoning Engine Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) 到 storage.googleapis.com 服务和 artifactregistry.googleapis.com 服务的入站流量。
自定义服务账号错误
如果您遇到服务账号方面的问题,则可能存在以下问题之一:
充当服务账号
问题:
您收到类似于以下内容的错误消息:
You do not have permission to act as service_account.
可能的原因:
您可能不拥有用于部署的自定义服务账号的 iam.serviceAccounts.actAs 权限。请注意,在具有多个自定义服务账号的多代理系统中,一个代理创建者或部署者可以充当一些服务账号。如果您在使用错误的服务账号,则出现此错误是预期行为
此外,如果自定义服务账号所在的项目与您部署代理的项目不同,并且服务账号项目中在强制执行 iam.disableCrossProjectServiceAccountUsage 组织政策,您也可能会遇到此错误。
如需查看此场景所需配置的完整列表,请参阅跨项目自定义服务账号。
推荐的解决方案:
确保您在使用预期的服务账号。检查您是否拥有此服务账号的 Service Account User (roles/iam.serviceAccountUser) 角色。如果不拥有,请让管理员向您授予此服务账号的相应角色。
如果您处于跨项目场景中,请检查您的服务账号项目是否强制执行了 iam.disableCrossProjectServiceAccountUsage 组织政策。如果是这样,请让管理员停用相应政策。
元数据服务器不可用
问题:
您收到类似于以下内容的错误消息:
ServiceUnavailable: 503 Getting metadata from plugin failed with error
或
Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token
可能的原因:
如果自定义服务账号和您的代理位于不同的项目中,并且 Agent Platform Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) 不拥有自定义服务账号的 iam.serviceAccounts.getAccessToken 权限,则可能会发生这种情况。
如需查看此场景所需配置的完整列表,请参阅跨项目自定义服务账号。
推荐的解决方案:
请让管理员向代理项目的 Agent Platform Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) 授予自定义服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。
Agent Platform Service Agent 应位于您用于部署代理的同一项目中。角色授予的 IAM 绑定应位于自定义服务账号所在的项目中。
环境预配失败
问题:
创建智能体失败,状态为 500、INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED),并显示一条消息,指出无法预配智能体的 Google 托管环境。
可能的原因:
在 Agent Runtime 首次在项目和区域中部署智能体之前,它会为您的智能体设置由 Google 管理的资源,例如服务代理和托管环境。如果此设置失败,该项目和区域中每个待处理的代理创建都会失败,并显示此错误。
推荐的解决方案:
与支持团队联系,并提供失败操作的名称,格式为 projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID。
不适用的解决方案:
- 重试代理创建无法解决此错误,因为 Google 必须先修复失败的设置。
- 更改代理的代码、要求或
resource_limits没有任何帮助,因为故障发生在 Agent Runtime 部署代理之前。 - 为项目申请增加配额没有任何效果,因为这些资源由 Google 管理。
资源用尽错误
如果您的部署失败,并显示 429、RESOURCE_EXHAUSTED 状态,则可能是以下某一问题导致:
超出 API 速率限制或配额
问题:
部署失败,状态为 Error 429 或 RESOURCE_EXHAUSTED。
可能的原因:
项目已超出其 API 速率限制或并发请求配额。
推荐的解决方案:
- 在部署脚本中实现指数退避算法和重试策略。
- 在 Google Cloud “Agent Platform API”的“配额”页面中,对照限额验证当前用量。
- 降低并发部署的频率。
区域暂时已达容量上限
问题:
部署失败,状态为 429、RESOURCE_EXHAUSTED,并显示一条消息,指出该区域的内存或 CPU 总允许量暂时已满。
可能的原因:
一个区域中的智能体部署会使用一个服务容量池,该容量池由 Agent Runtime 代表您管理,并由该区域中的所有客户共享。当池耗尽时,该区域中的新部署将失败,直到容量释放。
此限制不属于项目的配额。它不会显示在Google Cloud 配额页面上,也无法通过申请增加配额来提高。
推荐的解决方案:
- 部署到其他受支持的区域。这是解除部署屏蔽的最快方法。
- 用户可以稍后重试。区域容量不足是一个临时问题,通常会自行解决。
- 为智能体请求更少的内存或 CPU。较小的部署可能适合剩余容量。
- 如果某个区域中的部署一直以这种方式失败,请与支持团队联系。虽然我们无法提高限额,但您的报告有助于我们将容量分配到需要的地方。
不适用的解决方案:
- 删除现有代理不会释放此限制的容量,因为容量并非仅由您的项目使用。
- 申请增加配额没有任何效果,因为该限制不是项目配额。
实例数上限超出区域限制
问题:
部署失败,状态为 429、RESOURCE_EXHAUSTED,并显示一条消息,指出 spec.deployment_spec.max_instances 超过了该区域 resource_limits 中请求的 CPU 或内存支持的实例数量上限。
可能的原因:
部署智能体时,Agent Runtime 会将 spec.deployment_spec.max_instances 乘以 spec.deployment_spec.resource_limits 中每个实例的 cpu 和 memory,并检查此单个智能体的峰值分配是否在底层服务项目的区域限制范围内。如果您未指定 max_instances,Agent Runtime 会应用默认值(例如 200),在限制较低的区域中,该值乘以配置的每个实例的 cpu 或 memory 时,可能会超过支持的实例数上限。
推荐的解决方案:
- 将
spec.deployment_spec.max_instances设置为出错提示中显示的最大值(或更小值)。 - 减少
spec.deployment_spec.resource_limits中的每个实例cpu或memory值。 - 将代理部署到具有更高限制的其他受支持的区域。
不适用的解决方案:
- 在项目的 Google Cloud “配额”页面上申请增加配额没有任何效果,因为此限制是在 Google 管理的服务项目中强制执行的,而不是在您的项目中。
- 删除项目中的其他代理或在不更改
max_instances或resource_limits的情况下重试并不能解决此错误,因为该检查会根据静态限制评估单个部署的峰值分配。
Agent Gateway 查找受到限制
问题:
部署或更新使用 Agent Gateway 的代理失败,并显示 429、RESOURCE_EXHAUSTED 状态 (REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) 和类似于以下内容的消息:
The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.
可能的原因:
在部署或更新开始之前,Agent Runtime 会在智能体的 spec.deployment_spec.agent_gateway_config 中查找每个 Agent Gateway,以验证请求。此错误表示查找操作暂时受到速率限制。请求会在部署或更新开始之前被拒绝,因此您的代理不会创建或更改。
推荐的解决方案:
- 请等待大约一分钟,然后重试部署或更新。
- 在自动化工作流中,使用指数退避算法重试请求。
- 如果错误仍然存在,请与支持团队联系。
不适用的解决方案:
- 更改智能体的代码、
requirements或resource_limits无法解决此错误,并且检查容器或 Agent Gateway 流量日志也不会显示错误,因为请求在 Agent Runtime 构建或启动智能体的容器之前就被拒绝了。
Secret Manager 访问错误
问题:
部署失败,状态为 400、INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED),并显示类似于以下内容的消息:
The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).
可能的原因:
NOT_FOUND:secret_env中指定的 Secret ID 或版本 ID 在 Secret Manager 中不存在(与部署的智能体不在同一项目中),或者包含拼写错误。DESTROYED或DISABLED:Secret Manager 中引用的 Secret 版本处于已销毁或已停用状态。PERMISSION_DENIED:在基于服务账号的部署(自定义service_account或默认 AI Platform Reasoning Engine Service Agent)中,在部署验证期间,配置的服务账号对引用的 Secret 没有 Secret Manager Secret Accessor 角色 (roles/secretmanager.secretAccessor)。
推荐的解决方案:
- 对于
NOT_FOUND、DESTROYED或DISABLED:- 在您要部署代理的项目的 Secret Manager 页面中,验证
secret_env中引用的每个SECRET_ID和VERSION_ID是否存在且处于已启用状态。 - 如果引用的版本已停用或销毁,请启用有效版本或更新
secret_env以引用已启用的版本。
- 在您要部署代理的项目的 Secret Manager 页面中,验证
对于
PERMISSION_DENIED:按照管理对 Secret 的访问权限中的说明,向代理上配置的专用自定义服务账号授予特定 Secret 的 Secret Manager Secret Accessor 角色 (roles/secretmanager.secretAccessor)(或切换到隔离的代理身份)。
将 secret_env 与 AGENT_IDENTITY 搭配使用时容器启动失败
问题:
配置了 identity_type = AGENT_IDENTITY 和 secret_env 的代理在容器启动期间失败或超时(而不是在部署验证期间返回 REASONING_ENGINE_SECRET_ACCESS_DENIED)。
可能的原因:
对于 AGENT_IDENTITY 部署,Agent Runtime 会跳过部署时 Secret 访问权限验证,并在容器启动时提取引用的 Secret。如果您在初始创建期间(在预配的代理身份存在并被授予访问权限之前)传递 secret_env,如果预配的代理身份在引用的 Secret 上缺少 roles/secretmanager.secretAccessor,或者如果引用的 Secret 版本缺失 (NOT_FOUND)、停用 (DISABLED) 或销毁 (DESTROYED),则容器启动会反复无法提取 Secret。
推荐的解决方案:
- 先创建不含
secret_env的AGENT_IDENTITY代理。 - 按照管理对 Secret 的访问权限中的说明,向智能体预配的智能体身份授予对特定 Secret 的
roles/secretmanager.secretAccessor权限(在指定 IAM 成员时,在spec.effective_identity前面加上principal://,例如--member="principal://EFFECTIVE_IDENTITY")。 - 验证每个引用的 Secret 版本是否存在且已启用,并更新代理以附加
secret_env。限制智能体的aiplatform.reasoningEngines.update权限,以便只有获得授权的主账号才能修改以其身份运行的代码。
Agent Gateway 绑定错误
如果您通过 Agent Gateway 路由流量,并且在代理启动之前部署或更新代理失败,则可能是以下某一问题导致的:
Agent Gateway 绑定超时
问题:
部署或更新代理失败,并显示 504、DEADLINE_EXCEEDED 状态 (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) 和类似于以下内容的消息:
The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.
可能的原因:
同一项目和区域中的 Agent Runtime 智能体共享与每个已配置的 Agent Gateway 的一个绑定。设置或拆除共享绑定可能比将代理附加到活跃绑定多花几分钟时间。如果同一项目和区域中的其他绑定或解除绑定操作未在允许的时间内完成,则您的部署或更新会超时。常见原因可能包括:
- 并发初始绑定:在初始共享设置完成之前,您将多个智能体绑定到同一项目和区域中的 Agent Gateway。
- 正在解除绑定:您解除绑定或删除项目和区域中最后一个与网关绑定的智能体,然后在共享拆解完成之前将另一个智能体绑定到同一网关或不同网关。
- 在绑定失败后重试:绑定网关的部署或更新失败,您在 Agent Runtime 完成清理失败的设置之前重试。
推荐的解决方案:
- 等待几分钟,让错误中指定的网关上的其他操作完成,然后重试部署或更新。
- 如需在没有有效 Agent Gateway 绑定的项目和区域中绑定多个智能体,请先绑定一个智能体,然后等待该操作成功。然后同时部署或更新其余代理。
- 在自动化工作流中,请避免在绑定其他代理之前立即解除绑定或删除项目和区域中最后一个绑定到网关的代理。移除最后一个绑定到网关的代理会拆除共享绑定,因此下次部署会重复完整设置。
不适用的解决方案:
- 检查容器日志或 Agent Gateway 流量日志不会显示此失败的错误,因为超时发生在 Agent Runtime 启动智能体容器之前。
- 更改代理的代码、
requirements或resource_limits不会缩短共享绑定设置时间。
如果网关绑定成功,但容器随后无法启动,请参阅 Agent Runtime 启动期间出错。
Agent Gateway 绑定已中止
问题:
部署或更新代理失败,状态为 409、ABORTED (REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED),并显示类似于以下内容的消息:
The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.
可能的原因:
同一项目和区域中的 Agent Runtime 智能体与每个已配置的 Agent Gateway 共享一个绑定。如果您在设置网关的共享绑定之前将多个代理绑定到同一网关,则一个部署或更新会设置绑定,而其他部署或更新会等待绑定。如果该部署或更新在绑定准备就绪之前失败,Agent Runtime 会回滚绑定,并且等待该绑定的每个部署或更新都会失败,并显示此错误。设置绑定的部署或更新会报告其自身的错误,这些错误可能与 Agent Gateway 无关。
推荐的解决方案:
- 请等待至少 10 分钟,让 Agent Runtime 完成失败设置的回滚,然后重试部署或更新。在回滚完成之前启动的重试可能会失败,并显示
504、DEADLINE_EXCEEDED状态。请参阅Agent Gateway 绑定超时。 - 如需重试多个部署或更新,请先重试一个,等待该操作成功,然后同时重试其余操作。如果第一个操作失败,它会返回底层错误,而不是
409、ABORTED(例如,Agent Gateway 绑定暂时不可用或容器映像构建失败),您可以在错误目录中查一查这些错误。
不适用的解决方案:
- 检查容器日志或 Agent Gateway 流量日志不会显示此失败的错误,因为失败发生在 Agent Runtime 启动智能体的容器之前。
- 更改代理的代码、
requirements或resource_limits没有任何帮助,因为此错误是由其他部署或更新引起的,而不是由您的代理引起的。
Agent Gateway 绑定暂时不可用
问题:
部署或更新代理失败,状态为 503、UNAVAILABLE (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE),并显示类似于以下内容的消息:
The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.
可能的原因:
当某个项目和区域中的第一个智能体绑定到 Agent Gateway 时,Agent Runtime 会设置由 Google 管理的共享网络资源,用于将智能体连接到网关。如果此设置所依赖的 Google Cloud服务在多次自动重试后仍持续返回临时错误,Agent Runtime 会回滚设置,并且部署或更新会失败,并显示此错误。等待同一设置的其他部署或更新会失败,并显示 409、ABORTED 状态。请参阅Agent Gateway 绑定已中止。
推荐的解决方案:
- 请等待至少 10 分钟,让 Agent Runtime 完成失败设置的回滚,然后重试部署或更新。在回滚完成之前启动的重试可能会失败,并显示
504、DEADLINE_EXCEEDED状态。请参阅Agent Gateway 绑定超时。 - 如果多次重试后错误仍然存在,请与支持团队联系,并提供失败操作的名称(格式为
projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID)。
不适用的解决方案:
- 更改代理的代码、
requirements或resource_limits无济于事,因为故障发生在 Agent Runtime 部署代理之前。 - 为项目申请增加配额不会产生任何影响,因为这些网络资源由 Google 管理。
支持资源
如果问题仍未解决,请参阅我们的支持指南以获取帮助。