View a markdown version of this page

AgentCore Browser のトラブルシューティング - Amazon Bedrock AgentCore
アクセス拒否エラーモデルのアクセス拒否ブラウザセッションのタイムアウトAmazon S3 に記録が表示されないPlaywright 接続エラーCAPTCHA チェックによりエージェントが進行できないブラウザアプリケーションとの統合時の CORS エラーセッションの再生とウェブボット認証が新しいブラウザウィンドウやコンテキストで機能しないブラウザ拡張機能の問題ブラウザプロファイルの問題ルート認証機関の問題のトラブルシューティングブラウザプロキシのトラブルシューティングInvokeBrowser OS アクションのトラブルシューティング

AgentCore Browser のトラブルシューティング

このセクションでは、Amazon Bedrock AgentCore Browser を使用する際に発生する可能性がある一般的な問題の解決策を示します。

アクセス拒否エラー

症状: アクセスが拒否されたか、アクセス許可が不十分であると言及しているエラー。

解決策:

  • IAM ユーザーまたはロールに必要な Browser アクセス許可があることを確認します。

  • AWS 認証情報を確認します。 aws sts get-caller-identity

  • 録画の場合: 実行ロールに Amazon S3 書き込みアクセス許可があることを確認します。

  • 記録の場合: 信頼ポリシーで がロールを引き受けbedrock-agentcore.amazonaws.comることができることを確認します

モデルのアクセス拒否

症状: エージェントの実行時のモデルアクセスまたは認可に関するエラー。

解決策:

  • Amazon Bedrock コンソールに移動します。

  • 左側のナビゲーションの「モデルアクセス」に移動する

  • Anthropic Claude Sonnet 4 を有効にする

  • 正しいリージョンにいることを確認する (コード内のリージョンと一致する)

ブラウザセッションのタイムアウト

症状: ブラウザセッションが予期せず終了するか、タイムアウトエラーが発生します。

解決策:

  • セッションの開始時に sessionTimeoutSecondsパラメータを確認する

  • デフォルトのタイムアウトは 900 秒 (15 分) です

  • 長いセッションのタイムアウトを長くします。 sessionTimeoutSeconds=1800

  • タイムアウト期間後にセッションが自動的に停止する

Amazon S3 に記録が表示されない

症状: セッション完了後、Amazon S3 バケットに記録ファイルがありません。

