本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AgentCore 运行时故障排除

本疑难解答主题可帮助您识别和解决使用 AgentCore Runtime 时的常见问题。通过遵循这些解决方案，您可以快速诊断和修复代理运行时的问题。

我的代理调用失败，显示 “此运行时不是” MMDSv2-enabled ValidationException

发生这种情况时：通过InvokeAgentRuntime、、ExecuteCommandInvokeAgentRuntimeWithWebSocketStream、或调用代理运行时InvokeAgentRuntimeCommandShell时 GetAgentCard

为什么会发生这种情况：从 2026 年 6 月 30 日起，亚马逊 Bedrock Run AgentCore time 要求所有代理运行时使用 MMDSv2（微虚拟机元数据服务版本 2）。该服务拒绝针对未metadataConfiguration设置或设置为或的运行时调用requireMMDSV2。false null

解决方案：在requireMMDSV2设置UpdateAgentRuntime为 true in 的情况下进行通话metadataConfiguration：

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

更新后，新的调用将成功。现有会话不受影响。

我的代理调用失败，出现 504 网关超时错误

发生这种情况时：在通过 SDK 或控制台调用代理期间

为什么会发生这种情况：多种因素可能会阻止您的代理在超时时间内做出响应

有几个因素可能导致这种情况：

在提取 Python 基础镜像时，我的 Docker 构建失败并显示 “403 禁止”

发生这种情况时：在使用public.ecr.aws基础映像期间docker build或使用docker run时

为什么会发生这种情况：ECR 公共身份验证问题——身份验证过期或缺失是一个常见问题。

解决方案：要么登录 ECR Public，要么完全注销：

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

使用 boto3 时出现 “未知服务：'基岩代理核心运行时'” 错误

发生这种情况时：使用 boto3 SDK 调用亚马逊 Bedrock AgentCore API 时

为什么会发生这种情况：过时的 boto3 库 — 常见问题，因为大多数安装没有最新的 SDK

解决方案：更新到最新的 boto3 和 botocore 版本：

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

我在尝试创建亚马逊 Bedrock R AgentCore untim AccessDeniedException e 时得到 “”

发生这种情况时：在通过控制台、SDK 或 CLI 创建代理期间

为什么会发生这种情况：要么您的用户缺乏权限，要么没有为 Amazon Bedrock 正确配置执行角色 AgentCore

解决方案：有几个因素可能导致这种情况：

我的 Docker 构建因 “exec/bin/sh: exec 格式错误” 而失败

发生这种情况时：为 Amazon Bedrock AgentCore 部署构建容器时

为什么会发生这种情况：在没有适当的跨平台设置的情况下在 x86 系统上构建 ARM64 容器

解决方案：构建兼容 ARM64 的容器。你可以考虑使用 buildx 进行跨平台构建。或者，你可以使用 CodeBuild。有关示例代码，请参阅亚马逊基岩 AgentCore 示例。

对与亚马逊基岩 AgentCore 运行时一起使用的 Docker 容器有哪些要求？

查看亚马逊 Bedrock AgentCore 运行时要求，了解完整详情。

总而言之，你的 Docker 容器必须满足以下要求：

我长时间运行的工具会在 15 分钟后中断

有关信息，请参阅使用 Amazon Bedrock AgentCore Runtime 处理异步和长时间运行的代理，了解完整详细信息。

发生这种情况时：在长时间运行的代理操作或复杂的工作流程中

为什么会发生这种情况：Amazon Bedrock AgentCore 会在闲置 15 分钟后自动终止会话。该平台根据/ping响应来确定活动：会话报告HealthyBusy保持活动状态，而会话报告Healthy被视为空闲状态，其空闲时间是从status上次更改时开始计算的（参见下面的time_of_last_update字段）。

解决方案：确保您的/ping终端节点在后台工作进行HealthyBusy时返回：

{"status": "HealthyBusy"}

如果你使用的是 Bedrock AgentCore SDK，则会自动处理 ping 响应。对于自定义实现，请确保您的 ping 处理程序HealthyBusy在处理时返回。

我的空闲会话没有被释放，我的会话配额已经用完了

