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

# AgentCore 运行时故障排除
<a name="runtime-troubleshooting"></a>

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

**Topics**
+ [我的代理调用失败并显示 “此运行时不是” MMDSv2-enabled ValidationException](#troubleshoot-runtime-mmdsv2-validation)
+ [我的代理调用失败，出现 504 网关超时错误](#troubleshoot-runtime-timeout)
+ [拉取 Python 基础镜像时，我的 Docker 构建失败并显示 “403 禁止”](#troubleshoot-runtime-docker-403)
+ [使用 boto3 时出现了 “未知服务：'bedrock-agent-core-runtime'” 错误](#troubleshoot-runtime-boto3)
+ [尝试创建 Amazon Bedrock AgentCore 运行时我得到 AccessDeniedException “”](#troubleshoot-runtime-access-denied)
+ [我的 Docker 构建失败并出现 “exec/bin/sh: exec 格式错误”](#troubleshoot-runtime-exec-format)
+ [与 Amazon Bedrock AgentCore Runtime 一起使用的 Docker 容器有什么要求？](#troubleshoot-runtime-requirements)
+ [我的长时间运行的工具在 15 分钟后中断了](#troubleshoot-runtime-long-running)
+ [我的闲置会话没有被释放，而且我的会话配额已经用完了](#troubleshoot-runtime-idle-not-releasing)
+ [如何在代理代码SessionId 中访问运行时以标记或分组资源？](#troubleshoot-runtime-session-id)
+ [我有 RuntimeClientError (403) 个问题](#runtime-client-error)
+ [我的 CloudWatch 日志丢失或为空](#missing-cloudwatch-logs)
+ [迁移到平台版本 V2 后，我不再看到代理的 CloudWatch 指标](#troubleshoot-runtime-cross-account-metrics)
+ [我遇到了有效载荷格式问题](#payload-format-issues)
+ [我需要帮助来理解 HTTP 错误代码](#common-error-codes)
+ [我需要有关测试代理的建议](#testing-recommendations)
+ [我需要帮助调试容器问题](#debugging-container-issues)
+ [我需要帮助排除 MCP 协议代理故障](#troubleshooting-mcp-protocol)
+ [我需要帮助来排除使用双向流媒体的问题 WebSocket](#troubleshooting-websocket-protocol)
+ [我的代码更改未反映在现有会话中](#troubleshoot-code-updates)
+ [从 Lambda 函数调用我的运行时时，跨度丢失了](#troubleshoot-runtime-lambda-missing-spans)
+ [我的 S3 文件或 EFS 挂载失败，显示 “访问被拒绝”](#troubleshoot-byo-storage-access-denied)
+ [我的 S3 文件或 EFS 挂载失败，显示 “ResourceNotFound”](#troubleshoot-byo-storage-resource-not-found)
+ [我的 S3 文件或 EFS 挂载超时了](#troubleshoot-byo-storage-mount-timeout)
+ [写入已安装的文件系统时，我收到 “权限被拒绝”](#troubleshoot-byo-storage-write-permission-denied)
+ [我的容器启动失败，在高层图像上出现 HTTP 424 错误](#troubleshoot-runtime-overlay-mount-failure)
+ [我的容量提供商处于 CREATE\_FAILED 状态](#troubleshoot-instances-capacity-provider-create-failed)
+ [我在实例上的代理无权访问他们的证书](#troubleshoot-instances-credentials-access)
+ [最佳实践](#best-practices)

## 我的代理调用失败并显示 “此运行时不是” MMDSv2-enabled ValidationException
<a name="troubleshoot-runtime-mmdsv2-validation"></a>

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

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

 **解决方案：**`true`在`requireMMDSV2`设置[UpdateAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html)为 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 网关超时错误
<a name="troubleshoot-runtime-timeout"></a>

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

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

有几个因素可能导致这种情况：
+  **容器问题：**确保你的 Docker 镜像暴露了端口 8080 并且有路径 `/invocations`
+  **ARM64 兼容性：**目前您的容器必须兼容 ARM64
+  **重试逻辑：**查看用于处理临时问题的重试机制

## 拉取 Python 基础镜像时，我的 Docker 构建失败并显示 “403 禁止”
<a name="troubleshoot-runtime-docker-403"></a>

 **发生这种情况时：**在使用基础映像期间`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'” 错误
<a name="troubleshoot-runtime-boto3"></a>

 **发生这种情况时：使用 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 “”
<a name="troubleshoot-runtime-access-denied"></a>

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

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

 **解决方案：**有几个因素可能导致这种情况：
+  **呼叫者缺少权限。**确保来电者的凭据有`bedrock-agentcore:CreateAgentRuntime`。
+  **Amazon Bedrock AgentCore 不能担任执行角色。**确保执行角色遵循此关于 [Amazon Bedrock AgentCore Runtime 执行角色权限](runtime-permissions.md)的指南。

## 我的 Docker 构建失败并出现 “exec/bin/sh: exec 格式错误”
<a name="troubleshoot-runtime-exec-format"></a>

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

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

 **解决方案：**构建兼容 ARM64 的容器。你可以考虑使用 [buildx](https://github.com/docker/buildx) 进行跨平台构建。或者，你可以使用 CodeBuild。有关示例代码，请参阅 [Amazon 基岩 AgentCore 示例](https://github.com/awslabs/amazon-bedrock-agentcore-samples/)。

## 与 Amazon Bedrock AgentCore Runtime 一起使用的 Docker 容器有什么要求？
<a name="troubleshoot-runtime-requirements"></a>

请查看 [Amazon Bedrock AgentCore 运行时要求](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-service-contract.html)，了解完整详情。

总之，您的 Docker 容器必须满足以下要求：
+  **端口：**公开端口 8080（即将支持其他端口）
+  **端点：**必须有可用`/invocations`路径
+  **架构：**必须兼容 ARM64
+  **响应：**应处理预期的有效载荷格式

## 我的长时间运行的工具在 15 分钟后中断了
<a name="troubleshoot-runtime-long-running"></a>

有关信息，请参阅使用 [Amazon Bedrock AgentCore Runtime 处理异步和长时间运行的代理](runtime-long-run.md)，了解完整详情。

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

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

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

```
{"status": "HealthyBusy"}
```

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

## 我的闲置会话没有被释放，而且我的会话配额已经用完了
<a name="troubleshoot-runtime-idle-not-releasing"></a>

 **发生这种情况时：**会话计数在负载下持续攀升，即使每个会话都处于空闲状态，也不会在空闲超时后释放会话（例如，在突发调用期间`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 中访问运行时以标记或分组资源？
<a name="troubleshoot-runtime-session-id"></a>

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

 **解决方案** 
+ 如果你使用的是 Bedrock Agents SDK，请使用`context.session_id`。
+ 如果您要构建自定义运行时服务器，请将其从 `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` HTTP 标头中提取。

 **解决方案 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) 个问题
<a name="runtime-client-error"></a>

 **问题** 

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

 **原因** 

发生此错误的原因通常是：
+ 容器启动失败
+ 执行角色的权限问题
+ 持有者令牌的身份验证问题

 **解决方法** 

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

1.  **检查 CloudWatch 日志**：启动容器时出现的任何问题都将反映为 403- RuntimeClientError。导航到以下 CloudWatch 日志组以检查启动错误：

   ```
   /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/[runtime-logs]
   ```

1.  **验证执行角色**：确保您的代理的执行角色具有必要的权限。有关更多信息，请参阅[AgentCore 运行时执行角色](runtime-permissions.md#runtime-permissions-execution-role)。

1.  **验证身份验证**：对于 MCP 协议代理，请确保您的持有者令牌有效且未过期。

## 我的 CloudWatch 日志丢失或为空
<a name="missing-cloudwatch-logs"></a>

 **问题** 

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

 **解决方案** 

尝试以下方法来诊断问题：

1.  **检查正确的日志组**：确保您在正确的 CloudWatch 日志组中查找。标准模式是：

   ```
   /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/runtime-logs
   ```

1.  **在本地运行以进行诊断**：如果没有 CloudWatch 日志，请尝试使用与在 Runtime 中调用时使用的完全相同的有效负载在本地 AgentCore 运行代理容器。这可以帮助识别日志中可能看不到的问题。

1.  **启用 Verbose Logging**：更新代理代码以包含更详细的日志记录，尤其是在入口点和任何错误处理逻辑周围。

## 迁移到平台版本 V2 后，我不再看到代理的 CloudWatch 指标
<a name="troubleshoot-runtime-cross-account-metrics"></a>

 **问题** 

您可以跨账户调用代理运行时：您账户中的委托人通过基于资源的策略调用另一个账户拥有的运行时。运行时移至平台版本 V2 后，您的账户中将不再显示每次调用的 CloudWatch 指标。

 **解决方案** 

这是预期行为，而不是丢失数据。在平台版本 V2 上，跨账户调用会将运行时指标发布到资源所有者的账户，而不是调用账户。资源所有者是拥有代理运行时的账户。在资源所有者的账户中查找指标。有关更多信息，请参阅[AgentCore 生成的运行时可观测性数据](observability-runtime-metrics.md)。

## 我遇到了有效载荷格式问题
<a name="payload-format-issues"></a>

 **问题** 

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

 **解决方法** 

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

1.  **验证有效负载结构**：确保您的有效负载结构与代理的期望相匹配。要特别注意：
   + 如果您的代理代码需要在有效负载中包含`input`关键字，请务必将其包括在内：

     ```
     {
         "input": {
             "prompt": "Your question here"
         }
     }
     ```
   + 不只是：

     ```
     {
          "prompt": "Your question here"
     }
     ```

1.  **查看文档**：查看文档中预期的输入格式。

## 我需要帮助来理解 HTTP 错误代码
<a name="common-error-codes"></a>

 **问题** 

您的代理返回难以解释的 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
```

 **解决方法** 

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

 **422 无法处理的实体**   
当容器遇到输入负载的验证问题时，就会发生这种情况。  
常见原因：  
+ 有效载荷中缺少必填字段（例如，缺少 “输入” 字段）
+ 字段的数据类型不正确
+ 有效载荷的格式无效

 **403 禁止访问**   
身份验证或授权问题。  
检查您的不记名令牌或 IAM 权限。

 **409 RetryableConflictException**   
第二个操作在仍处于供应或拆除状态时进入了会话。你会看到消息`Session operation in progress, please retry`。  
 **这是什么意思：**这是一个暂时的、可重试的冲突，而不是终端错误。窗口很简短。 Already-running 会话不受影响。  
 **如何修复：**使用短指数退避重试该操作。对于 HTTP-based API（例如`InvokeAgentRuntime``InvokeAgentRuntimeCommand`、和`StopRuntimeSession`），启用默认重试后， Amazon 软件开发工具包会自动重试此操作。如果您禁用了重试功能，或者在没有 Amazon SDK 的情况下直接调用 API，请自己添加重试。对于 WebSocket-based API（例如`InvokeAgentRuntimeWithWebSocketStream`和`InvokeAgentRuntimeCommandShell`）， Amazon 软件开发工具包不会自动重试。请务必自己重试。

 **500 内部服务器错误**   
代理代码中存在运行时异常。  
查看 CloudWatch 日志以获取详细的堆栈跟踪。

## 我需要有关测试代理的建议
<a name="testing-recommendations"></a>

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

 **先在本地测试** 

在部署到 AgentCore 运行时之前：
+ 使用相同的 Docker 镜像在本地运行代理容器
+ 验证它是否适用于完全相同的有效载荷

 **比较有效载荷** 

确保环境之间的一致性：
+ 确保本地测试和 AgentCore 运行时调用之间的负载结构相同
+ 特别注意 “输入” 和 “提示” 等字段的嵌套

## 我需要帮助调试容器问题
<a name="debugging-container-issues"></a>

如果您怀疑与容器有关的问题：

 **在本地拉取并运行** 

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

```
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 协议代理故障
<a name="troubleshooting-mcp-protocol"></a>

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

 **验证端点路径** 

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

 **使用 MCP Inspector** 

使用 MCP Inspector 工具进行测试：

1. 安装并运行 MCP Inspector：`npx @modelcontextprotocol/inspector`

1. 通过 Connect 连接到您的本地服务器 `http://localhost:8000/mcp` 

1. 对于已部署的代理，请使用正确的 URL-encoded 端点

 **身份验证问题** 

检查身份验证配置：
+ 确保在标题中正确设置了不记名令牌
+ 验证您的 Cognito 用户池设置是否正确

## 我需要帮助来排除使用双向流媒体的问题 WebSocket
<a name="troubleshooting-websocket-protocol"></a>

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

 **验证端点配置** 

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

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

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

1. 测试基本连接：验证您的代理是否接受 WebSocket 连接 `ws://localhost:8080/ws` 

1. 测试消息处理：发送简单短信并验证回复

1. 测试会话管理：验证持续对话是否按预期运行

1. 测试错误处理：确保您的代理优雅地处理连接中断和格式错误的消息

 **身份验证问题** 

检查已部署代理的身份验证配置：
+ 对于 OAuth：确保持有者令牌有效且未过期
+ 对于 Sigv4：确保签名算法的输入正确，包括 WebSocket 网址、标头和请求方法
+ 使用与您的代理配置相匹配的正确身份验证方法

 **常见的连接问题** 

解决常见的 WebSocket 连接问题：
+ 验证您的代理和客户期望之间的消息格式兼容性
+ 配置消息帧分段或实现分块，使其保持在消息帧大小 (64 KB) 和消息帧速率（每秒 250 帧）限制之内，以防止连接关闭

## 我的代码更改未反映在现有会话中
<a name="troubleshoot-code-updates"></a>

 **问题** 

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

 **为什么会发生这种情况** 

每个 microVM 会话都是使用创建会话时部署的代码资产 (`agentRuntimeArtifact`) 创建的。建立会话后，它将继续使用该版本的代码，直到会话终止，即使在执行[UpdateAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html)操作的过程中更新了代码资产也是如此。

 **解决方案** 

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

## 从 Lambda 函数调用我的运行时时，跨度丢失了
<a name="troubleshoot-runtime-lambda-missing-spans"></a>

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

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

 **解决方案：**
+  **启用 Lambda 主动跟踪：**在 Lambda 函数上开启 X-Ray 主动跟踪，使其生成采样跟踪 ()。`Sampled=1`
+  **验证 CloudWatch 交易搜索：**确保您已完成[配置可观测性](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/observability-configure.html)中的设置，并且您的跟踪区段目标已设置为 CloudWatch 日志。
+  **检查采样决定：**在 Lambda 函数中记录`_X_AMZN_TRACE_ID`环境变量。如果显示`Sampled=0`，则表示未启用主动跟踪，或者上游调用方正在做出采样决定。

## 我的 S3 文件或 EFS 挂载失败，显示 “访问被拒绝”
<a name="troubleshoot-byo-storage-access-denied"></a>

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

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

 **解决方案：**

对于 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”
<a name="troubleshoot-byo-storage-resource-not-found"></a>

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

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

 **解决方案：**
+ 验证文件系统是否存在：
  + S3 文件：`aws s3files list-file-systems --region <region>`
  + EFS：`aws efs describe-file-systems --region <region>`
+ 验证接入点是否存在：
  + S3 文件：`aws s3files list-access-points --file-system-id <fs-id> --region <region>`
  + EFS：`aws efs describe-access-points --file-system-id <fs-id> --region <region>`
+ 验证所有必需的可用区中是否存在挂载目标：
  + S3 文件：`aws s3files list-mount-targets --file-system-id <fs-id> --region <region>`
  + EFS：`aws efs describe-mount-targets --file-system-id <fs-id> --region <region>`
  + 确保每个挂载目标都显示可用状态并且与代理运行时位于同一 VPC 中。
+ 如果资源已删除，请重新创建该资源并使用新的接入点 ARN 更新代理运行时

## 我的 S3 文件或 EFS 挂载超时了
<a name="troubleshoot-byo-storage-mount-timeout"></a>

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

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

 **解决方案：**
+  **检查挂载目标上的安全组：**验证挂载目标上的安全组允许代理运行时使用的安全组**在端口 2049 上入站 TCP**
+  **在代理运行时检查安全组：验证代理运行时**使用的安全组允许**端口 2049 上的出站 TCP** 进入装载目标安全组
+  **验证挂载目标是否存在于正确的可用区中：**挂载目标必须与代理运行时配置的子网位于相同的可用区中：
  + S3 文件：`aws s3files list-mount-targets --file-system-id <fs-id> --region <region>`
  + EFS：`aws efs describe-mount-targets --file-system-id <fs-id> --region <region>`
+  **验证子网路由：**确保您的子网具有正确的路由（CIDR 范围内的本地 VPC 路由）

## 写入已安装的文件系统时，我收到 “权限被拒绝”
<a name="troubleshoot-byo-storage-write-permission-denied"></a>

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

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

 **解决方案：**
+  **检查 IAM 权限：**确保您的执行角色包括`s3files:ClientWrite`（S3 文件）或`elasticfilesystem:ClientWrite`（EFS）。如果没有写入权限，则挂载是只读的。有关更多信息，请参阅 [Amazon Bedrock AgentCore 运行时执行角色的权限](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-permissions.html)。
+  **检查 POSIX 权限：**如果目录由与您的容器进程不同的用户所有，则写入将被拒绝。或者：
  + 将接入点的 PosixUser 设置为与容 uid/gid 器的运行方式相匹配，因此所有操作都以该用户身份执行。
  + 将目录权限设置为 777 以允许所有用户写入。

## 我的容器启动失败，在高层图像上出现 HTTP 424 错误
<a name="troubleshoot-runtime-overlay-mount-failure"></a>

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

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

 **解决方案：**使用以下解决方法之一：
+  **使用数字用户指令：**在你的 Dockerfile 中，`USER myuser`替换为数字 UID（例如）。`USER 1000`您可以通过在容器`id myuser`内运行来找到用户的 UID。这完全避免了文件系统的挂载。
+  **减少图像层：**使用多阶段 Docker 版本将图像缩小到 53 层以下。您可以通过以下方式检查图像的图层数：

```
docker inspect <image> | jq '.[0].RootFS.Layers | length'
```
+  **压平图层：**使用`docker build --squash`或类似的工具`docker-squash`来拼合图像图层。

## 我的容量提供商处于 CREATE\_FAILED 状态
<a name="troubleshoot-instances-capacity-provider-create-failed"></a>

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

 **发生这种情况的原因：**容量提供者依赖于容量提供者操作员角色必须能够创建的多个资源（例如启动模板和 Auto Scaling 组）。缺少该角色的权限会导致创建失败。

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

## 我在实例上的代理无权访问他们的证书
<a name="troubleshoot-instances-credentials-access"></a>

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

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

 **解决方案：**确保您为运行时配置的执行角色存在并`bedrock-agentcore.amazonaws.com`允许调用`sts:AssumeRole`。有关更多信息，请参阅 [Amazon Bedrock AgentCore 运行时执行角色的权限](runtime-permissions.md)。

## 最佳实践
<a name="best-practices"></a>

 **启用全面日志** 

在代理中实现彻底的登录：
+ 包括 request/response 登录您的代理
+ 记录关键路径和错误情况

 **使用结构化错误处理** 

实施清晰的错误报告：
+ 返回带有特定代码的清晰错误消息
+ 在错误响应中包含可操作的信息

 **测试增量更改** 

遵循有条不紊的测试方法：
+ 修改代理时，请在部署之前在本地进行测试
+ 验证有效载荷与本地和已部署环境的兼容性

 **监控性能** 

为您的代理设置监控：
+ 使用 CloudWatch 指标来跟踪调用模式
+ 为错误率和延迟设置警报