解決策:

  • 実行ロールに正しい Amazon S3 アクセス許可があることを確認する

  • Amazon S3 バケット名とプレフィックスが正しいことを確認します。

  • 実行ロールの信頼ポリシーに bedrock-agentcore サービスが含まれていることを確認する

  • CloudWatch Logs for Amazon S3 アップロードエラーを確認する

  • セッションが少なくとも数秒間実行されていることを確認します (非常に短いセッションでは録画が生成されない場合があります）。

Playwright 接続エラー

症状: Playwright または WebSocket エラーでブラウザに接続できません。

解決策:

  • playwright がインストールされていることを確認します。 pip install playwright

  • 接続前にブラウザセッションが正常に開始されたことを確認する

  • セッションがまだアクティブ (タイムアウトしていない) であることを確認します。

  • ネットワークが WebSocket 接続を許可していることを確認する

CAPTCHA チェックによりエージェントが進行できない

問題: ブラウザツールを使用してウェブサイトを操作すると、エージェントは CAPTCHA 検証によってブロックされます。

原因: 一般的なウェブサイトのボット対策は自動ブラウジングを検出し、人間による検証を必要とします。

解決策: エージェントを構造化して検索エンジンを回避し、次のアーキテクチャパターンを実装します。

  • ブラウザツールは、一般的なウェブ検索ではなく、特定のページアクションにのみ使用します。

  • Tavily などのブラウザ以外の MCP ツールを使用して一般的なウェブ検索オペレーションを検索する

  • エンドユーザーが必要に応じて CAPTCHAs を制御して解決できるようにするライブビュー機能をエージェントアプリケーションに追加することを検討してください。

ブラウザアプリケーションとの統合時の CORS エラー

問題: Cross-Origin Resource Sharing (CORS) エラーは、カスタム Amazon Bedrock AgentCore ランタイムサーバーを呼び出すブラウザベースのウェブアプリケーションを構築するときに発生します。

原因: ブラウザセキュリティポリシーは、ローカル開発またはセルフホストデプロイ中にランタイムサーバーへのクロスオリジンリクエストをブロックします。

解決策: BedrockAgentCoreApp に CORS ミドルウェアを追加して、フロントエンドからのクロスオリジンリクエストを処理します。

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=["*"] を特定のドメインオリジンに置き換えます。

セッションの再生とウェブボット認証が新しいブラウザウィンドウやコンテキストで機能しない

問題: 自動化コードが新しいブラウザウィンドウまたはコンテキストを作成する場合、セッション再生機能とウェブボット認証機能は利用できません。

原因: これらの機能は、Amazon Bedrock AgentCore が提供するデフォルトのブラウザコンテキストでのみ機能するブラウザ拡張機能に依存しています。Playwright browser.new_context()の のようなメソッドを使用して新しいコンテキストを作成する場合、拡張機能は使用できません。

解決策: ブラウザセッションに接続するときに提供されるデフォルトのブラウザコンテキストを使用します。セッション再生またはウェブボット認証機能が必要な場合は、新しいコンテキストやウィンドウを作成しないでください。

# ✓ 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()

ブラウザ拡張機能の問題

拡張機能のダウンロードが失敗し、アクセスが拒否されました

症状: 拡張機能を使用する場合、セッションは Amazon S3 アクセスに関連するエラーで開始できません。

解決策:

  • IAM ユーザーまたはロールに拡張機能バケットに対する s3:GetObjectおよび アクセスs3:GetObjectHead許可があることを確認する

  • Amazon S3 バケットが API コールを行う同じ AWS アカウントによって所有されていることを確認します。

  • バケット名とプレフィックス (オブジェクトキー) が正しいことを確認します。

  • バージョニングされたバケットを使用する場合は、 アクセスs3:GetObjectVersion許可があることを確認してください。

形式が無効であるため拡張機能が拒否されました

症状: 拡張ファイル形式に関する検証エラーでセッションが開始されません。

解決策:

  • 拡張ファイルが ZIP 形式であることを確認します。

  • ZIP ファイルに有効なmanifest.jsonファイルを含む有効な Chrome 拡張機能構造が含まれていることを確認する

  • 拡張機能が Chrome 拡張機能ガイドラインに従っていることを確認します。

  • ZIP が親フォルダではなく、拡張ディレクトリの内容から作成されたことを確認します。

ブラウザプロファイルの問題

プロファイルの同時オペレーションのため、ブラウザセッションプロファイルを保存できませんでした

症状: は をSaveBrowserSessionProfileスローしますConflictException。

解決策:

  • 後で再試行SaveBrowserSessionProfileする

  • エージェントまたはコードから再試行する場合は、ジッターでエクスポネンシャルバックオフを使用する

セッションの同時オペレーションのため、ブラウザセッションプロファイルを保存できませんでした

症状: は をSaveBrowserSessionProfileスローしますConflictException。

解決策:

  • 後で再試行SaveBrowserSessionProfileする

  • エージェントまたはコードから再試行する場合は、ジッターでエクスポネンシャルバックオフを使用する

保存したブラウザプロファイルをロードすると認証が失敗する

症状: 保存されたプロファイルからロードされたブラウザセッションには、プロファイルが有効な認証 Cookie で保存された場合でも、再認証が必要です。

原因: ブラウザプロファイルに保存されている Cookie の有効期限が切れています。ウェブサイトは Cookie (認証トークンなど) の有効期限を設定し、ブラウザはこれらの有効期限に従って期限切れの Cookie を自動的に削除します。プロファイルをロードすると、プロファイルの保存後に期限切れになった Cookie は使用できません。

解決策:

  • ブラウザセッションで再認証して新しい Cookie を取得する

  • 再認証後にプロファイルを再度保存して、新しい Cookie で更新する

  • 長期認証が必要なワークフローでは、プロファイルの使用を計画するときに、ターゲットウェブサイトの一般的な Cookie の有効期間を考慮してください。

  • Cookie の有効期限が予想される場合、オートメーションワークフローに定期的な再認証を実装する

  • 重要な認証状態のプロファイルをより頻繁に保存して、保存から後続の使用までの時間を最小限に抑える

注記

Cookie の有効期限はウェブサイトによって設定され、ブラウザプロファイルでは変更できません。セッション Cookie は通常、ブラウザセッションが終了すると期限切れになりますが、永続 Cookie は Max-Age または Expires 属性に基づいて期限切れになります。

ルート認証機関の問題のトラブルシューティング

次の表は、Amazon Bedrock AgentCore Browser のルート CA 証明書を設定する際の一般的なエラーとその解決策を示しています。

エラー 原因 解像度

Secrets Manager に証明書シークレットが見つかりません

シークレット ARN が存在しないか、シークレットが削除されました。

シークレット ARN が正しく、シークレットが指定されたリージョンに存在することを確認します。

Secrets Manager の証明書シークレットへのアクセスが拒否されました

呼び出し元にはシークレットに対するsecretsmanager:GetSecretValueアクセス許可がありません。

指定されたシークレット ARN の IAM ポリシーにアクセスsecretsmanager:GetSecretValue許可を追加します。

証明書の内容が有効な PEM/X.509 形式ではありません

シークレット値が有効な PEM エンコード X.509 証明書ではありません。

シークレットに、 で始まり-----BEGIN CERTIFICATE-----、 で終わる、正しくフォーマットされた PEM 証明書が含まれていることを確認します-----END CERTIFICATE-----。

証明書の有効期限が切れています

証明書notAfterの日付が過去の日付です。

期限切れの証明書を AWS Secrets Manager の有効な証明書に置き換えて、再試行してください。

証明書はまだ有効ではありません

証明書の日付は将来のnotBefore日付です。

証明書の有効期間が始まるまで待つか、現在有効な証明書を使用します。

証明書の数が最大許容数を超えています

セッションレベルまたはツールレベルで 10 を超える証明書が提供されました。

証明書の数をセッションごとに 10 以下、ツールごとに 10 以下に減らします。

証明書の場所は必須です

証明書エントリが場所なしで提供された。

配列内の各証明書に、有効な を含むsecretsManagerエントリlocationを含む が含まれていることを確認しますsecretArn。

証明書設定が有効になっていない

証明書機能はアカウントで有効になっていません。

AWS サポートに連絡して、アカウントの証明書機能を有効にします。

ブラウザプロキシのトラブルシューティング

プロキシでセッションを開始するときのエラー

症状: で始まるメッセージを含む HTTP 400 エラーStartBrowserSessionを返します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) – シークレットは存在しますが、アクセスできません。呼び出し元の ID に アクセスsecretsmanager:GetSecretValue許可があることを確認します。クロスアカウントシークレットについては、「クロスアカウントシークレットアクセス」を参照してください。

  • 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 – シークレットに usernameと の両方が存在し、空でないpasswordことを確認します。

  • Field 'username' contains invalid characters または Field 'password' contains invalid characters – エラーメッセージにリストされている文字のみを使用します。ステップ 1: 許可された文字の認証情報シークレットを作成する (認証を使用している場合) を参照してください。

  • Field 'username' exceeds maximum length of 256 characters または Field 'password' exceeds maximum length of 256 characters – 認証情報を 256 文字以下に短縮します。

