Skip to content

fix(#907): default Python runtime to PYTHON_3_13 to avoid CloudFormation rejection of PYTHON_3_14 #1165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
aidandaly24 wants to merge 4 commits into from
Closed

fix(#907): default Python runtime to PYTHON_3_13 to avoid CloudFormation rejection of PYTHON_3_14 #1165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7004025
fix: fix issue #907
May 7, 2026
9e2b90c
fix: address review findings round 1
May 7, 2026
75ac010
fix: address reviewer feedback
May 7, 2026
b232579
fix: address reviewer feedback
May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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)).

@agentcore-cli-automation agentcore-cli-automation May 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The caveat added here is great, but the same RuntimeVersion enum list in src/assets/agents/AGENTS.md:71 is unchanged:

- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'`

That file is shipped as part of every scaffolded agent project (via src/assets/agents/), so anyone who reads AGENTS.md in a new project and hand-edits agentcore.json will still pick PYTHON_3_14 thinking it's a supported option. A couple of options for the fix:

  1. Minimal: mark PYTHON_3_13 as the default and add a short (opt-in only; see docs/configuration.md) note next to PYTHON_3_14 in that line, mirroring what you've done here.
  2. Hoist the caveat: expand the enum line into a short bullet list (like the one in docs/configuration.md:199-207) so the regional limitation is visible in-line.
  3. Link out: keep the enum line compact and add a one-line note below it pointing to docs/configuration.md#runtime-versions for the PYTHON_3_14 caveat.

Also remember to regenerate src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap (line 5429 / 5537) once AGENTS.md is updated — npm run test:update-snapshots per the PR template.


**Node.js:**

Expand Down
2 changes: 1 addition & 1 deletion docs/container-builds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
```

Expand Down
2 changes: 1 addition & 1 deletion src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'\`
Expand Down
2 changes: 1 addition & 1 deletion src/assets/agents/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'`
Expand Down
3 changes: 2 additions & 1 deletion src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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');
});
Expand Down
8 changes: 8 additions & 0 deletions src/schema/__tests__/constants.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import {
DEFAULT_PYTHON_VERSION,
ModelProviderSchema,
NetworkModeSchema,
NodeRuntimeSchema,
Expand Down Expand Up @@ -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', () => {
Expand Down
12 changes: 11 additions & 1 deletion src/schema/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof PythonRuntimeSchema>;

/** 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<typeof NodeRuntimeSchema>;
Expand Down
4 changes: 3 additions & 1 deletion src/schema/llm-compacted/agentcore.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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'
Expand Down
2 changes: 2 additions & 0 deletions src/schema/llm-compacted/mcp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Loading