Claude Code を AWS の AgentCore 上で動かすという AWSによるサンプル を自分で実装してみました。デプロイ時のつまづきポイントや、AgentCoreの良さ、実装のポイントなどに気づいたので備忘のために記録します。
リージョンの設定
東京リージョン (ap-northeast-1) が利用可能でした。私の実装例 には東京リージョンに改変したコードを提示していますので参考にしてください。
モデルの選択
費用を抑えるために sonnet ではなく haiku を使用することにしました。
bedrockのモデルで
global.anthropic.claude-haiku-4-5-20251001-v1:0 のように global. プレフィックスをつけるとリージョンをまたいで推論することができますが、今回のように東京リージョンに限定して使用するなら、
jp.anthropic.claude-haiku-4-5-20251001-v1:0
と jp. プレフィックスを使うのが反応速度も早くおすすめです。
なお、東京リージョンで使用可能なプロファイルを確認する aws-cli のコマンドは下記です。
aws bedrock list-inference-profiles --region ap-northeast-1
権限の追加
下記の権限が必要でした
aws-marketplace:ViewSubscriptionsaws-marketplace:Subscribe
AWS CLI のIAMユーザーに AWSMarketplaceFullAccess をアタッチするとともに infrastructure.yaml で AgentCore に下記を付与しました
# infrastructure.yaml lines 92-97
- Sid: MarketplaceAccess
Effect: Allow
Action:
- "aws-marketplace:ViewSubscriptions"
- "aws-marketplace:Subscribe"
Resource: "*"
AWS CLI のバージョンに注意
bedrock-agentcoreコマンドはv2.32.1以降でサポートされています。AWS CLIのバージョンに注意してください。
タイムアウト
例では実行時のタイムアウトが60秒になっていましたが、これはエージェントにはあまりにも短いです。私は10分にしてみました。
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "$RUNTIME_ARN" \
--region "$REGION" \
--payload "$PAYLOAD" \
--cli-read-timeout 600 \
"$OUTPUT_FILE"
API Gateway からのアクセス
AgentCoreをAWS CLI から使う方法はAWSのサンプルで理解できましたが、「普通に使うときはどうしたらいいん？」 という疑問がわきました。AgentCoreには Gateway という機能が備わっていますが、これは AgentCoreが外部ツールを使用するときのインターフェース のようです。AgentCore を呼び出すときには API Gateway + Lambda を使うのが素直なアプローチではないでしょうか。私の実装例では API キーを設定した API Gateway を使っています。
⚠️ 重要：API Gateway のタイムアウト制限
Gemini 3 Pro (gemini-3-pro-preview) の指摘で気づいたのですが
API Gateway (REST/HTTP) には 29秒のハードリミット があります。エージェントの処理が29秒を超えた場合、504 Gateway Timeout エラーが発生します。
上記の「タイムアウト」セクションで CLI のタイムアウトを10分（600秒）に設定しましたが、API Gateway経由でアクセスする場合、この設定だけでは不十分です。
Gemini 3 Pro が提案する長時間実行するタスクへの対応策：
- 非同期呼び出し: Lambda を非同期で実行し、結果を S3 や DynamoDB に保存してポーリング
- WebSocket API: API Gateway WebSocket API を使用（タイムアウト制限なし）
- AWS AppSync: GraphQL サブスクリプションでリアルタイム応答
- 直接SDK呼び出し: API Gateway を経由せず、AWS SDK から直接 AgentCore を呼び出す
私の実装例も Issue #3 で後ほど対応しようと考えています。
AgentCoreの良さ
まだAgentCoreの全容を理解したわけではないですが、AgentCoreの利点としては、ブラウザ使用や外部ツールの使用など、エージェントに求められる機能が一式備わっていること、またBedrockを使用することでLLMのAPIキーを別途管理する必要がないことがあると感じました。さらにAIエージェントに最適化されたCloudWatchは最も魅力に感じました。LLMの使用などをしっかり監視することができるので、組織で共有のエージェントを作成するなどの用途にはかなり向いていると思います。「サブエージェント」として、比較的軽量で、定型業務に近いエージェントの必要性がこれから増すと考えていますが、そのような用途にはうってつけではないでしょうか。
まとめ
AWS AgentCore 上で Claude Code を動かす実装を通じて、重要だと思ったポイントをまとめます：
- AWS CLI のバージョン確認: v2.32.1以降が必須
-
リージョンプレフィックスの活用: 東京リージョンでは
jp.プレフィックスで高速化 - 適切な権限設定: AWS Marketplace の Subscribe 権限が必要
- タイムアウトの調整: エージェントにはある程度長いタイムアウトが必要
- API Gateway の制限に注意: 29秒制限があるため、長時間タスクには別の方式を検討
AgentCore は、エージェント機能が一式揃った強力なプラットフォームです。特に組織で共有するサブエージェントの構築に向いているのではないでしょうか。
参考文献
- AWS公式サンプル - Claude Code on AgentCore
- 私の実装例（東京リージョン対応版）
- API Gateway のクォータと制限
- Amazon Bedrock Inference Profiles
- AWS CLI v2.32.1 リリースノート
謝辞
図中のAgentCoreのアイコンは mauliksoniさん によるものを使わせていただきました。