发生这种情况时：会话数在负载下持续攀升，即使每个会话都处于空闲状态，在空闲超时（例如，突发调用期间的ServiceQuotaExceededException/maxVms错误）之后不会释放会话。

为什么会发生这种情况：当会话报告时Healthy，平台会衡量它在/ping响应中的time_of_last_update字段中空闲了多长时间，这必须反映出status上次更改的时间。如果您的 ping 处理程序设置time_of_last_update为每次 ping 的当前时间，则报告的空闲时间会继续重置，从而防止空闲超时触发。然后，会话将持续到您的会话配额MaxLifetime并可能耗尽您的会话配额。

解决方案：time_of_last_update仅在status实际发生变化时进行更新，或者将其完全省略，以便平台自行跟踪状态变化：

{"status": "Healthy"}

如果您使用的是 Bedrock AgentCore SDK，请升级到最新版本，该版本可以正确处理 ping 响应。作为权宜之计，调用会StopRuntimeSession释放卡住的会话。

如何在代理代码SessionId 中访问运行时以标记或分组资源？

适用时：您想按当前代理运行时会话对资源（例如 S3 对象、日志）进行分组、标记或追踪。

解决方案

解决方案 1：对于使用 Bedrock Amazon Bedrock AgentCore SDK 的代理，请context.session_id从代理入口点使用

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

解决方案 2：对于自定义运行时 HTTP 服务器

运行时会话 ID 在此 HTTP 标头中传递。将其从传入的请求中解析出来，然后将其用于标记、关联或下游传播。

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

我有 RuntimeClientError (403) 个问题

问题

尝试调用代理运行时时会收到 403 RuntimeClientError “”。

原因

此错误通常是由于：

解决方法

请按照以下步骤解决问题：

我缺少日志或 CloudWatch 日志为空

问题

你遇到了错误，但看不到任何相关的登录 CloudWatch。

解决方案

试试这些方法来诊断问题：

我有有效载荷格式问题

问题

即使容器成功启动，您的代理运行时调用也会失败。

解决方法

请按照以下步骤解决有效负载格式问题：

我需要帮助理解 HTTP 错误代码

问题

您的代理返回难以解释的 HTTP 错误代码。

错误消息示例

你可能会看到这样的错误：

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

解决方法

以下是最常见的错误代码及其含义：

我需要推荐来测试我的代理

要系统地调试代理运行时问题，请执行以下操作：

先在本地测试

部署到 AgentCore 运行时之前：

比较有效载荷

确保环境之间的一致性：

我需要帮助调试容器问题

如果你怀疑与容器相关的问题：

拉出并在本地运行

在本地计算机上测试容器镜像：

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

使用 curl 进行测试

向您的本地容器发送测试请求：

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

检查容器日志

检查容器的输出是否存在错误：

docker logs <container-id>

我需要帮助 MCP 协议代理进行故障排除

对于 MCP 协议代理，请执行以下特定的故障排除步骤：

验证端点路径

MCP 服务器应该监听 0.0.0.0:8000/mcp/

使用 MCP 检查器

使用 MCP 检查器工具进行测试：

身份验证问题

检查身份验证配置：

我需要使用以下方法解决双向流媒体的故障 WebSocket

要使用 WebSocket 代理进行双向流式传输，请执行以下特定的故障排除步骤：

验证端点配置

WebSocket 代理必须在端口 8080 上运行并在路径上/ws提供 WebSocket 连接

以增量复杂度进行本地测试

在部署之前，先从简单的本地测试开始：

身份验证问题

检查已部署代理的身份验证配置：

常见的连接问题

解决常见的 WebSocket 连接问题：

我的代码更改未反映在现有会话中

问题

您已经使用新代码更新了代理运行时，但现有会话继续使用旧版本。

为什么会发生这种情况

每个 microVM 会话都是使用创建会话时部署的代码资产 (agentRuntimeArtifact) 创建的。建立会话后，它会继续使用该版本的代码，直到会话终止，即使在执行UpdateAgentRuntime操作过程中更新了代码资产也是如此。

解决方案

