refactor(templates): simplify create flow, create flags, and runtime templates. by Hweinstock · Pull Request #2214 · aws/agentcore-cli

Hweinstock · 2026-09-04T01:06:52Z

Problem

We want to simplify the templates!

Solution

the memory option is removed, including the flag on the public facing interface on both the runtime add and create flows. All templates that support it, come with longAndShortTerm memory pre-configured.
only the agent-python-strands supports custom model providers, api keys, and container builds.
the memory prompt in the TUI create flow is removed for all agent scaffolding flows.
the assets no longer render memory, container files, or other configurations via handlebars, and instead have it hard coded for memory, and removed for others.
the typescript template is simplified to not accept any templates (no memory, or api-key). Or any of the existing ones like file mounts or others.
the language, protocol, build flags are removed.
empty template is now supported.
harness is only scaffolded on create when only the name flag is present, and only the default harness is available.

Verification

Help text:

$ agentcore project create --help
Usage: agentcore project create [options]

create a new AgentCore project

Options:
  --name <name>                      name of the project to create
  --template <template>              the template to scaffold the Runtime from; some templates also accept --model-provider/--api-key
  --model-provider <model-provider>  model provider for templates that support it: bedrock, anthropic, open_ai, gemini, or lite_llm
  --api-key <api-key>                API key for non-Bedrock providers: '-' for stdin, 'file://path' for file
  --skip-install                     skip installing dependencies (npm install, uv sync) (default: false)
  --skip-git                         skip initializing a git repository (default: false)
  -h, --help                         display help for command
  
$ agentcore project add runtime --help
Usage: agentcore project add runtime [options]

add a Runtime to the current project

Options:
  --name <name>                                             the name of the Runtime
  --description <description>                               an optional description of the Runtime
  --type <type>                                             create scaffolds new agent code (the default); import translates a Bedrock Agent version
  --agent-id <agent-id>                                     Bedrock Agent ID to import (requires --type import)
  --agent-alias-id <agent-alias-id>                         Bedrock Agent Alias ID selecting the version to import; must point at a prepared version, not DRAFT (requires --type import)
  --template <template>                                     a preset of flags for scaffolding the Runtime; compatible flags override preset values
  --framework <framework>                                   agent framework for an imported Bedrock Agent: strands or langgraph (requires --type import)
  --model-provider <model-provider>                         model provider for the scaffolded Runtime code (Bedrock, Anthropic, OpenAI, or Gemini)
  --api-key <api-key>                                       API key for non-Bedrock providers: '-' for stdin, 'file://path' for file
  --role-arn <role-arn>                                     IAM role ARN that provides permissions for the Runtime
  --additional-policies <additional-policies...>            additional IAM policy ARNs or policy document paths for the execution role
  --network-mode <network-mode>                             network mode for the Runtime environment (PUBLIC or VPC)
  --network-config <network-config>                         VPC network configuration (JSON)
  --authorizer-type <authorizer-type>                       inbound authorizer type (AWS_IAM or CUSTOM_JWT)
  --authorizer-configuration <authorizer-configuration>     inbound authorizer configuration (JSON)
  --request-header-allowlist <request-header-allowlist...>  request headers to pass through to the Runtime
  --lifecycle-configuration <lifecycle-configuration>       lifecycle configuration (JSON)
  --environment-variables <environment-variables>           environment variables (JSON object of key/value strings)
  --filesystem-configurations <filesystem-configurations>   filesystem mount configurations (JSON)
  --tags <tags...>                                          tags as key=value (repeatable) or JSON object
  -h, --help                                                display help for command

TUI Create Flow

create-flow.mov

Templates E2E verification

Simple happy case

$ agentcore project create --template empty --name Empty
$ cd Empty
$ ls app/

