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

Co-authored-by: Taiki Maekawa <tmae@amazon.com>

Author: nakayukl-demo

docs/en/DEPLOY_OPTION.md

@@ -830,6 +830,65 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
+> [!NOTE]
+> After enabling AgentCore use case settings, if you want to disable them again, you can disable the AgentCore use case by setting `createGenericAgentCoreRuntime: false` and redeploying, but the `AgentCoreStack` itself will remain. You can completely remove it by opening the Management Console and deleting the `AgentCoreStack` stack from CloudFormation in the `agentCoreRegion`.
+
+#### AgentCore Runtime Network Configuration
+
+AgentCore Runtime can operate in the following network modes:
+
+- `PUBLIC` (default): Operates on public network
+- `PRIVATE`: Operates on private network within VPC
+
+Network settings apply to both Generic Runtime and AgentBuilder Runtime.
+
+**Use cases for VPC mode**:
+
+- When AgentCore Runtime needs to access internal systems or private databases
+- For example, when you want to communicate directly with other AWS services (RDS, ElastiCache, etc.) within the VPC
+
+When using VPC mode, configure the following parameters:
+
+- `agentCoreVpcId`: VPC ID to use
+- `agentCoreSubnetIds`: List of subnet IDs to use
+
+> [!NOTE]
+> When both `agentCoreVpcId` and `agentCoreSubnetIds` are configured, AgentCore Runtime will be deployed in private network mode. If both are left unset (`null`), it will be deployed in public network mode.
+
+> [!IMPORTANT]
+> **Availability Zone (AZ) Support**: AgentCore Runtime has limited supported AZs per region. Subnets must be placed within supported AZs. For details, please refer to the [AWS official documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html#agentcore-supported-azs).
+>
+> **Internet Access**: AgentCore Runtime requires internet access for MCP server installation. If connecting to private subnets, configure routes to NAT Gateway.
+
+**Edit [parameter.ts](/packages/cdk/parameter.ts)**
+
+```typescript
+// parameter.ts
+const envs: Record<string, Partial<StackInput>> = {
+  dev: {
+    createGenericAgentCoreRuntime: true,
+    agentCoreVpcId: 'vpc-xxxxxxxxx',
+    agentCoreSubnetIds: ['subnet-xxxxxxxxx', 'subnet-yyyyyyyyy'],
+  },
+};
+```
+
+**Edit [packages/cdk/cdk.json](/packages/cdk/cdk.json)**
+
+```json
+// cdk.json
+{
+  "context": {
+    "createGenericAgentCoreRuntime": true,
+    "agentCoreVpcId": "vpc-xxxxxxxxx",
+    "agentCoreSubnetIds": ["subnet-xxxxxxxxx", "subnet-yyyyyyyyy"]
+  }
+}
+```
+
+> [!WARNING]
+> When using VPC mode, security groups are not automatically deleted when AgentCore Runtime is deleted due to changes such as from PRIVATE to PUBLIC. This is because AWS-managed ENIs created by AgentCore Runtime reference the security groups, making them undeletable by CloudFormation. After deleting AgentCore Runtime, wait for the managed ENIs to be automatically deleted, then manually delete the security groups. The security group IDs that need to be deleted are displayed in the CloudFormation outputs. Note: if the initial deployment fails (e.g., unsupported AZ), the security group may also remain and need to be cleaned up manually.
+
 ### Enabling AgentBuilder Use Case
 
 This is a use case where users can freely create Agents for each use case by configuring system prompts and arbitrary MCPs. (Experimental: Breaking changes may be made without notice)

docs/ja/DEPLOY_OPTION.md

@@ -849,6 +849,65 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
+> [!NOTE]
+> AgentCore ユースケースの設定を有効後に、再度無効化する場合は、`createGenericAgentCoreRuntime: false` にして再デプロイすればAgentCore ユースケースは無効化されますが、`AgentCoreStack` 自体は残ります。マネージメントコンソールを開き、`agentCoreRegion` の CloudFormation から `AgentCoreStack` というスタックを削除することで完全に消去ができます。
+
+#### AgentCore Runtime のネットワーク設定
+
+AgentCore Runtime は以下のネットワークモードで動作できます：
+
+- `PUBLIC` (デフォルト): パブリックネットワークで動作
+- `PRIVATE`: VPC内のプライベートネットワークで動作
+
+ネットワーク設定は、Generic Runtime と AgentBuilder Runtime の両方に適用されます。
+
+**VPCモードの使用場面**:
+
+- AgentCore Runtime から社内システムやプライベートデータベースにアクセスする必要がある場合
+- 例えば、VPC内の他のAWSサービス（RDS、ElastiCache等）と直接通信したい場合
+
+VPC モードを使用する場合は、以下のパラメータを設定してください：
+
+- `agentCoreVpcId`: 使用するVPCのID
+- `agentCoreSubnetIds`: 使用するサブネットのIDリスト
+
+> [!NOTE]
+> `agentCoreVpcId`と`agentCoreSubnetIds`を両方設定すると、AgentCore Runtimeはプライベートネットワークモードでデプロイされます。両方とも未設定（`null`）の場合は、パブリックネットワークモードでデプロイされます。
+
+> [!IMPORTANT]
+> **Availability Zone (AZ) サポート**: AgentCore RuntimeはリージョンごとにサポートされているAZが限定されています。サブネットは必ずサポートされているAZ内に配置してください。詳細は[AWS公式ドキュメント](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html#agentcore-supported-azs)をご確認ください。
+>
+> **インターネットアクセス**: AgentCore Runtime で MCP サーバーのインストールにはインターネットアクセスが必要です。プライベートサブネットが接続先の場合には NAT Gateway 等のインターネット到達経路を設定してください。
+
+**[parameter.ts](/packages/cdk/parameter.ts) を編集**
+
+```typescript
+// parameter.ts
+const envs: Record<string, Partial<StackInput>> = {
+  dev: {
+    createGenericAgentCoreRuntime: true,
+    agentCoreVpcId: 'vpc-xxxxxxxxx',
+    agentCoreSubnetIds: ['subnet-xxxxxxxxx', 'subnet-yyyyyyyyy'],
+  },
+};
+```
+
+**[packages/cdk/cdk.json](/packages/cdk/cdk.json) を編集**
+
+```json
+// cdk.json
+{
+  "context": {
+    "createGenericAgentCoreRuntime": true,
+    "agentCoreVpcId": "vpc-xxxxxxxxx",
+    "agentCoreSubnetIds": ["subnet-xxxxxxxxx", "subnet-yyyyyyyyy"]
+  }
+}
+```
+
+> [!WARNING]
+> VPC モードを使用する場合、例えば PRIVATE から PUBLIC への変更により AgentCore Runtime 削除時にセキュリティグループが自動削除されません。AgentCore Runtime が作成する AWS マネージドな ENI がセキュリティグループを参照するため、CloudFormation では削除できません。AgentCore Runtime 削除後、マネージド ENI が自動削除されるまで待ってから、手動でセキュリティグループを削除してください。削除が必要なセキュリティグループ ID は CloudFormation の出力に表示されます。
+
 ### AgentBuilder ユースケースの有効化
 
 ユーザーがシステムプロンプトと任意の MCP を設定することでユースケースごとの Agent を自由に作成できるユースケースです。(Experimental: 予告なく破壊的変更を行うことがあります)

docs/ko/DEPLOY_OPTION.md

@@ -820,6 +820,67 @@ const envs: Record<string, Partial<StackInput>> = {
 }
 ```
 
+> [!NOTE]
+> AgentCore 사용 사례 설정을 활성화한 후 다시 비활성화하려면 `createGenericAgentCoreRuntime: false`로 설정하고 재배포하면 AgentCore 사용 사례가 비활성화되지만 `AgentCoreStack` 자체는 남아있습니다. 관리 콘솔을 열고 `agentCoreRegion`의 CloudFormation에서 `AgentCoreStack` 스택을 삭제하여 완전히 제거할 수 있습니다.
+
+#### AgentCore Runtime 네트워크 설정
+
+AgentCore Runtime은 다음 네트워크 모드에서 작동할 수 있습니다:
+
+- `PUBLIC` (기본값): 퍼블릭 네트워크에서 작동
+- `PRIVATE`: VPC 내 프라이빗 네트워크에서 작동
+
+네트워크 설정은 Generic Runtime과 AgentBuilder Runtime 모두에 적용됩니다.
+
+**VPC 모드 사용 사례**:
+
+- AgentCore Runtime에서 사내 시스템이나 프라이빗 데이터베이스에 액세스해야 하는 경우
+- 예를 들어, VPC 내의 다른 AWS 서비스(RDS, ElastiCache 등)와 직접 통신하고 싶은 경우
+
+VPC 모드를 사용할 때는 다음 매개변수를 설정하세요:
+
+- `agentCoreVpcId`: 사용할 VPC ID
+- `agentCoreSubnetIds`: 사용할 서브넷 ID 목록
+
+> [!NOTE]
+> `agentCoreVpcId`와 `agentCoreSubnetIds`를 모두 설정하면 AgentCore Runtime이 프라이빗 네트워크 모드로 배포됩니다. 둘 다 미설정(`null`)인 경우 퍼블릭 네트워크 모드로 배포됩니다.
+
+> [!IMPORTANT]
+> **가용 영역(AZ) 지원**: AgentCore Runtime은 리전별로 지원되는 AZ가 제한되어 있습니다. 서브넷은 반드시 지원되는 AZ 내에 배치해야 합니다. 자세한 내용은 [AWS 공식 문서](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html#agentcore-supported-azs)를 확인하세요.
+>
+> **인터넷 액세스**: AgentCore Runtime에서 MCP 서버 설치에는 인터넷 액세스가 필요합니다. 프라이빗 서브넷이 연결 대상인 경우 NAT Gateway 등 인터넷 도달 경로를 설정하세요.
+
+**[parameter.ts](/packages/cdk/parameter.ts) 편집**
+
+```typescript
+// parameter.ts
+const envs: Record<string, Partial<StackInput>> = {
+  dev: {
+    createGenericAgentCoreRuntime: true,
+    agentBuilderEnabled: true,
+    agentCoreVpcId: 'vpc-xxxxxxxxx',
+    agentCoreSubnetIds: ['subnet-xxxxxxxxx', 'subnet-yyyyyyyyy'],
+  },
+};
+```
+
+**[packages/cdk/cdk.json](/packages/cdk/cdk.json) 편집**
+
+```json
+// cdk.json
+{
+  "context": {
+    "createGenericAgentCoreRuntime": true,
+    "agentBuilderEnabled": true,
+    "agentCoreVpcId": "vpc-xxxxxxxxx",
+    "agentCoreSubnetIds": ["subnet-xxxxxxxxx", "subnet-yyyyyyyyy"]
+  }
+}
+```
+
+> [!WARNING]
+> VPC 모드를 사용할 때, 예를 들어 PRIVATE에서 PUBLIC으로의 변경으로 인해 AgentCore Runtime 삭제 시 보안 그룹이 자동 삭제되지 않습니다. AgentCore Runtime이 생성하는 AWS 관리형 ENI가 보안 그룹을 참조하기 때문에 CloudFormation에서는 삭제할 수 없습니다. AgentCore Runtime 삭제 후 관리형 ENI가 자동 삭제될 때까지 기다린 다음 수동으로 보안 그룹을 삭제하세요. 삭제가 필요한 보안 그룹 ID는 CloudFormation 출력에 표시됩니다.
+
 ### Voice Chat 사용 사례 활성화
 
 > [!NOTE]

packages/cdk/cdk.json

@@ -71,6 +71,8 @@
     "createGenericAgentCoreRuntime": false,
     "agentCoreRegion": null,
     "agentCoreExternalRuntimes": [],
+    "agentCoreVpcId": null,
+    "agentCoreSubnetIds": null,
     "agentCoreGatewayArns": [],
     "researchAgentEnabled": false,
     "researchAgentBraveApiKey": "",

packages/cdk/lib/agent-core-stack.ts

@@ -23,6 +23,9 @@ export class AgentCoreStack extends Stack {
         env: params.env,
         createGenericRuntime: params.createGenericAgentCoreRuntime,
         createAgentBuilderRuntime: params.agentBuilderEnabled,
+        isAgentCoreNetworkPrivate: params.isAgentCoreNetworkPrivate,
+        agentCoreVpcId: params.agentCoreVpcId,
+        agentCoreSubnetIds: params.agentCoreSubnetIds,
         gatewayArns: params.agentCoreGatewayArns ?? undefined,
       });
 
@@ -44,6 +47,15 @@ export class AgentCoreStack extends Stack {
         );
       }
 
+      // Output retained security group ID for manual cleanup
+      if (this.genericAgentCore.retainedSecurityGroupId) {
+        new CfnOutput(this, 'RetainedSecurityGroupId', {
+          value: this.genericAgentCore.retainedSecurityGroupId,
+          description:
+            'MANUAL CLEANUP REQUIRED: Security Group ID to delete after AgentCore ENI cleanup (check tags: ManualCleanupRequired=true)',
+        });
+      }
+
       if (
         params.agentBuilderEnabled &&
         this.genericAgentCore.deployedAgentBuilderRuntimeArn