ブラウザのプロキシ接続エラー

症状: ブラウザセッションは正常に開始されますが、HTTP 502 エラーまたは を持つプロキシドメインではページナビゲーションは失敗しますnet::ERR_INVALID_AUTH_CREDENTIALS。

原因: ブラウザがプロキシサーバーに接続できないか、プロキシサーバーが提供された認証情報を拒否します。これらは AWS API エラーではなく、Chromium ネットワークエラーです。

解決策:

  • プロキシされたページの HTTP 502 – プロキシホスト名、ポート、およびサーバーが実行されており、パブリックインターネット (または VPC 設定を使用している場合は VPC から) から到達可能であることを確認します。

  • net::ERR_INVALID_AUTH_CREDENTIALS – Secrets Manager のシークレットをプロキシサーバーの有効な認証情報で更新します。

  • を使用してGetBrowserSessionアクティブなプロキシ設定を確認します。認証情報はレスポンスでは返されません。

注記

これらのエラーは、ライブビューとオートメーション API を通じて表示されます。

InvokeBrowser OS アクションのトラブルシューティング

次の表は、OS レベルのブラウザアクションに InvokeBrowser API を使用する場合の一般的なエラーを示しています。

例外 HTTP コード 説明

ValidationException

400

無効な入力。座標ベースのアクション ( mouseClick 、mouseMove、mouseDrag、mouseScroll) の場合、座標はセッションビューポートの境界内 (1 < x < viewportWidth-2、1 < y < viewportHeight-2) にある必要があります。デフォルトのビューポートサイズは 1456 x 819 ピクセルです。無効なアクションまたは無効なパラメータ値に対しても返されます。

AccessDeniedException

403

セッションに許可されていないアクセス許可またはアクションが不十分です。

ResourceNotFoundException

404

browserIdentifier または が無効ですsessionId。

ServiceQuotaExceededException

402

サービスクォータを超えました。

ThrottlingException

429

レート制限を超えました。

InternalServerException

500

実行中に予期しないエラーが発生しました。

解決策:

  • 座標値がセッションビューポートのディメンション内にあることを確認します。screenshot アクションを使用して現在の画面をキャプチャし、表示領域を確認します。

  • ブラウザセッションがまだアクティブで、タイムアウトしていないことを確認します。

  • IAM ID に アクセスbedrock-agentcore:InvokeBrowser許可があることを確認します。