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

# AgentCore 浏览器疑难解答
<a name="browser-tool-troubleshooting"></a>

本节提供您在使用亚马逊基岩 AgentCore 浏览器时可能遇到的常见问题的解决方案。

## 权限被拒绝错误
<a name="browser-tool-permission-errors"></a>

 **症状：提及访问被拒绝或权限不足的**错误。

 **解决方案：**
+ 验证您的 IAM 用户或角色是否具有所需的浏览器权限
+ 检查您的 Amazon 凭证：`aws sts get-caller-identity`
+ 用于记录：验证执行角色具有 Amazon S3 写入权限
+ 用于录制：确认信任策略`bedrock-agentcore.amazonaws.com`允许代入该角色

## 访问模型被拒
<a name="browser-tool-model-access-denied"></a>

 **症状：运行代理时出现模型访问或授权**错误。

 **解决方案：**
+ 导航到亚马逊 Bedrock 控制台
+ 转到左侧导航栏**中的**模型访问权限
+ 启用 ** Anthropic Claude Sonnet 4 ** 
+ 确认您所在的区域正确（匹配代码中的区域）

## 浏览器会话超时
<a name="browser-tool-session-timeout"></a>

 **症状：**浏览器会话意外结束或出现超时错误。

 **解决方案：**
+ 启动会话时检查`sessionTimeoutSeconds`参数
+ 默认超时时间为 900 秒（15 分钟）
+ 延长会话的超时时间：`sessionTimeoutSeconds=1800`
+ 超时时间过后会话自动停止

## 录音未出现在 Amazon S3 中
<a name="browser-tool-recording-not-in-s3"></a>

 **症状：会话完成后，您的 Amazon S3 存储桶中**没有录制文件。

 **解决方案：**
+ 验证执行角色具有正确的 Amazon S3 权限
+ 确认 Amazon S3 存储桶名称和前缀正确无误
+ 查看执行角色信任政策是否包含 bedrock-agentcore 服务
+ 查看 CloudWatch 日志中是否有 Amazon S3 上传错误
+ 确保会话至少运行几秒钟（很短的会话可能无法生成录音）

## 剧作家连接错误
<a name="browser-tool-playwright-connection-errors"></a>

 **症状：**无法通过 Playwright 或 WebSocket 错误连接到浏览器。

 **解决方案：**
+ 确认你安装了 playwright：`pip install playwright`
+ 在连接之前确认浏览器会话已成功启动
+ 检查会话是否仍处于活动状态（未超时）
+ 验证您的网络是否允许 WebSocket 连接

## 由于验证码检查，代理无法取得进展
<a name="browser-tool-captcha-issue"></a>

 **问题：使用浏览器工具与网站交互时，**您的代理会被验证码验证屏蔽。

 **原因：热门网站上的** Anti-bot 措施会检测到自动浏览，需要人工验证。

 **解决方案：**组织代理以避开搜索引擎并实现以下架构模式：
+ 仅将浏览器工具用于特定的页面操作，不能用于一般的 Web 搜索
+ 使用 Tavily 搜索等非浏览器 MCP 工具进行常规网络搜索操作
+ 考虑在代理应用程序中添加实时查看功能，允许最终用户在需要时控制和解析验证码

## 与浏览器应用程序集成时出现 CORS 错误
<a name="browser-tool-cors-issue"></a>

 **问题：构建调用自定义 Amazon Bed AgentCore rock 运行时服务器的基于浏览器的 Web 应用程序时，会出现** Cross-Origin 资源共享 (CORS) 错误。

 **原因：在本地开发或自托管部署期间，**浏览器安全策略会阻止对运行时服务器的跨域请求。

 **解决方案：向您的**添加 CORS 中间件 BedrockAgentCoreApp 以处理来自前端的跨源请求：

```
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from fastapi.middleware.cors import CORSMiddleware

app = BedrockAgentCoreApp()

# Add CORS middleware to allow browser requests
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],           # Customize in production
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Handle browser preflight requests to /invocations
@app.options("/invocations")
async def options_handler():
    return {"message": "OK"}

@app.entrypoint
def my_agent(payload):
    return {"response": "Hello from agent"}
```

**重要**  
在生产环境中，将 allow\_origins= ["\*"] 替换为特定的域名来源，以提高安全性。

## 会话重播和 Web 机器人身份验证在新的浏览器窗口或上下文中不起作用
<a name="browser-tool-new-window-limitation"></a>

 **问题：当您的自动化代码创建新的浏览器窗口或上下文时，会**话重播和 Web 机器人身份验证功能不可用。

 **原因：**这些功能依赖的浏览器扩展程序只能在 Amazon Bedrock AgentCore 提供的默认浏览器环境中运行。当你使用像 Playwright 这样的`browser.new_context()`方法创建新的上下文时，扩展不可用。

 **解决方案：**使用连接到浏览器会话时提供的默认浏览器上下文。如果您需要会话重放或 Web 机器人身份验证功能，请避免创建新的上下文或窗口。

