AgentCore ランタイムのトラブルシューティング

このトラブルシューティングトピックは、AgentCore Runtime を使用する際の一般的な問題の特定と解決に役立ちます。これらのソリューションに従うことで、エージェントのランタイムの問題をすばやく診断して修正できます。

エージェント呼び出しが「このランタイムは MMDSv2-enabledではありません」 ValidationException で失敗する

これが発生した場合: 、InvokeAgentRuntime、ExecuteCommand、InvokeAgentRuntimeCommandShell、または を介してエージェントランタイムInvokeAgentRuntimeWithWebSocketStreamを呼び出す場合 GetAgentCard

これが発生する理由: 2026 年 6 月 30 日以降、Amazon Bedrock AgentCore ランタイムでは、すべてのエージェントのランタイムで MMDSv2 (MicroVM メタデータサービスバージョン 2) を使用する必要があります。サービスは、 metadataConfigurationが設定されていないランタイム、または falseまたは requireMMDSV2に設定されたランタイムをターゲットとする呼び出しを拒否しますnull。

解決策: で を requireMMDSV2に設定して UpdateAgentRuntime を呼び出しtrueます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 Gateway タイムアウトエラーで失敗する

これが発生した場合: SDK またはコンソールを介したエージェントの呼び出し中

これが発生する理由: 複数の要因により、エージェントがタイムアウト期間内に応答できなくなる可能性があります。

これには、いくつかの要因が考えられます。

Python ベースイメージのプル時に「403 Forbidden」で Docker ビルドが失敗する

これが発生した場合: 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 の使用時に「不明なサービス: 'bedrock-agent-core-runtime'」エラーが表示される

これが発生した場合: boto3 SDK を使用して Amazon Bedrock AgentCore APIs を呼び出す場合

これが発生する理由: 古い 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 format error」で失敗する

これが発生した場合: Amazon Bedrock AgentCore デプロイ用のコンテナを構築する場合

これが発生する理由: 適切なクロスプラットフォーム設定なしで x86 システムに ARM64 コンテナを構築する

解決策: ARM64 互換コンテナを構築します。クロスプラットフォームビルドに buildx を使用することを検討できます。または、CodeBuild を使用することもできます。コード例については、「Amazon Bedrock AgentCore サンプル」を参照してください。

Amazon Bedrock AgentCore ランタイムで使用される Docker コンテナの要件は何ですか?

詳細については、Amazon Bedrock AgentCore ランタイム要件を参照してください。

要約すると、Docker コンテナは次の要件を満たしている必要があります。

15 分後に長時間実行されるツールが中断される

詳細については、「Amazon Bedrock Amazon Bedrock AgentCore ランタイムで非同期エージェントと長時間実行エージェントを処理する」を参照してください。

これが発生した場合: 長時間実行されるエージェントオペレーションまたは複雑なワークフロー中