要访问更新后的代码，请使用新的会话 ID。

从 Lambda 函数调用我的运行时时会缺少跨度

发生这种情况时：从 Lambda 函数调用 AgentCore Runtime 时

为什么会发生这种情况：Lambda 会生成自己的X-Amzn-Trace-Id标头。如果 Lambda 跟踪有Sampled=0，则此非采样上下文会传播到 AgentCore 运行时，运行时会跳过该调用的跨度生成。

解决方案：

我的 S3 文件或 EFS 挂载失败并显示 “访问被拒绝”

发生这种情况时：在调用配置了 S3 文件或 EFS 存储的代理期间

为什么会发生这种情况：执行角色缺少所需的文件系统权限。有关配置永久存储的更多信息，请参阅 AgentCore Runtime 的文件系统配置。

解决方案：

对于 S3 文件，请确保您的执行角色具有：

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

对于 EFS，请确保您的执行角色具有：

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

elasticfilesystem:ClientWrite如果您的代理只需要读取权限，请省略s3files:ClientWrite。

我的 S3 文件或 EFS 挂载失败，显示 “ResourceNotFound”

发生这种情况时：在调用配置了 S3 文件或 EFS 存储的代理期间

为什么会出现这种情况：创建代理后文件系统或接入点被删除，或者 ID 不正确。

解决方案：

我的 S3 文件或 EFS 挂载超时

发生这种情况时：在调用配置了 S3 文件或 EFS 存储的代理期间。调用可能需要比平时更长的时间才能失败。

为什么会发生这种情况：VPC 网络配置阻塞了代理计算和文件系统挂载目标之间的 NFS 流量（端口 2049）。

解决方案：

写入已挂载的文件系统时出现 “权限被拒绝”

出现这种情况时：代理调用成功且代理可以从装载中读取文件，但写入失败并显示 “权限被拒绝”

为什么会发生这种情况：要么是 IAM 角色缺少写入权限，要么在访问点创建期间设置的目录的 POSIX 权限不允许代理用户写入。

解决方案：

我的容器无法启动，在高层图像上出现 HTTP 424 错误

发生这种情况时：您的InvokeAgentRuntime呼叫返回 HTTP 424（失败的依赖关系），并且会显示Failed to mount overlay: No such file or directory您的代理日志。当您的容器映像超过 53 层且使用非数字 USER 指令（例如，USER myuser代替USER 1000）时，就会发生这种情况。

为什么会发生这种情况：具有许多层的容器镜像与非数字 USER 指令相结合可能会导致初始化失败。

解决方案：使用以下变通办法之一：

docker inspect <image> | jq '.[0].RootFS.Layers | length'

我的容量提供商处于 CREATE_FAILED 状态

发生这种情况时：在您调CreateCapacityProvider用实例计算类型后，容量提供商无法到达ACTIVE，而是进入CREATE_FAILED。

为什么会发生这种情况：容量提供者依赖于容量提供者运营商角色必须能够创建的多种资源（例如启动模板和 Auto Scaling 组）。缺少该角色的权限会导致创建失败。

解决方案：调用 GetCapacityProvider API 在statusReason字段中检索失败原因。标statusReason识创建失败的资源。向容量提供者操作员角色授予创建这些资源所需的权限，然后再次创建容量提供者。有关操作员角色的更多信息，请参阅运行时实例的安全模型和权限。

我在实例上的代理无权访问他们的证书

发生这种情况时：在实例会话上运行的代理无法获得调用 AWS 服务所需的证书。

为什么会发生这种情况：缺少运行时执行角色或无法由其担任 AgentCore。

解决方案：确保您为运行时配置的执行角色存在并bedrock-agentcore.amazonaws.com允许调用sts:AssumeRole。有关更多信息，请参阅亚马逊 Bedrock AgentCore 运行时执行角色的AgentCore 运行时的 IAM 权限权限。

最佳实践

启用全面日志

在您的代理中实现全面登录：

使用结构化错误处理

实现清晰的错误报告：

测试增量更改

遵循有条不紊的测试方法：

监控性能

为您的代理设置监控：