feat: add VPC network mode support (#545)

* feat: add VPC network mode support

Replace the PRIVATE network mode placeholder with VPC across the full
CLI stack: schema validation, TUI wizards, CLI flags, template rendering,
and CDK config persistence.

Schema:
- NetworkModeSchema enum: PUBLIC | PRIVATE → PUBLIC | VPC
- Add NetworkConfigSchema with subnet/security group ID validation
- Cross-field superRefine: VPC requires networkConfig, non-VPC forbids it

CLI flags:
- Add --network-mode, --subnets, --security-groups to create and add agent
- Shared vpc-utils.ts with parseCommaSeparatedList, validateVpcOptions,
  validateSubnetIds, validateSecurityGroupIds, and VPC_ENDPOINT_WARNING

TUI:
- VPC prompts in both create (GenerateWizard) and BYO (AddAgentScreen) paths
- Inline validation for subnet/SG ID format in TextInput fields
- VPC endpoint warning on completion screens

Template rendering:
- Add isVpc flag to AgentRenderConfig
- Skip Exa AI MCP example endpoint in VPC mode (unreachable without NAT)
- VPC stubs return None/empty so main.py null-checks work unchanged

Data persistence:
- AgentPrimitive passes VPC config through both handleCreatePath and
  handleByoPath to agentcore.json
- useAddAgent mappers (mapByoConfigToAgent, mapAddAgentConfigToGenerateConfig)
  thread VPC fields through TUI path

Warnings:
- dev command warns about VPC behavior differences in local mode
- invoke command warns about VPC endpoint requirements

* fix: restore existing tests deleted by VPC commit, append VPC tests

The original VPC commit accidentally replaced three test files instead
of appending to them. This restores all existing tests from main and
adds VPC-specific tests at the end of each file.

* fix: add format validation to non-interactive VPC path, consolidate VpcOptions type

- validateVpcOptions now calls validateSubnetIds/validateSecurityGroupIds
  so the non-interactive CLI path gives friendly format errors instead of
  falling through to Zod regex failures
- CreateOptions, AddAgentOptions, and AgentPrimitive.AddAgentOptions now
  extend VpcOptions instead of redeclaring networkMode/subnets/securityGroups

* fix: add VPC warnings to TUI dev and invoke screens

The non-interactive CLI paths had VPC warnings but the TUI screens did not.
- DevScreen: warn that local dev runs outside VPC
- InvokeScreen: warn about VPC endpoint requirements
- Thread networkMode through useInvokeFlow config

* fix: pass VPC config through create TUI flow

The GenerateWizard collected networkMode/subnets/securityGroups but
useCreateFlow did not include them when building the GenerateConfig,
so agents created via TUI always defaulted to PUBLIC.

Author: tejaskash

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -1012,6 +1012,15 @@ exports[`Assets Directory Snapshots > Python framework assets > python/python/au
 
 exports[`Assets Directory Snapshots > Python framework assets > python/python/autogen/base/mcp_client/client.py should match snapshot 1`] = `
 "from typing import List
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with \`agentcore add gateway\`, or configure your own endpoint below.
+
+
+async def get_streamable_http_mcp_tools() -> List:
+    """No MCP server configured. Add a gateway with \`agentcore add gateway\`."""
+    return []
+{{else}}
 from autogen_ext.tools.mcp import (
     StreamableHttpMcpToolAdapter,
     StreamableHttpServerParams,
@@ -1029,6 +1038,7 @@ async def get_streamable_http_mcp_tools() -> List[StreamableHttpMcpToolAdapter]:
     # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
     server_params = StreamableHttpServerParams(url=EXAMPLE_MCP_ENDPOINT)
     return await mcp_server_tools(server_params)
+{{/if}}
 "
 `;
 
@@ -1792,6 +1802,14 @@ def get_all_gateway_mcp_toolsets() -> list[MCPToolset]:
     {{/each}}
     return toolsets
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with \`agentcore add gateway\`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPToolset | None:
+    """No MCP server configured. Add a gateway with \`agentcore add gateway\`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -1803,6 +1821,7 @@ def get_streamable_http_mcp_client() -> MCPToolset:
         connection_params=StreamableHTTPConnectionParams(url=EXAMPLE_MCP_ENDPOINT)
     )
 {{/if}}
+{{/if}}
 "
 `;
 
@@ -2098,6 +2117,14 @@ def get_all_gateway_mcp_client() -> MultiServerMCPClient | None:
         return None
     return MultiServerMCPClient(servers)
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with \`agentcore add gateway\`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MultiServerMCPClient | None:
+    """No MCP server configured. Add a gateway with \`agentcore add gateway\`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -2114,6 +2141,7 @@ def get_streamable_http_mcp_client() -> MultiServerMCPClient:
         }
     )
 {{/if}}
+{{/if}}
 "
 `;
 
@@ -2545,6 +2573,14 @@ def get_all_gateway_mcp_servers() -> list[MCPServerStreamableHttp]:
     {{/each}}
     return servers
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with \`agentcore add gateway\`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPServerStreamableHttp | None:
+    """No MCP server configured. Add a gateway with \`agentcore add gateway\`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -2556,6 +2592,7 @@ def get_streamable_http_mcp_client() -> MCPServerStreamableHttp:
         name="AgentCore Gateway MCP", params={"url": EXAMPLE_MCP_ENDPOINT}
     )
 {{/if}}
+{{/if}}
 "
 `;
 
@@ -2879,6 +2916,14 @@ def get_all_gateway_mcp_clients() -> list[MCPClient]:
     {{/each}}
     return clients
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with \`agentcore add gateway\`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPClient | None:
+    """No MCP server configured. Add a gateway with \`agentcore add gateway\`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -2887,6 +2932,7 @@ def get_streamable_http_mcp_client() -> MCPClient:
     # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
     return MCPClient(lambda: streamablehttp_client(EXAMPLE_MCP_ENDPOINT))
 {{/if}}
+{{/if}}
 "
 `;
 

src/assets/python/autogen/base/mcp_client/client.py

@@ -1,4 +1,13 @@
 from typing import List
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+
+async def get_streamable_http_mcp_tools() -> List:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return []
+{{else}}
 from autogen_ext.tools.mcp import (
     StreamableHttpMcpToolAdapter,
     StreamableHttpServerParams,
@@ -16,3 +25,4 @@ async def get_streamable_http_mcp_tools() -> List[StreamableHttpMcpToolAdapter]:
     # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
     server_params = StreamableHttpServerParams(url=EXAMPLE_MCP_ENDPOINT)
     return await mcp_server_tools(server_params)
+{{/if}}

src/assets/python/googleadk/base/mcp_client/client.py

@@ -53,6 +53,14 @@ def get_all_gateway_mcp_toolsets() -> list[MCPToolset]:
     {{/each}}
     return toolsets
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPToolset | None:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -64,3 +72,4 @@ def get_streamable_http_mcp_client() -> MCPToolset:
         connection_params=StreamableHTTPConnectionParams(url=EXAMPLE_MCP_ENDPOINT)
     )
 {{/if}}
+{{/if}}

src/assets/python/langchain_langgraph/base/mcp_client/client.py

@@ -50,6 +50,14 @@ def get_all_gateway_mcp_client() -> MultiServerMCPClient | None:
         return None
     return MultiServerMCPClient(servers)
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MultiServerMCPClient | None:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -66,3 +74,4 @@ def get_streamable_http_mcp_client() -> MultiServerMCPClient:
         }
     )
 {{/if}}