これが発生する理由: Amazon Bedrock AgentCore は、15 分間非アクティブ状態になるとセッションを自動的に終了します。プラットフォームHealthyBusyは/pingレスポンスからアクティビティを決定します。セッションレポートは存続し、セッションレポートはアイドル対象としてHealthy扱われ、アイドル時間はstatus最後に変更された時点から測定されます (以下のtime_of_last_updateフィールドを参照）。

解決策: バックグラウンド作業の進行HealthyBusy中に/pingエンドポイントが を返すことを確認します。

{"status": "HealthyBusy"}

Bedrock AgentCore SDK を使用している場合、ping レスポンスは自動的に処理されます。カスタム実装の場合は、ping ハンドラーが処理HealthyBusy中に を返すことを確認します。

アイドルセッションが解放されておらず、セッションクォータを使い果たしている

これが発生した場合: セッション数は負荷がかかると継続的に増加し、各セッションがアイドル状態であっても、アイドルタイムアウト後にセッションは解放されません (呼び出しのバースト中の ServiceQuotaExceededException / maxVms エラーなど）。

これが発生する理由: セッションが を報告するとHealthy、プラットフォームは/pingレスポンスの time_of_last_updateフィールドからアイドル状態になった時間を測定します。これは、status最後に変更された日時を反映する必要があります。ping ハンドラが ping のたびに現在の時刻time_of_last_updateに設定されている場合、報告されたアイドル時間はリセットされ続け、アイドルタイムアウトが発射されるのを防ぎます。その後、セッションは まで存続MaxLifetimeし、セッションクォータを使い果たすことができます。

解決策: がstatus実際に変更されたtime_of_last_update場合にのみ更新するか、プラットフォームが単独でステータスの変更を追跡するように完全に省略します。

{"status": "Healthy"}

Bedrock AgentCore SDK を使用している場合は、ping レスポンスが正しく処理される最新バージョンにアップグレードします。ストップギャップとして、 を呼び出すとセッションがスタックStopRuntimeSessionします。

リソースのタグ付けまたはグループ化のために、エージェントコードの runtimeSessionId にアクセスするにはどうすればよいですか?

これが適用される場合: 現在のエージェントランタイムセッションによってリソース (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) の問題がある

[Problem] (問題)

エージェントランタイムを呼び出そうとすると、403「RuntimeClientError」が表示されます。

原因

このエラーは通常、次の理由で発生します。

解決策

問題を解決するには、次の手順に従います。

CloudWatch Logs がないか、空です

[Problem] (問題)

エラーが発生しても、CloudWatch に関連するログは表示されません。

解決策

問題を診断するには、次の方法を試してください。

ペイロード形式の問題がある

[Problem] (問題)

コンテナが正常に起動しても、エージェントのランタイム呼び出しは失敗します。

解決策

ペイロード形式の問題を解決するには、次の手順に従います。

HTTP エラーコードの理解にヘルプが必要です

[Problem] (問題)

エージェントは、解釈が難しい 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 Inspector を使用する

MCP Inspector ツールでテストします。

認証の問題

認証設定を確認します。

WebSocket を使用した双方向ストリーミングのトラブルシューティングにヘルプが必要

WebSocket エージェントを使用した双方向ストリーミングの場合は、以下の特定のトラブルシューティング手順に従ってください。

エンドポイント設定の検証

WebSocket エージェントはポート 8080 で実行され、/wsパスで WebSocket 接続を提供する必要があります

段階的な複雑さでローカルでテストする

デプロイする前に、シンプルなローカルテストから始めます。

認証の問題

デプロイされたエージェントの認証設定を確認します。

一般的な接続の問題

WebSocket 接続の一般的な問題に対処します。

コードの変更が既存のセッションに反映されない

[Problem] (問題)

エージェントランタイムを新しいコードで更新しましたが、既存のセッションは引き続き古いバージョンを使用します。

これが発生する理由

各 microVM セッションは、セッションの作成時にデプロイされたコードアセット () agentRuntimeArtifact を使用して作成されます。セッションが確立されると、UpdateAgentRuntime オペレーションの実行の一環としてコードアセットが更新されても、セッションが終了するまでそのバージョンのコードが引き続き使用されます。

解決策

更新されたコードにアクセスするには、新しいセッション ID を使用します。

ランタイムが Lambda 関数から呼び出されたときにスパンが欠落している

これが発生した場合: Lambda 関数から AgentCore ランタイムを呼び出す場合

これが発生する理由: Lambda は独自のX-Amzn-Trace-Idヘッダーを生成します。Lambda トレースに がある場合Sampled=0、このサンプリングされていないコンテキストは AgentCore ランタイムに伝達され、ランタイムはその呼び出しのスパン生成をスキップします。

解決策:

S3 ファイルまたは EFS マウントが「アクセス拒否」で失敗する

これが発生した場合: S3 ファイルまたは EFS ストレージが設定されたエージェントの呼び出し中

これが発生する理由: 実行ロールに必要なファイルシステムのアクセス許可がありません。永続ストレージの設定の詳細については、AgentCore ランタイムのファイルシステム設定」を参照してください。

解決策:

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 ストレージが設定されたエージェントの呼び出し中

これが発生する理由: エージェントの作成後にファイルシステムまたはアクセスポイントが削除されたか、IDsが正しくありません。

解決策:

S3 ファイルまたは EFS マウントがタイムアウトする

これが発生した場合: S3 ファイルまたは EFS ストレージが設定されたエージェントの呼び出し中。呼び出しが失敗するまでに通常よりも時間がかかる場合があります。

これが発生する理由: VPC ネットワーク設定は、エージェントのコンピューティングとファイルシステムのマウントターゲット間の NFS トラフィック (ポート 2049) をブロックしています。

解決策:

マウントされたファイルシステムに書き込むと「アクセス許可が拒否」される

これが発生した場合: エージェント呼び出しは成功し、エージェントはマウントからファイルを読み取ることができますが、書き込みは「アクセス許可が拒否されました」で失敗します。

これが発生する理由: IAM ロールに書き込みアクセス許可がないか、アクセスポイントの作成中に設定されたディレクトリに対する POSIX アクセス許可がエージェントのユーザーの書き込みを許可していません。

解決策:

コンテナがハイレイヤーイメージで HTTP 424 エラーで起動しない

これが発生した場合: InvokeAgentRuntime呼び出しは HTTP 424 (Failed Dependency) を返し、エージェントログには が表示されますFailed to mount overlay: No such file or directory。これは、コンテナイメージに 53 を超えるレイヤーがあり、数値以外の USER ディレクティブ ( USER myuserではなく などUSER 1000) を使用している場合に発生します。

これが発生する理由: 多数のレイヤーを持つコンテナイメージを数値以外の USER ディレクティブと組み合わせると、初期化が失敗する可能性があります。

解決策: 次のいずれかの回避策を使用します。

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

ベストプラクティス

包括的なログ記録を有効にする

エージェントに詳細なログ記録を実装します。

構造化エラー処理を使用する

明確なエラーレポートを実装します。

増分変更をテストする

体系的なテストアプローチに従います。

パフォーマンスのモニタリング

エージェントのモニタリングをセットアップします。