イメージをビルドする

AWS Bedrock AgentCore でエージェントを実行するには、イメージを agent-proxy レイヤーでラップする必要があります。agent-proxy レイヤーは、オブザーバビリティと監査のために、エージェントのすべてのアウトバウンドトラフィックをインターセプトし、送信元、宛先、バイト数をログに記録します。AgentCore ランタイムをセットアップするときに管理対象ゲートウェイを作成した場合、agent-proxy レイヤーはさらにすべてのアウトバウンドトラフィックをゲートウェイ経由に再ルーティングし、ゲートウェイがランタイム認可ポリシーを適用し、エージェントと AgentCore にデプロイされている MCP サーバー間の通信を仲介できるようにします。

エージェントイメージを agent-proxy レイヤーでラップするには、arctl wrap-agent-image コマンドを使用します。ラップの対象になるには、Dockerfile が次の要件を満たしている必要があります。

• Dockerfile では実際の ENTRYPOINT または CMD を設定する必要があります。イメージの起動コマンドは、agent-proxy レイヤー経由で起動するように書き換えられます。Dockerfile に起動コマンドが設定されていない場合、イメージのラップは失敗します。
• Dockerfile で root 以外の USER を設定する場合、そのユーザーはイメージ自身の /etc/passwd ファイルと /etc/group ファイルから解決できる必要があります。agent-proxy レイヤーはエージェントを起動するときにこのユーザーを保持し、ID を解決できない場合は起動に失敗します。
• エージェントは、AWS Bedrock AgentCore がリクエストを転送するポートでリッスンする必要があります。A2A プロトコルでは 9000、エージェント定義で spec.source.protocol が HTTP に設定されている場合は 8080 です。agent-proxy レイヤーは各インバウンドリクエストをこの同じポート上のエージェントに転送します。

AWS Bedrock AgentCore は、AgentCore ランタイムと同じ AWS アカウントおよびリージョン内のプライベート Amazon ECR リポジトリからプルする linux/arm64 イメージだけを実行します。そのため、ラップ済みイメージを Amazon ECR リポジトリにプッシュする必要があります。

1. ローカルマシンでエージェントを作成して実行します。

2. エージェントイメージ用のプライベート Amazon ECR リポジトリがまだない場合は作成します。詳細については、AWS ドキュメントのプライベートリポジトリの作成を参照してください。

   aws ecr create-repository \
     --repository-name myagent \
     --region <region>

   出力例:

   {
     "repository": {
       "repositoryUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent",
       ...
     }
   }
   

3. Docker を ECR レジストリに認証します。

   aws ecr get-login-password --region <region> \
     | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

4. linux/arm64 イメージをビルドし、先ほど取得した AWS ECR リポジトリ URI にプッシュします。Dockerfile が前述の要件を満たしていることを確認してください。このステップで作成するイメージは、エージェントのベースイメージになります。後でこのイメージの上に agent-proxy を重ね、ラップ済みイメージも同じリポジトリにプッシュします。

   Note

   AgentCore は、この後のステップで作成するラップ済みイメージからエージェントを起動します。このステップで作成するベースイメージからは起動しません。ベースイメージは任意のコンテナレジストリに保存できます。ただし、このガイドでは、ベースイメージをラップ済みイメージと同じリポジトリに保存することを前提とします。

   arctl build myagent \
     --image 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest \
     --platform linux/arm64 \
     --push

   出力例:

   Building agent image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   ✓ Successfully built Docker image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   ✓ Pushed image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   

5. プッシュ済みのベースイメージを agent-proxy レイヤーでラップし、別のタグを付けて同じリポジトリにプッシュします。AWS Bedrock AgentCore は、エージェントランタイムをデプロイするときにラップ済みイメージだけをプルします。

   arctl wrap-agent-image \
     --image 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest \
     --tag 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:wrapped \
     --platform linux/arm64 \
     --push

   設定	説明
   --image	ラップするエージェントイメージです。
   --tag	ラップ済みイメージに割り当てる参照です。ラップ前のイメージも利用可能なままにするため、新しいタグを使用します。
   --platform	ベースイメージのプラットフォームです。AWS Bedrock AgentCore では linux/arm64 を使用します。
   --push	--tag オプションで定義したリポジトリに、ラップ済みイメージを直接プッシュします。

6. agent.yaml ファイル内のエージェント定義で、spec.source.image フィールドを 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:wrapped などのラップ済みイメージタグに更新します。