feat: upgrade default Python runtime to PYTHON_3_14 (#837)

jesseturner21 · web-flow · commit b139c05072ee · 2026-04-15T12:03:12.000-04:00
* feat: upgrade default Python runtime to PYTHON_3_14

Add PYTHON_3_14 as a supported runtime version and make it the default
for new agents and MCP tools. Updates schema enums, defaults, UI options,
packaging fallbacks, import mappings, and tests.

Verified end-to-end: deployed a runtime with PYTHON_3_14 to AgentCore
and confirmed successful invocation.

* chore: revert JSON schema change (auto-generated at release)

The JSON schema file is auto-regenerated during the release workflow.
Direct changes are rejected by the schema-check CI job.

* fix: address review — missed defaults, types, tests, and docs

- Update packCodeZipSync fallback in packaging/index.ts
- Add PYTHON_3_14 to llm-compacted/mcp.ts PythonRuntime type
- Update hardcoded runtimeVersion in AgentPrimitive.tsx
- Add PYTHON_3_14 to agent-env schema test
- Update TUI harness fixture default
- Update docs examples and runtime version list

* refactor: consolidate DEFAULT_PYTHON_VERSION into schema/constants

Define DEFAULT_PYTHON_VERSION once in schema/constants.ts and re-export
from the three TUI screen files that previously defined their own copy.
Replace hardcoded 'PYTHON_3_14' fallbacks in packaging and AgentPrimitive
with the shared constant. Future runtime version bumps now require a
single-line change.

* fix: detect Python ABI tag and usable wheels errors in platform retry logic

When numpy lacks pre-built wheels for a specific manylinux platform on
CPython 3.14, uv reports "no wheels with a matching Python ABI tag" or
"has no usable wheels" instead of the platform-specific errors the retry
logic was matching. This caused the packager to hard-fail on the first
platform candidate instead of retrying with a newer manylinux version
that does have compatible wheels.
diff --git 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_13",
+      "runtimeVersion": "PYTHON_3_14",
       "networkMode": "PUBLIC",
       "protocol": "HTTP"
     }
@@ -166,7 +166,7 @@ on the next deployment.
   "build": "CodeZip",
   "entrypoint": "main.py",
   "codeLocation": "app/MyAgent/",
-  "runtimeVersion": "PYTHON_3_13",
+  "runtimeVersion": "PYTHON_3_14",
   "networkMode": "PUBLIC",
   "envVars": [{ "name": "MY_VAR", "value": "my-value" }],
   "instrumentation": {
@@ -201,6 +201,7 @@ on the next deployment.
 - `PYTHON_3_11`
 - `PYTHON_3_12`
 - `PYTHON_3_13`
+- `PYTHON_3_14`
 
 **Node.js:**
 
diff --git 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_13"
+  "runtimeVersion": "PYTHON_3_14"
 }
 ```
 
diff --git a/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap b/src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap
@@ -4010,7 +4010,7 @@ file maps to a JSON config file and includes validation constraints as comments.
 
 - **BuildType**: \`'CodeZip'\` | \`'Container'\`
 - **NetworkMode**: \`'PUBLIC'\`
-- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\`
+- **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\` | \`'PYTHON_3_14'\`
 - **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` | \`'EPISODIC'\`
 
 ### Build Types
diff --git a/src/assets/agents/AGENTS.md b/src/assets/agents/AGENTS.md
@@ -62,7 +62,7 @@ file maps to a JSON config file and includes validation constraints as comments.
 
 - **BuildType**: `'CodeZip'` | `'Container'`
 - **NetworkMode**: `'PUBLIC'`
-- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'`
+- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'`
 - **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'`
 
 ### Build Types
diff --git a/src/cli/commands/import/constants.ts b/src/cli/commands/import/constants.ts
@@ -51,4 +51,5 @@ export const RUNTIME_TYPE_MAP: Record<string, string> = {
   PYTHON_3_11: 'PYTHON_3_11',
   PYTHON_3_12: 'PYTHON_3_12',
   PYTHON_3_13: 'PYTHON_3_13',
+  PYTHON_3_14: 'PYTHON_3_14',
 };
diff --git a/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts b/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts
@@ -87,7 +87,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_13');
+    expect(result.runtimeVersion).toBe('PYTHON_3_14');
     expect(result.networkMode).toBe('PUBLIC');
     expect(result.protocol).toBe('HTTP');
   });
