diff --git a/docs/configuration.md b/docs/configuration.md index 6e42c101a..3b6f92a03 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -31,7 +31,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an "build": "CodeZip", "entrypoint": "main.py", "codeLocation": "app/MyAgent/", - "runtimeVersion": "PYTHON_3_14", + "runtimeVersion": "PYTHON_3_13", "networkMode": "PUBLIC", "protocol": "HTTP" } @@ -166,7 +166,7 @@ on the next deployment. "build": "CodeZip", "entrypoint": "main.py", "codeLocation": "app/MyAgent/", - "runtimeVersion": "PYTHON_3_14", + "runtimeVersion": "PYTHON_3_13", "networkMode": "PUBLIC", "envVars": [{ "name": "MY_VAR", "value": "my-value" }], "instrumentation": { @@ -201,8 +201,10 @@ on the next deployment. - `PYTHON_3_10` - `PYTHON_3_11` - `PYTHON_3_12` -- `PYTHON_3_13` -- `PYTHON_3_14` +- `PYTHON_3_13` (default) +- `PYTHON_3_14` — **opt-in only.** Currently supported by CloudFormation in `us-east-1` and `us-west-2`. In other + regions the deploy will fail with `AWS::EarlyValidation::PropertyValidation` and leave the stack stuck in + `REVIEW_IN_PROGRESS` (see [issue #907](https://github.com/aws/agentcore-cli/issues/907)). **Node.js:** diff --git a/docs/container-builds.md b/docs/container-builds.md index 61d65bcde..a75f5e7a9 100644 --- a/docs/container-builds.md +++ b/docs/container-builds.md @@ -58,7 +58,7 @@ In `agentcore.json`, set `"build": "Container"`: "build": "Container", "entrypoint": "main.py", "codeLocation": "app/MyAgent/", - "runtimeVersion": "PYTHON_3_14" + "runtimeVersion": "PYTHON_3_13" } ``` diff --git a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap index a97bbeb1d..a44f54503 100644 --- a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap +++ b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap @@ -5534,7 +5534,7 @@ file maps to a JSON config file and includes validation constraints as comments - **BuildType**: \`'CodeZip'\` | \`'Container'\` - **NetworkMode**: \`'PUBLIC'\` | \`'VPC'\` -- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` | \`'PYTHON_3_14'\` | \`'NODE_18'\` | \`'NODE_20'\` | \`'NODE_22'\` +- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` (default) | \`'PYTHON_3_14'\` (opt-in; only supported by CloudFormation in \`us-east-1\` and \`us-west-2\` — see [issue #907](https://github.com/aws/agentcore-cli/issues/907)) | \`'NODE_18'\` | \`'NODE_20'\` | \`'NODE_22'\` - **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` | \`'EPISODIC'\` - **GatewayTargetType**: \`'lambda'\` | \`'mcpServer'\` | \`'openApiSchema'\` | \`'smithyModel'\` | \`'apiGateway'\` | \`'lambdaFunctionArn'\` - **ModelProvider**: \`'Bedrock'\` | \`'Gemini'\` | \`'OpenAI'\` | \`'Anthropic'\` diff --git a/src/assets/agents/AGENTS.md b/src/assets/agents/AGENTS.md index 2153de014..96464b9b1 100644 --- a/src/assets/agents/AGENTS.md +++ b/src/assets/agents/AGENTS.md @@ -68,7 +68,7 @@ file maps to a JSON config file and includes validation constraints as comments - **BuildType**: `'CodeZip'` | `'Container'` - **NetworkMode**: `'PUBLIC'` | `'VPC'` -- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'` +- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` (default) | `'PYTHON_3_14'` (opt-in; only supported by CloudFormation in `us-east-1` and `us-west-2` — see [issue #907](https://github.com/aws/agentcore-cli/issues/907)) | `'NODE_18'` | `'NODE_20'` | `'NODE_22'` - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'` - **GatewayTargetType**: `'lambda'` | `'mcpServer'` | `'openApiSchema'` | `'smithyModel'` | `'apiGateway'` | `'lambdaFunctionArn'` - **ModelProvider**: `'Bedrock'` | `'Gemini'` | `'OpenAI'` | `'Anthropic'` diff --git a/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts b/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts index d30ae23fc..35bfa7ada 100644 --- a/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts +++ b/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts @@ -1,3 +1,4 @@ +import { DEFAULT_PYTHON_VERSION } from '../../../../../schema/constants.js'; import { computeManagedOAuthCredentialName } from '../../../../primitives/credential-utils.js'; import { mapByoConfigToAgent } from '../../../../tui/screens/agent/useAddAgent.js'; import type { GenerateConfig } from '../../../../tui/screens/generate/types.js'; @@ -87,7 +88,7 @@ describe('mapGenerateConfigToAgent', () => { expect(result.name).toBe('TestProject'); expect(result.build).toBe('CodeZip'); expect(result.entrypoint).toBe('main.py'); - expect(result.runtimeVersion).toBe('PYTHON_3_14'); + expect(result.runtimeVersion).toBe(DEFAULT_PYTHON_VERSION); expect(result.networkMode).toBe('PUBLIC'); expect(result.protocol).toBe('HTTP'); }); diff --git a/src/schema/__tests__/constants.test.ts b/src/schema/__tests__/constants.test.ts index 2d8bd3bc9..073385fb5 100644 --- a/src/schema/__tests__/constants.test.ts +++ b/src/schema/__tests__/constants.test.ts @@ -1,4 +1,5 @@ import { + DEFAULT_PYTHON_VERSION, ModelProviderSchema, NetworkModeSchema, NodeRuntimeSchema, @@ -72,6 +73,13 @@ describe('RuntimeVersionSchemas', () => { expect(NodeRuntimeSchema.safeParse('NODE_24').success).toBe(false); expect(RuntimeVersionSchema.safeParse('RUBY_3_0').success).toBe(false); }); + + // Regression test for issue #907: PYTHON_3_14 is not yet broadly supported + // by CloudFormation, so the CLI default must remain a server-side-supported + // version (PYTHON_3_13) to avoid stuck REVIEW_IN_PROGRESS stacks. + it('uses PYTHON_3_13 as the default Python runtime', () => { + expect(DEFAULT_PYTHON_VERSION).toBe('PYTHON_3_13'); + }); }); describe('NetworkModeSchema', () => { diff --git a/src/schema/constants.ts b/src/schema/constants.ts index d235a0df1..bbe7ae670 100644 --- a/src/schema/constants.ts +++ b/src/schema/constants.ts @@ -143,11 +143,21 @@ export function isReservedProjectName(name: string): boolean { // Infrastructure Constants (shared between agent-env and mcp schemas) // ============================================================================ +/** + * Supported Python runtime versions. + * + * NOTE: `PYTHON_3_14` is accepted by the schema but is currently only + * supported by CloudFormation in `us-east-1` and `us-west-2`. In other + * regions, deploys with `PYTHON_3_14` fail with + * `AWS::EarlyValidation::PropertyValidation` and leave the stack stuck + * in `REVIEW_IN_PROGRESS` (see issue #907). The default is therefore + * `PYTHON_3_13` until `PYTHON_3_14` is broadly supported. + */ export const PythonRuntimeSchema = z.enum(['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13', 'PYTHON_3_14']); export type PythonRuntime = z.infer; /** Default Python runtime version for new agents and MCP tools */ -export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_14'; +export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13'; export const NodeRuntimeSchema = z.enum(['NODE_18', 'NODE_20', 'NODE_22']); export type NodeRuntime = z.infer; diff --git a/src/schema/llm-compacted/agentcore.ts b/src/schema/llm-compacted/agentcore.ts index c86c14cb7..ef64fe1ca 100644 --- a/src/schema/llm-compacted/agentcore.ts +++ b/src/schema/llm-compacted/agentcore.ts @@ -35,6 +35,8 @@ interface AgentCoreProjectSpec { // ───────────────────────────────────────────────────────────────────────────── type BuildType = 'CodeZip' | 'Container'; +// PYTHON_3_14 is opt-in only; CloudFormation currently supports it in us-east-1 +// and us-west-2. See docs/configuration.md#runtime-versions and issue #907. type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13' | 'PYTHON_3_14'; type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22'; type RuntimeVersion = PythonRuntime | NodeRuntime; @@ -68,7 +70,7 @@ interface AgentEnvSpec { entrypoint: string; // @regex ^[a-zA-Z0-9_][a-zA-Z0-9_/.-]*\.(py|ts|js)(:[a-zA-Z_][a-zA-Z0-9_]*)?$ e.g. "main.py:handler" or "index.ts" codeLocation: string; // Directory path dockerfile?: string; // Custom Dockerfile name for Container builds (default: 'Dockerfile'). Must be a filename, not a path. - runtimeVersion?: RuntimeVersion; + runtimeVersion?: RuntimeVersion; // default 'PYTHON_3_13' envVars?: EnvVar[]; networkMode?: NetworkMode; // default 'PUBLIC' networkConfig?: NetworkConfig; // Required when networkMode is 'VPC' diff --git a/src/schema/llm-compacted/mcp.ts b/src/schema/llm-compacted/mcp.ts index 9e1e8d8a2..d393a3c24 100644 --- a/src/schema/llm-compacted/mcp.ts +++ b/src/schema/llm-compacted/mcp.ts @@ -177,6 +177,8 @@ interface IamPolicyDocument { // ───────────────────────────────────────────────────────────────────────────── type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel' | 'apiGateway' | 'lambdaFunctionArn'; +// PYTHON_3_14 is opt-in only; CloudFormation currently supports it in us-east-1 +// and us-west-2. See docs/configuration.md#runtime-versions and issue #907. type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13' | 'PYTHON_3_14'; type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22'; type NetworkMode = 'PUBLIC' | 'VPC';