在 Agent Runtime 中使用智能体时进行问题排查

本文档介绍了如何解决在使用代理时可能遇到的错误。

注意:如需搜索和过滤代理错误日志,请使用 Logs Explorer,将 RESOURCE TYPE 选择为“Vertex AI 推理引擎”,然后选择相应的 RESOURCE CONTAINER 值(即项目编号)和 REASONING ENGINE ID 值。

操作架构为空

如果您的代理从 .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 错误

如果您没有所需的权限,您的查询可能会失败。

Agent Platform 扩展程序权限

问题

您可能会收到类似于以下内容的 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}"
}
]

您的代理没有 Agent Platform 扩展程序权限。如需将 Agent Platform 扩展程序与 Agent Runtime 搭配使用,请向您的代理身份服务账号授予 Agent Platform User (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)。

推荐的解决方案:

确保您的服务账号具有错误消息中列出的适当 Identity and Access Management (IAM) 权限。您可能缺少的 IAM 权限的一个例子是 aiplatform.endpoints.predict。如需了解详情,请参阅为代理设置身份和权限。

请求在到达您的代理之前被拒绝

如果您的请求在 Agent Runtime 将其发送到您的代理之前失败,则可能是以下某一问题导致的:

找不到智能体

问题:

请求失败,并显示 404、NOT_FOUND 状态 (REASONING_ENGINE_NOT_FOUND) 和类似于以下内容的消息:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` was not found.

可能的原因:

  • 请求中的项目、位置或资源 ID 不正确。
  • 智能体已删除。

推荐的解决方案:

  • 将出错提示中的资源名称与已部署的代理进行比较。请参阅列出已部署的代理。
  • 确保您的客户端将请求发送到您部署智能体的项目和区域。

智能体未处于活跃状态

问题:

请求失败,并显示 403、PERMISSION_DENIED 状态 (REASONING_ENGINE_NOT_ACTIVE) 和类似于以下内容的消息:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` is not active, so it can't serve requests.

可能的原因:

  • 代理仍在创建中。
  • 未能创建智能体。
  • 正在删除代理。

推荐的解决方案:

  • 如果您刚刚创建了代理,请等待创建完成,然后重试请求。
  • 如果代理创建失败,请查看错误元数据的 logs_url 字段中链接的日志,找出原因。请修正错误,然后重新部署代理。请参阅排查智能体部署问题。

代理没有正在运行的实例

问题:

请求失败,并显示 400、FAILED_PRECONDITION 状态 (REASONING_ENGINE_NO_RUNNING_INSTANCES) 和类似于以下内容的消息:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` has no running instances because no agent is deployed to it.

可能的原因:

资源存在,但在创建或更新期间未指定要部署的智能体(对象、源文件或容器映像)。

推荐的解决方案:

使用要部署的代理更新资源。请参阅更新已部署的代理。

未定义 A2A 方法

问题:

A2A 请求失败,并显示 400、FAILED_PRECONDITION 状态 (REASONING_ENGINE_A2A_NOT_CONFIGURED) 和类似于以下内容的消息:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` does not define A2A methods, so it can't serve A2A requests.

可能的原因:

您向一个并非 A2A 智能体的智能体发送了 A2A 请求,例如请求智能体卡片或发送消息。

推荐的解决方案:

请求载荷过大

问题:

请求失败,并显示 400、FAILED_PRECONDITION 状态 (REASONING_ENGINE_REQUEST_TOO_LARGE) 或 HTTP 413 Request Entity Too Large 错误,以及类似于以下内容的消息:

The request to the Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` exceeds the 32 MiB maximum HTTP payload size (about 24 MiB for Base64-encoded files).

可能的原因:

  • Agent Runtime 强制执行固定的 32 MiB HTTP 请求正文大小上限。
  • 在 JSON 中采用 Base64 编码的内嵌文件附件会扩大约 33%,因此大于约 24 MiB 的文件会超出 32 MiB 的载荷限制。
  • 在多轮对话中,累积的对话历史记录和请求载荷中发送的先前附件会导致总请求正文超过 32 MiB。

推荐的解决方案:

  • 将大文件上传到 Cloud Storage,并在请求中传递 gs:// URI,而不是内嵌的 Base64 编码字节。
  • 在发送大型附件之前,请先对其进行压缩、拆分或缩减,使序列化 HTTP 请求正文的总大小保持在 32 MiB(约 24 MiB 的原始文件)以下。
  • 当多轮对话上下文接近上限时,请发起新对话或从对话记录中剪除较早的附件。

推理引擎执行失败

如果您在查询代理时收到“推理引擎执行失败”错误消息,则可能是由本部分中所述的某个问题所导致的。

.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 模型配额管理流程增加配额。或者,您也可以对测试进行速率限制,然后稍后重试。

推理引擎 ID 不正确

问题:

您可能会收到一条错误消息,指出推理引擎执行失败,详情为 Not Found。

可能的原因:

如果您在查询智能体时使用了错误的推理引擎 ID,则可能会发生此错误。

推荐的解决方案:

验证您是否为智能体使用了正确的推理引擎 ID。

支持资源

如果问题仍未解决,请参阅我们的支持指南以获取帮助。