AgentCore Runtime VPC設定機能とネットワーク構成オプションの追加

[nakayukl-demo]

概要

AgentCore RuntimeのVPCネットワーク設定機能を追加し、プライベートネットワーク環境での動作をサポートしました。

変更内容

🚀 新機能

• AgentCore Runtime VPC設定: PUBLIC/PRIVATEネットワークモードの選択が可能
• VPCネットワーク構成: 既存VPCとサブネットを指定してAgentCore Runtimeをデプロイ

🔧 実装詳細

新規パラメータ

• agentCoreNetworkType: PUBLIC (デフォルト) / PRIVATE
• agentCoreVpcId: 使用するVPC ID
• agentCoreSubnetIds: 使用するサブネットIDリスト

コード変更

• stack-input.ts: VPC設定パラメータとバリデーション追加
• agent-core-stack.ts: VPC設定パラメータの受け渡しとCloudFormation出力
• generic-agent-core.ts: VPC/セキュリティグループ作成ロジック実装

⚠️ 重要な設計判断

セキュリティグループのRetain設定

VPCモード使用時、セキュリティグループにRemovalPolicy.RETAINを設定：

• AgentCore Runtimeが作成するAWSマネージドENIがセキュリティグループを参照
• CloudFormationではマネージドENI削除前にセキュリティグループを削除不可
• マネージドENIの自動削除完了後（長い場合数時間）に手動削除が必要
• CloudFormation出力でセキュリティグループIDを表示し、手動削除を促進

📚 ドキュメント更新

• 日本語/英語/韓国語: AgentCore Runtime VPC設定セクション追加
• 使用場面: 社内システム連携、プライベートデータベースアクセス等
• AZ制限: リージョンごとのサポート対象AZ情報
• NAT Gateway要件: MCPサーバーインストール用インターネットアクセス
• 手動削除手順: AgentCore無効化後のスタック削除方法

🧪 テスト

• スナップショットテスト更新済み
• AgentCore設定変更フローテスト: なし → PUBLIC → PRIVATE → PUBLIC → なし
• Generic RuntimeとAgentBuilder Runtime両方の動作確認
• セキュリティグループの適切なタグ付けと保持確認
• VPC内データベース接続テスト: プライベートサブネット内のSQL Server RDSに対してMSSQL MCPサーバー経由でのデータベースアクセス動作確認済み

"mssql": {
  "command": "npx",
  "args": ["@wener/mssql-mcp", "--stdio"],
  "env": {
    "MSSQL_SERVER": "xxxxxxxx.xxxxxxxx.us-east-1.rds.amazonaws.com",
    "MSSQL_DATABASE": "xxxxxxxx",
    "MSSQL_USER": "xxxxxxxx",
    "MSSQL_PASSWORD": "xxxxxxxx"
  },
  "metadata": {
    "category": "Database",
    "description": "Microsoft SQL Server database access for AgentBuilder"
  }
}

使用例

// parameter.ts
const envs: Record<string, Partial<StackInput>> = {
  dev: {
    createGenericAgentCoreRuntime: true,
    agentBuilderEnabled: true,
    agentCoreNetworkType: 'PRIVATE',
    agentCoreVpcId: 'vpc-xxxxxxxxx',
    agentCoreSubnetIds: ['subnet-xxxxxxxxx', 'subnet-yyyyyyyyy'],
  },
};

影響範囲

• 既存のPUBLICモードは後方互換
• VPCモードはデフォルトでは無効（PUBLICがデフォルト）
• セキュリティグループの手動削除が必要（コスト影響なし）

参考リンク

• AWS公式ドキュメント: AgentCore VPC connectivity

参考動画

• RDS に接続しての動作の様子
  https://github.com/user-attachments/assets/259e315a-8d03-4083-bfc9-bfeba92fb819

[tbrand]

agentCoreNetworkType の仕様について質問です。VpcId と SubnetIds がともに指定されている場合、自動で private 判定されるというロジックではだめでしょうか？また、PUBLIC、PRIVATE という文字列による指定である必要はありますか？例えば、これ以上選択肢が増える見込みがない場合、boolean で良いのではないでしょうか？

[nakayukl-demo]

VpcId と SubnetIds がともに指定されている場合、自動で private 判定されるというロジックではだめでしょうか？

いいですね！そちらの方がシンプルで開発者の設定が少なくて良いと思います。
もともと、agentcore の network configuration の 引数にそのまま PUBLIC と PRIVATE で渡せるってだけだったので、ご指摘のように変えようと思います。しばしお待ちを。

[nakayukl-demo]

修正してみました。まだテストとドキュメントを修正途中なのでマージは待っていただけると嬉しいのですが、1 点、GenU の cdk.json や parameter.ts を stack に波及させる部分の設計意図に沿っているか判断できない部分がありご質問です。

例えば、これ以上選択肢が増える見込みがない場合、boolean で良いのではないでしょうか？

この修正のために、parameter.ts の getParam 内で、 isAgentCoreNetworkPrivate: boolean を agentCoreVpcId, agentCoreSubnetIds から自動で判定するロジックを実装しています。そして、その isAgentCoreNetworkPrivate を agent core runtime の stack に渡す仕組みです。変換ロジックの差し込み場所がこの位置で正しそうかコメントいただけますと幸いです。

私の処理の理解は以下の通りで、これが正しそうなら、今差し込んでいる場所で良さそうだなと思いつつ。

[tbrand]

https://github.com/aws-samples/generative-ai-use-cases/pull/1360/files#diff-7222bc11938073d7b5cdde6d47c378c7dfcebe6d024af0e6ab00d252a62a9820R82
こちらのことでしょうか？であれば、ここで良いと思います。

[nakayukl-demo]

細かいところで、恐縮でした。ありがとございます。
では、このままテスト進めます。

[nakayukl-demo]

@tbrand
修正、テスト完了し、チェックとおりました。ご確認をお願いします。