diff --git a/src/cli/primitives/AgentPrimitive.tsx b/src/cli/primitives/AgentPrimitive.tsx
@@ -12,7 +12,13 @@ import type {
   SDKFramework,
   TargetLanguage,
 } from '../../schema';
-import { AgentEnvSpecSchema, CREDENTIAL_PROVIDERS, LIFECYCLE_TIMEOUT_MAX, LIFECYCLE_TIMEOUT_MIN } from '../../schema';
+import {
+  AgentEnvSpecSchema,
+  CREDENTIAL_PROVIDERS,
+  DEFAULT_PYTHON_VERSION,
+  LIFECYCLE_TIMEOUT_MAX,
+  LIFECYCLE_TIMEOUT_MIN,
+} from '../../schema';
 import type { AddAgentOptions as CLIAddAgentOptions } from '../commands/add/types';
 import { validateAddAgentOptions } from '../commands/add/validate';
 import { parseAndNormalizeHeaders } from '../commands/shared/header-utils';
@@ -526,7 +532,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
       build: options.buildType,
       entrypoint: (options.entrypoint ?? 'main.py') as FilePath,
       codeLocation: codeLocation as DirectoryPath,
-      runtimeVersion: 'PYTHON_3_13',
+      runtimeVersion: DEFAULT_PYTHON_VERSION,
       protocol,
       networkMode,
       ...(networkMode === 'VPC' &&
diff --git a/src/cli/tui/screens/agent/types.ts b/src/cli/tui/screens/agent/types.ts
@@ -189,5 +189,5 @@ export const NETWORK_MODE_OPTIONS = [
   { id: 'VPC', title: 'VPC', description: 'Attach to your VPC' },
 ] as const;
 
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
+export { DEFAULT_PYTHON_VERSION } from '../../../../schema';
 export const DEFAULT_ENTRYPOINT = 'main.py';
diff --git a/src/cli/tui/screens/generate/defaults.ts b/src/cli/tui/screens/generate/defaults.ts
@@ -1,12 +1,11 @@
-import type { NetworkMode, PythonRuntime } from '../../../../schema';
+import type { NetworkMode } from '../../../../schema';
+
+export { DEFAULT_PYTHON_VERSION } from '../../../../schema';
 
 /**
  * Default configuration values for create command
  */
 
-/** Default Python runtime version for new agents */
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
-
 /** Default network mode for agent runtimes */
 export const DEFAULT_NETWORK_MODE: NetworkMode = 'PUBLIC';
 
diff --git a/src/cli/tui/screens/mcp/types.ts b/src/cli/tui/screens/mcp/types.ts
@@ -6,7 +6,6 @@ import type {
   GatewayPolicyEngineConfiguration,
   GatewayTargetType,
   NodeRuntime,
-  PythonRuntime,
   SchemaSource,
   ToolDefinition,
 } from '../../../../schema';
@@ -278,7 +277,8 @@ export const POLICY_ENGINE_MODE_OPTIONS = [
 ] as const;
 
 export const PYTHON_VERSION_OPTIONS = [
-  { id: 'PYTHON_3_13', title: 'Python 3.13', description: 'Latest' },
+  { id: 'PYTHON_3_14', title: 'Python 3.14', description: 'Latest' },
+  { id: 'PYTHON_3_13', title: 'Python 3.13', description: '' },
   { id: 'PYTHON_3_12', title: 'Python 3.12', description: '' },
   { id: 'PYTHON_3_11', title: 'Python 3.11', description: '' },
   { id: 'PYTHON_3_10', title: 'Python 3.10', description: '' },
@@ -294,6 +294,6 @@ export const NODE_VERSION_OPTIONS = [
 // Defaults
 // ─────────────────────────────────────────────────────────────────────────────
 
-export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_13';
+export { DEFAULT_PYTHON_VERSION } from '../../../../schema';
 export const DEFAULT_NODE_VERSION: NodeRuntime = 'NODE_20';
 export const DEFAULT_HANDLER = 'handler.lambda_handler';
diff --git a/src/lib/packaging/__tests__/python.test.ts b/src/lib/packaging/__tests__/python.test.ts
@@ -19,6 +19,10 @@ describe('extractPythonVersion', () => {
     expect(extractPythonVersion('PYTHON_3_13' as PythonRuntime)).toBe('3.13');
   });
 
+  it('extracts 3.14 from PYTHON_3_14', () => {
+    expect(extractPythonVersion('PYTHON_3_14' as PythonRuntime)).toBe('3.14');
+  });
+
   it('throws for unsupported runtime string', () => {
     expect(() => extractPythonVersion('RUBY_3_0' as PythonRuntime)).toThrow('Unsupported Python runtime');
   });
diff --git a/src/lib/packaging/__tests__/uv.test.ts b/src/lib/packaging/__tests__/uv.test.ts
@@ -57,6 +57,20 @@ describe('detectUnavailablePlatform', () => {
     expect(issue!.message).toContain('has no wheels');
   });
 
+  it('detects "no wheels with a matching Python ABI tag" message (e.g. cp314)', () => {
+    const out = 'numpy==2.4.4 has no wheels with a matching Python ABI tag (e.g., `cp314`)';
+    const issue = detectUnavailablePlatform(result(out));
+    expect(issue).not.toBeNull();
+    expect(issue!.message).toContain('cp314');
+  });
+
+  it('detects "has no usable wheels" message', () => {
+    const out = 'numpy>=1.10.4 has no usable wheels, we can conclude that numpy>=1.10.4 cannot be used.';
+    const issue = detectUnavailablePlatform(result(out));
+    expect(issue).not.toBeNull();
+    expect(issue!.message).toContain('usable wheels');
+  });
+
   it('returns null for successful output', () => {
     const out = 'Successfully installed package-1.0.0\nAll done!';
     expect(detectUnavailablePlatform({ code: 0, stdout: out, stderr: '', signal: null })).toBeNull();
diff --git a/src/lib/packaging/index.ts b/src/lib/packaging/index.ts
@@ -1,4 +1,5 @@
 import type { AgentCoreProjectSpec, AgentEnvSpec, RuntimeVersion } from '../../schema';
+import { DEFAULT_PYTHON_VERSION } from '../../schema';
 import { ContainerPackager } from './container';
 import { PackagingError } from './errors';
 import { isNodeRuntime, isPythonRuntime } from './helpers';
@@ -78,7 +79,7 @@ export async function packRuntime(spec: AgentEnvSpec, options?: PackageOptions):
  * Defaults to Python if no runtimeVersion is specified.
  */
 export function packCodeZipSync(config: CodeBundleConfig | AgentEnvSpec, options?: PackageOptions): ArtifactResult {
-  const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_13';
+  const runtimeVersion = config.runtimeVersion ?? DEFAULT_PYTHON_VERSION;
   const packager = getCodeZipPackager(runtimeVersion);
   return packager.packCodeZip(config as AgentEnvSpec, options);
 }
diff --git a/src/lib/packaging/python.ts b/src/lib/packaging/python.ts
@@ -1,4 +1,5 @@
 import type { AgentEnvSpec, PythonRuntime, RuntimeVersion } from '../../schema';
+import { DEFAULT_PYTHON_VERSION } from '../../schema';
 import { UV_INSTALL_HINT, getArtifactZipName } from '../constants';
 import { runSubprocessCapture, runSubprocessCaptureSync } from '../utils/subprocess';
 import { PackagingError } from './errors';
@@ -155,7 +156,7 @@ export class PythonCodeZipPackager implements RuntimePackager {
  */
 export class PythonCodeZipPackagerSync implements CodeZipPackager {
   packCodeZip(config: AgentEnvSpec, options: PackageOptions = {}): ArtifactResult {
-    const runtimeVersion = config.runtimeVersion ?? 'PYTHON_3_13';
+    const runtimeVersion = config.runtimeVersion ?? DEFAULT_PYTHON_VERSION;
 
     if (!isPythonRuntimeVersion(runtimeVersion)) {
       throw new PackagingError(`Python packager only supports Python runtimes. Received: ${runtimeVersion}`);
diff --git a/src/lib/packaging/uv.ts b/src/lib/packaging/uv.ts
@@ -7,7 +7,8 @@ export interface PlatformIssue {
 
 const PLATFORM_HINT_REGEX = /platforms:\s*([^\n]+)/i;
 const MANYLINUX_TOKEN = /(manylinux[^\s,]+)/gi;
-const NO_WHEELS_REGEX = /(has no wheels with a matching platform tag|no compatible (?:wheels|tags) found)/i;
+const NO_WHEELS_REGEX =
+  /(has no wheels with a matching (?:platform|Python ABI) tag|no compatible (?:wheels|tags) found|has no usable wheels)/i;
 
 export function detectUnavailablePlatform(result: SubprocessResult): PlatformIssue | null {
   const combined = `${result.stdout}\n${result.stderr}`;
diff --git a/src/schema/__tests__/constants.test.ts b/src/schema/__tests__/constants.test.ts
@@ -60,13 +60,13 @@ describe('ModelProviderSchema', () => {
 });
 
 describe('PythonRuntimeSchema', () => {
-  it.each(['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13'])('accepts "%s"', version => {
+  it.each(['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13', 'PYTHON_3_14'])('accepts "%s"', version => {
     expect(PythonRuntimeSchema.safeParse(version).success).toBe(true);
   });
 
   it('rejects unsupported versions', () => {
     expect(PythonRuntimeSchema.safeParse('PYTHON_3_9').success).toBe(false);
-    expect(PythonRuntimeSchema.safeParse('PYTHON_3_14').success).toBe(false);
+    expect(PythonRuntimeSchema.safeParse('PYTHON_3_15').success).toBe(false);
   });
 });
 
diff --git a/src/schema/constants.ts b/src/schema/constants.ts
@@ -137,9 +137,12 @@ export function isReservedProjectName(name: string): boolean {
 // Infrastructure Constants (shared between agent-env and mcp schemas)
 // ============================================================================
 
-export const PythonRuntimeSchema = z.enum(['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13']);
+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<typeof PythonRuntimeSchema>;
 
+/** Default Python runtime version for new agents and MCP tools */
+export const DEFAULT_PYTHON_VERSION: PythonRuntime = 'PYTHON_3_14';
+
 export const NodeRuntimeSchema = z.enum(['NODE_18', 'NODE_20', 'NODE_22']);
 export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 
diff --git a/src/schema/llm-compacted/agentcore.ts b/src/schema/llm-compacted/agentcore.ts
@@ -25,7 +25,7 @@ interface AgentCoreProjectSpec {
 // ─────────────────────────────────────────────────────────────────────────────
 
 type BuildType = 'CodeZip' | 'Container';
-type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
+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;
 type NetworkMode = 'PUBLIC' | 'VPC';
diff --git a/src/schema/llm-compacted/mcp.ts b/src/schema/llm-compacted/mcp.ts
@@ -177,6 +177,6 @@ interface IamPolicyDocument {
 // ─────────────────────────────────────────────────────────────────────────────
 
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel' | 'apiGateway' | 'lambdaFunctionArn';
-type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
+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';
diff --git a/src/schema/schemas/__tests__/agent-env.test.ts b/src/schema/schemas/__tests__/agent-env.test.ts
@@ -209,7 +209,7 @@ describe('AgentEnvSpecSchema', () => {
   });
 
   it('accepts agent with all Python runtime versions', () => {
-    for (const version of ['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13']) {
+    for (const version of ['PYTHON_3_10', 'PYTHON_3_11', 'PYTHON_3_12', 'PYTHON_3_13', 'PYTHON_3_14']) {
       const result = AgentEnvSpecSchema.safeParse({ ...validPythonAgent, runtimeVersion: version });
       expect(result.success, `Should accept ${version}`).toBe(true);
     }
diff --git a/src/tui-harness/helpers.ts b/src/tui-harness/helpers.ts
@@ -5,6 +5,7 @@
  * AgentCore CLI recognizes as valid projects, without the overhead of
  * running the full create wizard or npm/uv installs.
  */
+import { DEFAULT_PYTHON_VERSION } from '../schema';
 import { mkdir, mkdtemp, rm, writeFile } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
@@ -103,7 +104,7 @@ export async function createMinimalProjectDir(
       build: 'CodeZip',
       entrypoint: 'main.py:handler',
       codeLocation: 'app/TestAgent',
-      runtimeVersion: 'PYTHON_3_13',
+      runtimeVersion: DEFAULT_PYTHON_VERSION,
     });
 
     // Create the agent code directory so the CLI does not complain.

Original file line number	Diff line number	Diff line change
@@ -58,7 +58,7 @@ In `agentcore.json`, set `"build": "Container"`:
`58`	`58`	`"build": "Container",`
`59`	`59`	`"entrypoint": "main.py",`
`60`	`60`	`"codeLocation": "app/MyAgent/",`
`61`		`- "runtimeVersion": "PYTHON_3_13"`
	`61`	`+ "runtimeVersion": "PYTHON_3_14"`
`62`	`62`	`}`
`63`	`63`	```
`64`	`64`