+{{/if}}

src/assets/python/openaiagents/base/mcp_client/client.py

@@ -52,6 +52,14 @@ def get_all_gateway_mcp_servers() -> list[MCPServerStreamableHttp]:
     {{/each}}
     return servers
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPServerStreamableHttp | None:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -63,3 +71,4 @@ def get_streamable_http_mcp_client() -> MCPServerStreamableHttp:
         name="AgentCore Gateway MCP", params={"url": EXAMPLE_MCP_ENDPOINT}
     )
 {{/if}}
+{{/if}}

src/assets/python/strands/base/mcp_client/client.py

@@ -54,6 +54,14 @@ def get_all_gateway_mcp_clients() -> list[MCPClient]:
     {{/each}}
     return clients
 {{else}}
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+def get_streamable_http_mcp_client() -> MCPClient | None:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return None
+{{else}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -62,3 +70,4 @@ def get_streamable_http_mcp_client() -> MCPClient:
     # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
     return MCPClient(lambda: streamablehttp_client(EXAMPLE_MCP_ENDPOINT))
 {{/if}}
+{{/if}}

src/cli/commands/add/__tests__/validate.test.ts

@@ -989,3 +989,80 @@ describe('validate', () => {
     });
   });
 });
+
+describe('validateAddAgentOptions - VPC validation', () => {
+  const baseOptions: AddAgentOptions = {
+    name: 'TestAgent',
+    type: 'byo',
+    language: 'Python',
+    framework: 'Strands',
+    modelProvider: 'Bedrock',
+    build: 'CodeZip',
+    codeLocation: './app/test/',
+  };
+
+  it('accepts valid VPC options', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      networkMode: 'VPC',
+      subnets: 'subnet-12345678',
+      securityGroups: 'sg-12345678',
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts PUBLIC network mode without VPC options', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      networkMode: 'PUBLIC',
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects invalid network mode', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      networkMode: 'INVALID',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('Invalid network mode');
+  });
+
+  it('rejects VPC mode without subnets', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      networkMode: 'VPC',
+      securityGroups: 'sg-12345678',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('--subnets is required');
+  });
+
+  it('rejects VPC mode without security groups', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      networkMode: 'VPC',
+      subnets: 'subnet-12345678',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('--security-groups is required');
+  });
+
+  it('rejects subnets without VPC mode', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      subnets: 'subnet-12345678',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('only valid with --network-mode VPC');
+  });
+
+  it('rejects security groups without VPC mode', () => {
+    const result = validateAddAgentOptions({
+      ...baseOptions,
+      securityGroups: 'sg-12345678',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('only valid with --network-mode VPC');
+  });
+});

src/cli/commands/add/types.ts

@@ -1,8 +1,9 @@
 import type { GatewayAuthorizerType, ModelProvider, SDKFramework, TargetLanguage } from '../../../schema';
 import type { MemoryOption } from '../../tui/screens/generate/types';
+import type { VpcOptions } from '../shared/vpc-utils';
 
 // Agent types
-export interface AddAgentOptions {
+export interface AddAgentOptions extends VpcOptions {
   name?: string;
   type?: 'create' | 'byo';
   build?: string;

src/cli/commands/add/validate.ts

@@ -11,6 +11,7 @@ import {
   getSupportedModelProviders,
   matchEnumValue,
 } from '../../../schema';
+import { validateVpcOptions } from '../shared/vpc-utils';
 import type {
   AddAgentOptions,
   AddGatewayOptions,
@@ -150,6 +151,12 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes
     }
   }
 
+  // Validate VPC options
+  const vpcResult = validateVpcOptions(options);
+  if (!vpcResult.valid) {
+    return { valid: false, error: vpcResult.error };
+  }
+
   return { valid: true };
 }