```
# ✓ Use the existing default context
context = browser.contexts[0]
page = context.pages[0]

# ✗ Don't create new contexts - Session Replay and Web Bot Auth won't work
# context = browser.new_context()
```

## 浏览器扩展问题
<a name="browser-extensions-troubleshooting"></a>

### 扩展程序下载失败，访问被拒绝
<a name="browser-extensions-s3-access-denied"></a>

 **症状：使用扩展程序时，**会话无法启动，出现与 Amazon S3 访问相关的错误。

 **解决方案：**
+ 验证您的 IAM 用户或角色拥有`s3:GetObject`扩展存储桶的`s3:GetObjectHead`权限
+ 确认 Amazon S3 存储桶归发出 API 调用的同一个 Amazon 账户所有
+ 检查存储桶名称和前缀（对象密钥）是否正确
+ 如果使用版本控制存储桶，请确保您拥有权限 `s3:GetObjectVersion`

### 由于格式无效，扩展被拒绝
<a name="browser-extensions-invalid-format"></a>

 **症状：由于扩展文件格式存在验证错误，**会话无法启动。

 **解决方案：**
+ 确保扩展文件采用 ZIP 格式
+ 验证 ZIP 文件包含有效的 Chrome 扩展结构和有效的`manifest.json`文件
+ 检查该扩展程序是否遵守 Chrome 扩展程序指南
+ 确保 ZIP 是根据扩展目录内容创建的，而不是父文件夹

## 浏览器配置文件问题
<a name="browser-profile-troubleshooting"></a>

### 由于对配置文件进行并行操作，无法保存浏览器会话配置文件
<a name="browser-profile-concurrent-profile-operation"></a>

 **症状：**`SaveBrowserSessionProfile`投掷。`ConflictException`

 **解决方案：**
+ 稍`SaveBrowserSessionProfile`后重试
+ 如果从代理或代码重试，则使用指数退避和抖动

### 由于对会话进行并行操作，无法保存浏览器会话配置文件
<a name="browser-profile-concurrent-session-operation"></a>

 **症状：**`SaveBrowserSessionProfile`投掷。`ConflictException`

 **解决方案：**
+ 稍`SaveBrowserSessionProfile`后重试
+ 如果从代理或代码重试，则使用指数退避和抖动

### 加载保存的浏览器配置文件时身份验证失败
<a name="browser-profile-authentication-failure"></a>

 **症状：**从已保存的配置文件加载的浏览器会话需要重新进行身份验证，即使该配置文件是使用有效的身份验证 Cookie 保存的。

 **原因：存储在浏览器配置文件中的 ** Cookie 已过期。网站在 Cookie（例如身份验证令牌）上设置到期时间，浏览器会根据这些到期日期自动删除过期的 Cookie。当您加载配置文件时，自保存配置文件以来已过期的任何 Cookie 都将不可用。

 **解决方案：**
+ Re-authenticate 在浏览器会话中获取新的 cookie
+ 重新进行身份验证后再次保存配置文件以使用新的 Cookie 对其进行更新
+ 对于需要长期身份验证的工作流程，请在规划配置文件使用时考虑目标网站的典型 Cookie 生命周期
+ 如果预计 cookie 会过期，请在您的自动化工作流程中定期重新进行身份验证
+ 更频繁地保存关键身份验证状态下的配置文件，以最大限度地缩短保存和后续使用之间的时间

**注意**  
Cookie 过期时间由网站设置，不能由浏览器配置文件修改。会话 Cookie 通常在浏览器会话结束时过期，而永久 Cookie 会根据其 Max-Age 或 Expires 属性过期。

## 根证书颁发机构问题疑难解答
<a name="browser-root-ca-troubleshooting"></a>

下表描述了为亚马逊 Bedrock AgentCore 浏览器配置根 CA 证书时的常见错误及其解决方法。


| 错误 | 原因 | 解决方案 | 
| --- | --- | --- | 
| 在密钥管理器中找不到证书密钥 | 密钥 ARN 不存在或密钥已被删除。 | 验证密钥 ARN 是否正确且密钥存在于指定区域。 | 
| 拒绝访问密钥管理器中的证书密钥 | 呼叫者对该密钥没有`secretsmanager:GetSecretValue`权限。 | 在您的 IAM 策略中添加指定机密 ARN 的`secretsmanager:GetSecretValue`权限。 | 
| 证书内容 PEM/X.509 格式无效 | 密钥值不是有效的 PEM-encoded X.509 证书。 | 确保密钥包含以开头`-----BEGIN CERTIFICATE-----`和结尾的正确格式的 PEM 证书。`-----END CERTIFICATE-----` | 
| 证书已过期 | 证书的`notAfter`日期是过去的日期。 | 在 S Amazon ecrets Manager 中将过期的证书替换为有效证书，然后重试。 | 
| 证书尚未生效 | 证书的`notBefore`日期是将来的日期。 | 等到证书的有效期开始，或使用当前有效的证书。 | 
| 证书数量超过允许的最大值 | 在会话级别或工具级别提供了 10 多个证书。 | 将每个会话的证书数量减少到 10 个或更少，每个工具 10 个或更少。 | 
| 证书位置为必填项 | 提供的证书条目没有注明地点。 | 确保阵列中的每个证书都包含，`location`其`secretsManager`条目包含有效的`secretArn`。 | 
| 未启用证书配置 | 您的账户未启用证书功能。 | 请联系客 Amazon 服，为您的账户启用证书功能。 | 

