feat: add VPC info messages to dev and invoke commands [3/3]

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;

src/cli/commands/dev/command.tsx

@@ -144,6 +144,12 @@ export const registerDev = (program: Command) => {
  const targetAgent = project.agents.find(a => a.name === config.agentName);
  const providerInfo = targetAgent?.modelProvider ?? '(see agent code)';
 
+ if (targetAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+
  console.log(`Starting dev server...`);
  console.log(`Agent: ${config.agentName}`);
  console.log(`Provider: ${providerInfo}`);
@@ -178,6 +184,20 @@ export const registerDev = (program: Command) => {
  await new Promise(() => {});
  }
 
+ // Warn if the target agent uses VPC mode
+ {
+ const vpcAgent = opts.agent
+ ? project.agents.find(a => a.name === opts.agent)
+ : project.agents.length === 1
+ ? project.agents[0]
+ : undefined;
+ if (vpcAgent?.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from deployed environment.'
+ );
+ }
+ }
+
  // Enter alternate screen buffer for fullscreen mode
  process.stdout.write(ENTER_ALT_SCREEN);
 

src/cli/commands/invoke/action.ts

@@ -67,6 +67,12 @@ export async function handleInvoke(context: InvokeContext, options: InvokeOption
  return { success: false, error: 'No agents defined in configuration' };
  }
 
+ if (agentSpec.networkMode === 'VPC') {
+ console.warn(
+ 'Warning: This agent uses VPC network mode. Invocation may require setting up VPC Endpoints for S3, ECR, Bedrock. If your agent uses a non-Bedrock model provider, VPC will require public internet access.'
+ );
+ }
+
  // Get the deployed state for this specific agent
  const agentState = targetState?.resources?.agents?.[agentSpec.name];
 

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
  expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
  });
 
- it('accepts PRIVATE', () => {
- expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+ it('accepts VPC', () => {
+ expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
  });
 
  it('rejects other modes', () => {
- expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+ expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
  });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+ subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+ securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
  runtimeVersion: RuntimeVersion;
  envVars?: EnvVar[];
  networkMode?: NetworkMode; // default 'PUBLIC'
+ networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
  instrumentation?: Instrumentation; // OTel settings
  modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
  EnvVarSchema,
  GatewayNameSchema,
  InstrumentationSchema,
+ NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
  it('accepts agent with network mode', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
- expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'VPC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(true);
  });
 
  it('rejects invalid network mode', () => {
+ expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+ });
+
+ it('rejects VPC mode without networkConfig', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
  });
 
+ it('rejects networkConfig without VPC mode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkMode: 'PUBLIC',
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
+ it('rejects networkConfig with missing networkMode', () => {
+ expect(
+ AgentEnvSpecSchema.safeParse({
+ ...validPythonAgent,
+ networkConfig: {
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ },
+ }).success
+ ).toBe(false);
+ });
+
  it('accepts agent with instrumentation config', () => {
  const result = AgentEnvSpecSchema.safeParse({
  ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
  expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
  });
 });
+
+describe('NetworkConfigSchema', () => {
+ it('accepts valid network config', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('accepts multiple subnets and security groups', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678', 'subnet-abcdef12'],
+ securityGroups: ['sg-12345678', 'sg-abcdef12'],
+ });
+ expect(result.success).toBe(true);
+ });
+
+ it('rejects empty subnets array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: [],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects empty security groups array', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: [],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid subnet format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['invalid-subnet'],
+ securityGroups: ['sg-12345678'],
+ });
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects invalid security group format', () => {
+ const result = NetworkConfigSchema.safeParse({
+ subnets: ['subnet-12345678'],
+ securityGroups: ['invalid-sg'],
+ });
+ expect(result.success).toBe(false);
+ });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
  }
  });
 
- it('accepts explicit PRIVATE networkMode', () => {
- const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+ it('accepts explicit VPC networkMode', () => {
+ const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
  expect(result.success).toBe(true);
  });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+ subnets: z
+ .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+ securityGroups: z
+ .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+ .min(1)
+ .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
- type: AgentTypeSchema,
- name: AgentNameSchema,
- build: BuildTypeSchema,
- entrypoint: EntrypointSchema,
- codeLocation: DirectoryPathSchema,
- runtimeVersion: RuntimeVersionSchemaFromConstants,
- /** Environment variables to set on the runtime */
- envVars: z.array(EnvVarSchema).optional(),
- /** Network mode for the runtime. Defaults to PUBLIC. */
- networkMode: NetworkModeSchema.optional(),
- /** Instrumentation settings for observability. Defaults to OTel enabled. */
- instrumentation: InstrumentationSchema.optional(),
- /** Model provider used by this agent. Optional for backwards compatibility. */
- modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+ .object({
+ type: AgentTypeSchema,
+ name: AgentNameSchema,
+ build: BuildTypeSchema,
+ entrypoint: EntrypointSchema,
+ codeLocation: DirectoryPathSchema,
+ runtimeVersion: RuntimeVersionSchemaFromConstants,
+ /** Environment variables to set on the runtime */
+ envVars: z.array(EnvVarSchema).optional(),
+ /** Network mode for the runtime. Defaults to PUBLIC. */
+ networkMode: NetworkModeSchema.optional(),
+ /** VPC network configuration. Required when networkMode is VPC. */
+ networkConfig: NetworkConfigSchema.optional(),
+ /** Instrumentation settings for observability. Defaults to OTel enabled. */
+ instrumentation: InstrumentationSchema.optional(),
+ /** Model provider used by this agent. Optional for backwards compatibility. */
+ modelProvider: ModelProviderSchema.optional(),
+ })
+ .superRefine((data, ctx) => {
+ if (data.networkMode === 'VPC' && !data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is required when networkMode is VPC',
+ });
+ }
+ if (data.networkMode !== 'VPC' && data.networkConfig) {
+ ctx.addIssue({
+ code: 'custom',
+ path: ['networkConfig'],
+ message: 'networkConfig is only allowed when networkMode is VPC',
+ });
+ }
+ });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;