AgentCore 运行时故障排除

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

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

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

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

解决方案：true在requireMMDSV2设置UpdateAgentRuntime为 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 禁止”

发生这种情况时：在使用基础映像期间docker build或使用public.ecr.aws基础映像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 时出现了 “未知服务：'bedrock-agent-core-runtime'” 错误

发生这种情况时：使用 boto3 软件开发工具包调用 Amazon Bedrock AgentCore API 时

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

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

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

尝试创建 Amazon Bedrock AgentCore 运行时我得到 AccessDeniedException “”

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

发生这种情况的原因：可能是您的用户缺少权限，或者没有为 Amazon Bedrock 正确配置执行角色 AgentCore

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

我的 Docker 构建失败并出现 “exec/bin/sh: exec 格式错误”

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

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

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

与 Amazon Bedrock AgentCore Runtime 一起使用的 Docker 容器有哪些要求？

请查看 Amazon Bedrock AgentCore 运行时要求，了解完整详情。

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

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

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

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

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

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

{"status": "HealthyBusy"}

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

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

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

为什么会发生这种情况：当会话报告时Healthy，平台会衡量您的/ping响应中它在time_of_last_update现场闲置了多长时间，这必须反映出status上次更改的时间。如果您的 ping 处理程序在每次 ping 时都设置time_of_last_update为当前时间，则报告的空闲时间会不断重置，从而防止触发空闲超时。然后，会话将持续到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 -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 Inspector

使用 MCP Inspector 工具进行测试：

身份验证问题

检查身份验证配置：

我需要帮助来排除使用双向流媒体的问题 WebSocket

对于使用 WebSocket 代理进行双向流式传输，请按照以下特定的故障排除步骤进行操作：

验证端点配置

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

在本地进行测试，复杂性越来越高

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

身份验证问题

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

常见的连接问题

解决常见的 WebSocket 连接问题：

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

问题

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

为什么会发生这种情况

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

解决方案

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

从 Lambda 函数调用我的运行时时，跨度丢失了

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

为什么会发生这种情况：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'

最佳实践

启用全面日志

在代理中实现彻底的登录：

使用结构化错误处理

实施清晰的错误报告：

测试增量更改

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

监控性能

为您的代理设置监控：