# AgentCore ランタイムのトラブルシューティング
このトラブルシューティングトピックは、AgentCore Runtime を使用する際の一般的な問題の特定と解決に役立ちます。これらのソリューションに従うことで、エージェントのランタイムの問題をすばやく診断して修正できます。
**Topics**
+ [エージェント呼び出しが「このランタイムは MMDSv2-enabledではありません」 ValidationException で失敗する](#troubleshoot-runtime-mmdsv2-validation)
+ [エージェント呼び出しが 504 Gateway タイムアウトエラーで失敗する](#troubleshoot-runtime-timeout)
+ [Python ベースイメージのプル時に「403 Forbidden」で Docker ビルドが失敗する](#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 format error」で失敗する](#troubleshoot-runtime-exec-format)
+ [Amazon Bedrock AgentCore ランタイムで使用される Docker コンテナの要件は何ですか?](#troubleshoot-runtime-requirements)
+ [15 分後に長時間実行されるツールが中断される](#troubleshoot-runtime-long-running)
+ [アイドルセッションが解放されておらず、セッションクォータを使い果たしている](#troubleshoot-runtime-idle-not-releasing)
+ [リソースのタグ付けまたはグループ化のために、エージェントコードの runtimeSessionId にアクセスするにはどうすればよいですか?](#troubleshoot-runtime-session-id)
+ [RuntimeClientError (403) の問題がある](#runtime-client-error)
+ [CloudWatch Logs がないか、空です](#missing-cloudwatch-logs)
+ [ペイロード形式の問題がある](#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)
+ [ベストプラクティス](#best-practices)
## エージェント呼び出しが「このランタイムは MMDSv2-enabledではありません」 ValidationException で失敗する
**これが発生した場合:** 、`InvokeAgentRuntime`、`ExecuteCommand`、`InvokeAgentRuntimeCommandShell`、または を介してエージェントランタイム`InvokeAgentRuntimeWithWebSocketStream`を呼び出す場合 `GetAgentCard`
**これが発生する理由:** 2026 年 6 月 30 日以降、Amazon Bedrock AgentCore ランタイムでは、すべてのエージェントのランタイムで MMDSv2 (MicroVM メタデータサービスバージョン 2) を使用する必要があります。サービスは、 `metadataConfiguration`が設定されていないランタイム、または `false`または `requireMMDSV2`に設定されたランタイムをターゲットとする呼び出しを拒否します`null`。
**解決策:** で を `requireMMDSV2`に設定して [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html) を呼び出し`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 またはコンソールを介したエージェントの呼び出し中
**これが発生する理由:** 複数の要因により、エージェントがタイムアウト期間内に応答できなくなる可能性があります。
これには、いくつかの要因が考えられます。
+ **コンテナの問題:** Docker イメージがポート 8080 を公開し、 `/invocations`パスがあることを確認します。
+ **ARM64 互換性:** 現在、コンテナは ARM64 互換である必要があります
+ **再試行ロジック:** 一時的な問題を処理するための再試行メカニズムを確認する
## 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 の実行ロールが正しく設定されていない
**解決策:** これにはいくつかの要因が考えられます。
+ **呼び出し元のアクセス許可がありません。**発信者の認証情報に があることを確認します`bedrock-agentcore:CreateAgentRuntime`。
+ **Bedrock Amazon Bedrock AgentCore は実行ロールを引き受けることができません。**実行ロールが [Amazon Bedrock AgentCore ランタイム実行ロールのアクセス許可](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)に関するこのガイダンスに従っていることを確認します。
## Docker ビルドが「exec /bin/sh: exec format error」で失敗する
**これが発生した場合:** Amazon Bedrock AgentCore デプロイ用のコンテナを構築する場合
**これが発生する理由:** 適切なクロスプラットフォーム設定なしで x86 システムに ARM64 コンテナを構築する
**解決策:** ARM64 互換コンテナを構築します。クロスプラットフォームビルドに [buildx](https://github.com/docker/buildx) を使用することを検討できます。または、CodeBuild を使用することもできます。コード例については、[「Amazon Bedrock AgentCore サンプル](https://github.com/awslabs/amazon-bedrock-agentcore-samples/)」を参照してください。
## Amazon Bedrock AgentCore ランタイムで使用される Docker コンテナの要件は何ですか?
詳細については、[Amazon Bedrock AgentCore ランタイム要件](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html)を参照してください。
要約すると、Docker コンテナは次の要件を満たしている必要があります。
+ **ポート:** ポート 8080 を公開する (追加のポートは間もなくサポートされる予定です)
+ **エンドポイント:** `/invocations`パスが使用可能である必要があります
+ **アーキテクチャ:** ARM64 互換である必要があります
+ **レスポンス:** 予想されるペイロード形式を処理する必要があります
## 15 分後に長時間実行されるツールが中断される
詳細については、[「Amazon Bedrock Amazon Bedrock AgentCore ランタイムで非同期エージェントと長時間実行エージェントを処理する](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-long-run.html)」を参照してください。
**これが発生した場合:** 長時間実行されるエージェントオペレーションまたは複雑なワークフロー中
**これが発生する理由:** 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 オブジェクト、ログなど) をグループ化、タグ付け、またはトレースする場合。
**解決方法:**
+ Bedrock エージェント SDK を使用している場合は、 を使用します`context.session_id`。
+ カスタムランタイムサーバーを構築する場合は、HTTP `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` ヘッダーから抽出します。
**解決策 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:
```
## RuntimeClientError (403) の問題がある
**[Problem]** (問題)
エージェントランタイムを呼び出そうとすると、403「RuntimeClientError」が表示されます。
**原因**
このエラーは通常、次の理由で発生します。
+ コンテナの起動エラー
+ 実行ロールのアクセス許可の問題
+ ベアラートークンの認証の問題
**解決策**
問題を解決するには、次の手順に従います。
1. **CloudWatch Logs を確認する**: コンテナの起動に関する問題は、403 - RuntimeClientError として反映されます。次の CloudWatch ロググループに移動して、起動エラーを確認します。
```
/aws/bedrock-agentcore/runtimes/-/[runtime-logs]
```
1. **実行ロールの検証**: エージェントの実行ロールに必要なアクセス許可があることを確認します。詳細については、[AgentCore ランタイム実行ロール](runtime-permissions.md#runtime-permissions-execution-role)」を参照してください。
1. **認証の検証**: MCP プロトコルエージェントの場合、ベアラートークンが有効で、有効期限が切れていないことを確認します。
## CloudWatch Logs がないか、空です
**[Problem]** (問題)
エラーが発生しても、CloudWatch に関連するログは表示されません。
**解決策**
問題を診断するには、次の方法を試してください。
1. **正しいロググループをチェック**する: 適切な CloudWatch ロググループを探していることを確認します。標準パターンは次のとおりです。
```
/aws/bedrock-agentcore/runtimes/-/runtime-logs
```
1. **診断のためにローカルで実行する**: CloudWatch Logs がない場合は、AgentCore ランタイムの呼び出しに使用したのとまったく同じペイロードを使用して、エージェントコンテナをローカルで実行してみてください。これにより、ログに表示されない可能性のある問題を特定できます。
1. **詳細ログを有効にする**: エージェントコードを更新して、特にエントリポイントとエラー処理ロジックを中心に、より詳細なログ記録を含めます。
## ペイロード形式の問題がある
**[Problem]** (問題)
コンテナが正常に起動しても、エージェントのランタイム呼び出しは失敗します。
**解決策**
ペイロード形式の問題を解決するには、次の手順に従います。
1. **ペイロード構造の検証**: ペイロード構造がエージェントが期待する内容と一致していることを確認します。次の点に特に注意してください。
+ エージェントコードがペイロードに`input`キーワードを想定している場合は、必ず含めてください。
```
{
"input": {
"prompt": "Your question here"
}
}
```
+ 以下だけではありません。
```
{
"prompt": "Your question here"
}
```
1. **ドキュメントの確認**: ドキュメントで予想される入力形式を確認します。
## HTTP エラーコードの理解にヘルプが必要です
**[Problem]** (問題)
エージェントは、解釈が難しい HTTP エラーコードを返します。
**エラーメッセージの例**
次のようなエラーが表示される場合があります。
```
An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error () from runtime. Please check your CloudWatch logs for more information
```
**解決策**
最も一般的なエラーコードとその意味は次のとおりです。
**422 未処理のエンティティ**
これは、コンテナが入力ペイロードで検証の問題が発生した場合に発生します。
一般的な原因:
+ ペイロードに必須フィールドがない (例: 「入力」フィールドがない)
+ フィールドのデータ型が正しくない
+ ペイロードの形式が無効です
**403 Forbidden**
認証または認可の問題。
ベアラートークンまたは IAM アクセス許可を確認します。
**500 内部サーバーエラー**
エージェントコードのランタイム例外。
CloudWatch ログでスタックトレースの詳細を確認します。
## エージェントをテストするためのレコメンデーションが必要です
エージェントランタイムの問題を体系的にデバッグするには:
**最初にローカルでテストする**
AgentCore ランタイムにデプロイする前に:
+ 同じ Docker イメージを使用してエージェントコンテナをローカルで実行する
+ まったく同じペイロードで動作することを確認する
**ペイロードを比較する**
環境間の整合性を確保します。
+ ローカルテストと AgentCore ランタイム呼び出しの間のペイロード構造が同じであることを確認します。
+ 「入力」や「プロンプト」などのフィールドのネストには特に注意してください。
## コンテナの問題のデバッグにヘルプが必要
コンテナ関連の問題が疑われる場合:
**ローカルでプルして実行する**
ローカルマシンでコンテナイメージをテストします。
```
docker pull
docker run -p 8080:8080
```
**curl でテストする**
ローカルコンテナにテストリクエストを送信します。
```
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"input": {"prompt": "Hello world!"}}'
```
**コンテナログを確認する**
コンテナの出力にエラーがないか調べます。
```
docker logs
```
## MCP プロトコルエージェントのトラブルシューティングにヘルプが必要です
MCP プロトコルエージェントの場合は、以下の特定のトラブルシューティングステップに従います。
**エンドポイントパスを検証する**
MCP サーバーはリッスンする必要があります `0.0.0.0:8000/mcp/`
**MCP Inspector を使用する**
MCP Inspector ツールでテストします。
1. MCP Inspector をインストールして実行します。 `npx @modelcontextprotocol/inspector`
1. でローカルサーバーに接続する `http://localhost:8000/mcp`
1. デプロイされたエージェントには、適切な URL エンコードされたエンドポイントを使用します。
**認証の問題**
認証設定を確認します。
+ ヘッダーにベアラートークンが正しく設定されていることを確認します。
+ Cognito ユーザープールが正しく設定されていることを確認します。
## WebSocket を使用した双方向ストリーミングのトラブルシューティングにヘルプが必要
WebSocket エージェントを使用した双方向ストリーミングの場合は、以下の特定のトラブルシューティング手順に従ってください。
**エンドポイント設定の検証**
WebSocket エージェントはポート 8080 で実行され、`/ws`パスで WebSocket 接続を提供する必要があります
**段階的な複雑さでローカルでテストする**
デプロイする前に、シンプルなローカルテストから始めます。
1. 基本的な接続をテストする: エージェントが で WebSocket 接続を受け入れることを確認する `ws://localhost:8080/ws`
1. テストメッセージ処理: シンプルなテキストメッセージを送信し、レスポンスを検証する
1. セッション管理のテスト: 永続的な会話が期待どおりに機能することを確認する
1. テストエラー処理: エージェントが接続ドロップと不正な形式のメッセージを適切に処理することを確認する
**認証の問題**
デプロイされたエージェントの認証設定を確認します。
+ OAuth の場合: ベアラートークンが有効で、有効期限が切れていないことを確認します
+ SigV4 の場合: WebSocket URL、ヘッダー、リクエストメソッドなど、署名アルゴリズムへの入力が正しいことを確認します。
+ エージェントの設定に一致する正しい認証方法を使用する
**一般的な接続の問題**
WebSocket 接続の一般的な問題に対処します。
+ エージェントとクライアントの期待間のメッセージ形式の互換性を検証する
+ メッセージフレームの断片化を設定するか、チャンキングを実装してメッセージフレームサイズ (64 KB) とメッセージフレームレート (250 フレーム/秒) の制限内に留まり、接続が閉じないようにします。
## コードの変更が既存のセッションに反映されない
**[Problem]** (問題)
エージェントランタイムを新しいコードで更新しましたが、既存のセッションは引き続き古いバージョンを使用します。
**これが発生する理由**
各 microVM セッションは、セッションの作成時にデプロイされたコードアセット () `agentRuntimeArtifact` を使用して作成されます。セッションが確立されると、[UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html) オペレーションの実行の一環としてコードアセットが更新されても、セッションが終了するまでそのバージョンのコードが引き続き使用されます。
**解決策**
更新されたコードにアクセスするには、新しいセッション ID を使用します。
## ランタイムが Lambda 関数から呼び出されたときにスパンが欠落している
**これが発生した場合:** Lambda 関数から AgentCore ランタイムを呼び出す場合
**これが発生する理由:** Lambda は独自の`X-Amzn-Trace-Id`ヘッダーを生成します。Lambda トレースに がある場合`Sampled=0`、このサンプリングされていないコンテキストは AgentCore ランタイムに伝達され、ランタイムはその呼び出しのスパン生成をスキップします。
**解決策:**
+ **Lambda アクティブトレースを有効にする:** Lambda 関数で X-Ray アクティブトレースを有効にして、サンプリングされたトレース (`Sampled=1`) を生成します。
+ **CloudWatch トランザクション検索の確認:** [「オブザーバビリティの設定](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html)」のセットアップが完了し、トレースセグメントの送信先が CloudWatch Logs に設定されていることを確認します。
+ **サンプリング決定を確認する:** Lambda 関数内に`_X_AMZN_TRACE_ID`環境変数をログに記録します。と表示されている場合`Sampled=0`、アクティブトレースは有効になっていないか、アップストリーム発信者がサンプリングを決定しています。
## S3 ファイルまたは EFS マウントが「アクセス拒否」で失敗する
**これが発生した場合: **S3 ファイルまたは EFS ストレージが設定されたエージェントの呼び出し中
**これが発生する理由:** 実行ロールに必要なファイルシステムのアクセス許可がありません。永続ストレージの設定の詳細については、[AgentCore ランタイムのファイルシステム設定](runtime-filesystem-configurations.md)」を参照してください。
**解決策:**
S3 ファイルの場合、実行ロールに次のものがあることを確認します。
```
{
"Effect": "Allow",
"Action": [
"s3files:ClientMount",
"s3files:ClientWrite"
],
"Resource": "arn:aws:s3files:::file-system/*",
"Condition": {
"StringEquals": {
"s3files:AccessPointArn": ""
}
}
}
```
EFS の場合、実行ロールに次のものがあることを確認します。
```
{
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": "arn:aws:elasticfilesystem:::file-system/",
"Condition": {
"StringEquals": {
"elasticfilesystem:AccessPointArn": ""
}
}
}
```
エージェントが読み取りアクセスのみを必要とする`elasticfilesystem:ClientWrite`場合は、 `s3files:ClientWrite`または を省略します。
## S3 ファイルまたは EFS マウントがResourceNotFound」で失敗する
**これが発生した場合: **S3 ファイルまたは EFS ストレージが設定されたエージェントの呼び出し中
**これが発生する理由:** エージェントの作成後にファイルシステムまたはアクセスポイントが削除されたか、IDsが正しくありません。
**解決策:**
+ ファイルシステムが存在することを確認します。
+ S3 ファイル: `aws s3files list-file-systems --region `
+ EFS: `aws efs describe-file-systems --region `
+ アクセスポイントが存在することを確認します。
+ S3 ファイル: `aws s3files list-access-points --file-system-id --region `
+ EFS: `aws efs describe-access-points --file-system-id --region `
+ 必要なすべてのアベイラビリティーゾーンにマウントターゲットが存在することを確認します。
+ S3 ファイル: `aws s3files list-mount-targets --file-system-id --region `
+ EFS: `aws efs describe-mount-targets --file-system-id --region `
+ 各マウントターゲットが使用可能ステータスを示し、エージェントのランタイムと同じ VPC にあることを確認します。
+ リソースが削除された場合は、リソースを再作成し、エージェントのランタイムを新しいアクセスポイント ARN で更新します。
## S3 ファイルまたは EFS マウントがタイムアウトする
**これが発生した場合: **S3 ファイルまたは EFS ストレージが設定されたエージェントの呼び出し中。呼び出しが失敗するまでに通常よりも時間がかかる場合があります。
**これが発生する理由:** VPC ネットワーク設定は、エージェントのコンピューティングとファイルシステムのマウントターゲット間の NFS トラフィック (ポート 2049) をブロックしています。
**解決策:**
+ **マウントターゲットのセキュリティグループを確認する: **マウントターゲットにアタッチされたセキュリティグループが、エージェントのランタイムで使用されるセキュリティグループからの**インバウンド TCP をポート 2049 で**許可することを確認する
+ **エージェントランタイムでセキュリティグループを確認する:** エージェントランタイムで使用されるセキュリティグループが、マウントターゲットセキュリティグループへの**ポート 2049 でのアウトバウンド TCP** を許可していることを確認します。
+ **マウントターゲットが正しいアベイラビリティーゾーンに存在することを確認する:** マウントターゲットは、エージェントのランタイムに設定されたサブネットと同じアベイラビリティーゾーンに存在する必要があります。
+ S3 ファイル: `aws s3files list-mount-targets --file-system-id --region `
+ EFS: `aws efs describe-mount-targets --file-system-id --region `
+ **サブネットルーティングの検証:** サブネットに適切なルーティング (CIDR 範囲のローカル VPC ルート) があることを確認します。
## マウントされたファイルシステムに書き込むと「アクセス許可が拒否」される
**これが発生した場合:** エージェント呼び出しは成功し、エージェントはマウントからファイルを読み取ることができますが、書き込みは「アクセス許可が拒否されました」で失敗します。
**これが発生する理由:** IAM ロールに書き込みアクセス許可がないか、アクセスポイントの作成中に設定されたディレクトリに対する POSIX アクセス許可がエージェントのユーザーの書き込みを許可していません。
**解決策:**
+ **IAM アクセス許可を確認する:** 実行ロールに `s3files:ClientWrite` (S3 ファイル) または `elasticfilesystem:ClientWrite` (EFS) が含まれていることを確認します。書き込みアクセス許可がない場合、マウントは読み取り専用です。詳細については、[「Amazon Bedrock AgentCore ランタイム実行ロールのアクセス許可](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)」を参照してください。
+ **POSIX アクセス許可を確認する:** ディレクトリがコンテナプロセスとは異なるユーザーによって所有されている場合、書き込みは拒否されます。次のいずれかを実行します:
+ アクセスポイントの posixUser をコンテナが実行する uid/gid と一致するように設定し、すべてのオペレーションがそのユーザーとして実行されます。
+ ディレクトリのアクセス許可を 777 に設定して、すべてのユーザーに書き込みを許可します。
## コンテナがハイレイヤーイメージで HTTP 424 エラーで起動しない
**これが発生した場合:** `InvokeAgentRuntime`呼び出しは HTTP 424 (Failed Dependency) を返し、エージェントログには が表示されます`Failed to mount overlay: No such file or directory`。これは、コンテナイメージに 53 を超えるレイヤーがあり、数値以外の USER ディレクティブ ( `USER myuser`ではなく など`USER 1000`) を使用している場合に発生します。
**これが発生する理由:** 多数のレイヤーを持つコンテナイメージを数値以外の USER ディレクティブと組み合わせると、初期化が失敗する可能性があります。
**解決策:** 次のいずれかの回避策を使用します。
+ **数値 USER ディレクティブを使用する:** Dockerfile で、 を数値 UID (例: `USER 1000`) `USER myuser`に置き換えます。コンテナ`id myuser`内で を実行することで、ユーザーの UID を見つけることができます。これにより、ファイルシステムのマウントが完全に回避されます。
+ **イメージレイヤーを減らす:** マルチステージ Docker ビルドを使用して、イメージを 53 レイヤー未満に減らします。イメージのレイヤー数は、以下を使用して確認できます。
```
docker inspect | jq '.[0].RootFS.Layers | length'
```
+ **スカッシュレイヤー:** `docker build --squash`または などのツールを使用してイメージレイヤー`docker-squash`をフラット化します。
## ベストプラクティス
**包括的なログ記録を有効にする**
エージェントに詳細なログ記録を実装します。
+ エージェントにリクエスト/レスポンスのログ記録を含める
+ 重要なパスとエラー条件をログに記録する
**構造化エラー処理を使用する**
明確なエラーレポートを実装します。
+ 特定のコードを含むクリアエラーメッセージを返す
+ エラーレスポンスに実用的な情報を含める
**増分変更をテストする**
体系的なテストアプローチに従います。
+ エージェントを変更するときは、デプロイ前にローカルでテストします。
+ ローカル環境とデプロイされた環境の両方でペイロードの互換性を検証する
**パフォーマンスのモニタリング**
エージェントのモニタリングをセットアップします。
+ CloudWatch メトリクスを使用して呼び出しパターンを追跡する
+ エラー率とレイテンシーのアラームを設定する