$ agentcore project add runtime --name alice --template agent-python-strands
..
$ agentcore project dev --mode headless &
...
$ curl -X POST localhost:8087/invocations -d '{ "prompt": "what is your name" }'
alice] {"timestamp": "2026-09-03T23:46:08.745Z", "level": "INFO", "message": "Returning streaming response (generator) (0.000s)", "logger": "bedrock_agentcore.app", "requestId": "d4dd5116-30c0-46fa-9ee7-1f426641b6e4"}
[alice] INFO:     127.0.0.1:44792 - "POST /invocations HTTP/1.1" 200 OK
[alice] {"timestamp": "2026-09-03T23:46:08.779Z", "level": "INFO", "message": "Invoking Agent.....", "logger": "bedrock_agentcore.app", "requestId": "d4dd5116-30c0-46fa-9ee7-1f426641b6e4"}
data: {"event": {"messageStart": {"role": "assistant"}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": "I'm Claude, an AI assistant made"}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": " by Anthropic. How"}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": " can I help you today?"}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockStop": {"contentBlockIndex": 0}}}

data: {"event": {"messageStop": {"stopReason": "end_turn"}}}

data: {"event": {"metadata": {"usage": {"inputTokens": 600, "outputTokens": 23, "totalTokens": 623}, "metrics": {"latencyMs": 1553}}}}
$ agentcore project deploy 

$ agentcore project invoke runtime --name alice --payload '{ "prompt": "hello-world" }'. 
data: {"event": {"messageStart": {"role": "assistant"}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": "Hello! "}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": "👋 How"}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": " can I help you today?"}, "contentBlockIndex": 0}}}

data: {"event": {"contentBlockStop": {"contentBlockIndex": 0}}}

data: {"event": {"messageStop": {"stopReason": "end_turn"}}}

data: {"event": {"metadata": {"usage": {"inputTokens": 598, "outputTokens": 16, "totalTokens": 614}, "metrics": {"latencyMs": 1678}}}}

status=200 content-type=text/event-stream; charset=utf-8 runtime-session-id=b21f5166-93f3-42c9-aabc-ac9ac1963cfc mcp-session-id=- mcp-protocol-version=- trace-id=- trace-parent=- trace-state=- baggage=- complete=true bytes=625

Default to harness on create:

$ agentcore project create --name myProject
✓ Creating project tree
✓ Reading project spec file at '[..]'
✓ Scaffolding harness in project
✓ Updating project spec file at '[..]'
✓ Installing CDK dependencies with npm
✓ Initializing git repository
Created project 'myProject' in ./myProject
To deploy it: cd myProject && agentcore project deploy

had agents test the following:

create flow with each template into dev, curl, then deploy and invoke.
create a strands python agent with gemini and verify the same flow.
validate that memory is always scaffolded in each template that supports it.

Notes

I still think import bedrock agents adds some complexity to the add command, that might be better served by a separate command, but this could be a future pr.

…flags

…zard

…ner only for strands, trim agui

…Importer

…comments

agentcore-devx-automation · 2026-09-04T01:09:22Z

Claude Security Review: no high-confidence findings. (run)

codecov-commenter · 2026-09-04T01:10:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.04%. Comparing base (d041f01) to head (805b89c).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2214      +/-   ##
============================================
- Coverage     97.07%   97.04%   -0.04%     
============================================
  Files           544      544              
  Lines         37865    37535     -330     
============================================
- Hits          36759    36427     -332     
- Misses         1106     1108       +2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

agentcore-devx-automation

AgentCore Harness Review

Verdict: Looks good

Nice cleanup — the surface reduction reads clearly and the tests mostly stayed off mocks (real temp dirs + spy on create rather than a mocked manager, which is the right shape).

Only minor things I noticed; none block merge:

src/handlers/project/add/runtime/index.ts (~L140-L169): source.resolveSecret("api-key", flags["api-key"]) runs before the !isImport && !isTemplate && modelFlagsPresent validation. If a user invokes project add runtime --name foo --api-key - (or file://…) without a template, stdin/file is consumed before the error surfaces. Cheap fix is to move that validation block above the resolveSecret call so we reject before touching secret input. Same nit applies to --model-provider on the create handler in that no-op sense, though there the side effect is nil.
Purely FYI (not a bug): agent-python-strands-container reuses runtimeName: "agent_python_strands". If someone eventually calls add runtime --template agent-python-strands-container inside a project that already has agent-python-strands, they'll collide on the codeLocation. Pre-existing shape, worth keeping in mind if you get user reports.
PR title is still wip: …; presumably drop before merge.

Everything else — the template asset trims, the shortcut table, the wizard flow, the README, and the schema-driven validation — hangs together well.

…uards

agentcore-devx-automation · 2026-09-04T01:27:51Z

Claude Security Review: no high-confidence findings. (run)

tejaskash · 2026-09-04T01:44:43Z

+        createInput = { ...base };
+      } else {
+        const source = new SourceResolver({ stdin: config.io.stdin });
+        const apiKey = await source.resolveSecret("api-key", apiKeyFlag);


resolveSecret runs before resolveRuntimeTemplateShortcut checks supportsModelProviderOverride, so --api-key - on an unsupported template blocks on stdin and consumes the secret before failing with the template error.

Yeah I was trying to centralize this in the resolution, but I see how it creates a worse UX, lemme pop it out into the handlers.

tejaskash · 2026-09-04T01:44:43Z

+      }

      const source = new SourceResolver({ stdin: config.io.stdin });
      const apiKey = await source.resolveSecret("api-key", flags["api-key"]);


Same ordering as create: the secret is read before the template's supportsModelProviderOverride check, so --api-key -/file:// errors surface before the "not valid with this template" error.

tejaskash · 2026-09-04T01:44:43Z

 | --- | --- | --- |
-{{#if identityProviders.[0]}}| `{{identityProviders.[0].envVarName}}` | Yes | {{modelProvider}} API key (local) or Identity provider name (deployed) |
-{{/if}}| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |
+| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |


Nit: LOCAL_DEV is no longer read anywhere in this template (its only consumer was the removed Anthropic/OpenAI/Gemini branch in model/load.ts), so this row can go.

good catch!

…-key secret

agentcore-devx-automation · 2026-09-04T02:32:00Z

Claude Security Review: no high-confidence findings. (run)

agentcore-devx-automation · 2026-09-04T02:36:53Z

Claude Security Review: no high-confidence findings. (run)

Hweinstock · 2026-09-04T03:01:29Z

Added back memory to AGUI and verified e2e by deploying, invoking, and verifying a memory was in the stack.

AlexanderRichey · 2026-09-04T03:30:53Z

-        if not api_key:
-            raise RuntimeError(
-                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
-            )


https://i.programmerhumor.io/2025/08/c654b6c78f6c13122e359d9f763e20666b2c9824d4781f3ca02c962f183cdcad.jpeg

Hweinstock · 2026-09-04T04:02:48Z

Merging since earlier comments were addressed and we have a single approval. Will address remaining comments as a follow-up.

Hweinstock added 10 commits September 3, 2026 23:41

refactor(project): simplify template shortcuts and reduce create/add …

bed8a7c

…flags

refactor(tui): remove memory step and trim template list in create wi…

d2eb28d

…zard

refactor(templates): rename minimal, hardcode memory/provider, contai…

9f7b7f4

…ner only for strands, trim agui

test(project): update tests for the simplified template surface

1a17469

docs: update README for the simplified create and add surface

c545c24

refactor(project): reword create help text and drop dead bedrockAgent…

a2f31d7

…Importer

test(project): cover agui-python-strands scaffolding

61389b6

feat(project): imported Bedrock agents ship longAndShortTerm memory

0f0e11c

refactor(project): generalize model-flag rejection messages and trim …

5310d7f

…comments

docs(project): simplify getDefaultMemorySpec comment

233c43b

github-actions Bot added the size/xl PR size: XL label Sep 4, 2026

agentcore-devx-automation Bot added claude-security-reviewing Claude Code /security-review in progress agentcore-harness-reviewing AgentCore Harness review in progress labels Sep 4, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Sep 4, 2026

agentcore-devx-automation Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label Sep 4, 2026

agentcore-devx-automation Bot reviewed Sep 4, 2026

View reviewed changes

Hweinstock added 3 commits September 4, 2026 01:23

refactor(templates): drop unreachable agent-python-minimal resolver g…

c90c2ad

…uards

fix(project): validate model flags before resolving the api-key secret

a512843

fix(templates): give the strands container template its own runtime name

a2697d3

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Sep 4, 2026

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

Hweinstock changed the title ~~wip: refactor(templates): simplify create flow, create flags, and runtime templates.~~ refactor(templates): simplify create flow, create flags, and runtime templates. Sep 4, 2026

Hweinstock marked this pull request as ready for review September 4, 2026 01:28

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Sep 4, 2026

tejaskash reviewed Sep 4, 2026

View reviewed changes

Hweinstock added 3 commits September 4, 2026 02:25

feat(templates): restore longAndShortTerm memory for agui-python-strands

e164d48

fix(project): reject unsupported model flags before resolving the api…

f212520

…-key secret

docs(templates): drop stale LOCAL_DEV env var from typescript README

91552b3

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Sep 4, 2026

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

refactor(project): inline runtimeTemplateSupportsModelProvider lookup

805b89c

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Sep 4, 2026

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 4, 2026

AlexanderRichey approved these changes Sep 4, 2026

View reviewed changes

Hweinstock merged commit da28031 into aws:refactor Sep 4, 2026
19 of 22 checks passed

Uh oh!

Conversation

Hweinstock commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Verification

Help text:

TUI Create Flow

Templates E2E verification

Notes

Uh oh!

agentcore-devx-automation Bot commented Sep 4, 2026

Uh oh!

codecov-commenter commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

agentcore-devx-automation Bot left a comment

Choose a reason for hiding this comment

AgentCore Harness Review

Uh oh!

agentcore-devx-automation Bot commented Sep 4, 2026

Uh oh!

tejaskash Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Hweinstock Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tejaskash Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

tejaskash Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Hweinstock Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

agentcore-devx-automation Bot commented Sep 4, 2026

Uh oh!

agentcore-devx-automation Bot commented Sep 4, 2026

Uh oh!

Hweinstock commented Sep 4, 2026

Uh oh!

AlexanderRichey Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Hweinstock Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Hweinstock commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Hweinstock commented Sep 4, 2026 •

edited

Loading

codecov-commenter commented Sep 4, 2026 •

edited

Loading

Hweinstock commented Sep 4, 2026 •

edited

Loading