## 浏览器代理疑难解答
<a name="browser-proxies-troubleshooting"></a>

### 使用代理启动会话时出错
<a name="browser-proxies-troubleshoot-session-errors"></a>

 **症状：**`StartBrowserSession`返回 HTTP 400 错误，消息以开头`Failed to set up browser proxy:`。

 **原因：**代理配置或凭据密钥无效。

 **解决方案：**
+  `Proxy credentials secret not found in Secrets Manager`— 密钥 ARN 与目标账户和区域中的任何密钥都不匹配。验证 ARN 是否正确以及密钥是否已被删除或计划删除。
+  `Invalid proxy credentials secret configuration (check encryption key for cross-account access)`— 密钥存在但无法访问。确保呼叫身份具有`secretsmanager:GetSecretValue`权限。有关跨账户密钥，请参阅[Cross-account 秘密访问](browser-proxies.md#browser-proxies-cross-account)。
+  `Proxy credentials secret must be a JSON object with username and password fields`— 将密钥值更新为有效的 JSON 对象：`{"username": "…​", "password": "…​"}`。
+  `Failed to parse proxy credentials from secret`— 无法将密钥值读取为代理凭证。验证密钥是否包含带有`username`和`password`字段的纯 JSON 字符串（不是二进制）。
+  `Field 'username' is missing or empty in secret`或 `Field 'password' is missing or empty in secret` — 确保密钥中两者`password`都`username`存在且非空。
+  `Field 'username' contains invalid characters`或 `Field 'password' contains invalid characters` — 仅使用错误消息中列出的字符。请参阅[步骤 1：为允许的字符创建凭据密钥（如果使用身份验证）](browser-proxies.md#browser-proxies-step1)。
+  `Field 'username' exceeds maximum length of 256 characters`或 `Field 'password' exceeds maximum length of 256 characters` — 将凭据缩短到 256 个字符或更少。

### 浏览器中的代理连接错误
<a name="browser-proxies-troubleshoot-connection-errors"></a>

 **症状：**浏览器会话成功启动，但出现HTTP 502错误的代理域的页面导航失败或. `net::ERR_INVALID_AUTH_CREDENTIALS` 

 **原因：**浏览器无法连接到代理服务器，或者代理服务器拒绝提供的凭据。这些是 Chromium 网络错误，而不是 Amazon API 错误。

 **解决方案：**
+  **代理页面上的 HTTP 502 ** — 验证代理主机名、端口，以及服务器是否正在运行并可从公共互联网（如果使用 VPC 配置，则可从您的 VPC 访问）。
+  `net::ERR_INVALID_AUTH_CREDENTIALS`— 使用代理服务器的有效凭据更新密钥管理器中的密钥。
+ `GetBrowserSession`用于确认有效的代理服务器设置。响应中永远不会返回证书。

**注意**  
这些错误可以在实时预览和自动化 API 中看到。

## InvokeBrowser 操作系统操作疑难解答
<a name="browser-invoke-troubleshooting"></a>

下表描述了使用 InvokeBrowser API 进行 OS-level 浏览器操作时的常见错误。


| 例外 | HTTP 代码 | 说明 | 
| --- | --- | --- | 
|  `ValidationException`  | 400 | 输入无效。对于基于坐标的操作（`mouseClick`、、`mouseMove``mouseDrag`、`mouseScroll`），坐标必须严格在会话视口边界内（1 < x < 视口Width-2，1 < y < 视口）。Height-2默认视口大小为 1456×819 像素。对于禁用的操作或无效的参数值，也会返回。 | 
|  `AccessDeniedException`  | 403 | 权限不足，不允许会话执行操作。 | 
|  `ResourceNotFoundException`  | 404 | 无效`browserIdentifier`或`sessionId`。 | 
|  `ServiceQuotaExceededException`  | 402 | 已超过服务配额。 | 
|  `ThrottlingException`  | 429 | 已超过速率限制。 | 
|  `InternalServerException`  | 500 | 执行中意外失败。 | 

 **解决方案：**
+ 验证坐标值是否在会话视口维度内。使用该`screenshot`操作捕获当前屏幕并确认可见区域。
+ 检查浏览器会话是否仍处于活动状态且未超时。
+ 确保您的 IAM 身份具有`bedrock-agentcore:InvokeBrowser`权限。