refactor: align templates with old cli definition by Hweinstock · Pull Request #2094 · aws/agentcore-cli

Hweinstock · 2026-08-24T21:16:16Z

Problem

The new CLI has a new definition of templates that is not fully flushed out and diverges from the old CLI. We want to get e2e functionality first, before rethinking this.

Solution

Templates now again refer to the asset rendering, and the flag for templates refers to flag presets.
remove byo support to simplify runtime handler for initial version.
bring parity to create flags to what was discussed in (basically what was in the old cli).
adjust runtime flags to match the create flags.
make minimal backend changes to support new interface.

Future Work

Want to refactor the templates to split up template parameters from template identifiers (i.e. what determines the base vs rendered in with handlebars. )

Testing

added unit tests that exercise the command e2e.

codecov-commenter · 2026-08-24T21:19:23Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.42%. Comparing base (1593e2d) to head (e295d4e).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2094   +/-   ##
=========================================
  Coverage     97.41%   97.42%           
=========================================
  Files           428      428           
  Lines         26096    26124   +28     
=========================================
+ Hits          25422    25450   +28     
  Misses          674      674

☔ 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.

Hweinstock · 2026-08-24T21:41:56Z

  },
 };

+function buildRuntimeTemplateKey(input: ScaffoldRuntimeInput): string {


i plan to refactor this in a future PR. We're going to want some of these parameters to determine the asset templates to render from, and some of them to be rendered into it with handlebars. However, this felt like the smallest change I could make to keep it functional with the new interface.

This PR is intended to focus on aligning the handlers with what we want, then we work backwards from there to implement the functionality we need to support it.

What makes this complexity necessary at this stage? Do we expect more than a handful of templates?

agentcore-devx-automation · 2026-08-25T17:46:46Z

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

notgitika

still reviewing the manager and templates files in a couple mins

notgitika · 2026-08-25T18:56:51Z


+/** Set of flags needed to scaffold a new Runtime-based agent **/
+export const ScaffoldRuntimeInputSchema = z.object({
+  runtimeName: z.string().min(1),


maybe not related to this PR but if we are only checking if it is a string, is "../MyAgent" a valid runtime name? it would scaffold cold into <cwd>/.. outside the project then right?

good question! my understanding is this case is handled for the runtime case in the schema itself, so when the write fails, the scaffolding rollback, but we don't have the same on the create command, so its currently possible to do this already.

runtime schema:

agentcore-cli/src/projectSchemas/runtime.ts

Lines 16 to 23 in e51a676

export const AgentNameSchema = z

.string()

.min(1, "Name is required")

.max(48)

.regex(

/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/,

"Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",

);

To allow us to fail earlier and fix the create case, we can validate the same regex we validate in the schema here.

notgitika · 2026-08-25T18:59:17Z

+    await expect(
+      run([
+        "create",
+        "--name",
+        "MyAgent",
+        "--template",
+        "hello-world-python",
+        "--build",
+        "Container",
+      ]),
+    ).rejects.toThrow(/--template and --build are mutually exclusive/);
+  });
+


just wanted to confirm is our vision that we can probably add certain build time env vars into templates? so I can do like hello-world-python[no-memory]
or do we just reject that idea altogether?

my implementation here is based on the old CLI. my understanding from our conversation yesterday was that we want to mirror existing behavior, before adding new functionality. Hopefully we get a chance to come back and make this more flexible.

sounds good, we can revisit this later

notgitika · 2026-08-25T19:01:26Z

+        "model provider for the scaffolded runtime code",
+        z.enum(["Bedrock"]).optional(),
+      ),
+      flag(


api-key is still not supported fully yet right? like it gets resolved but nothing reads it so it is dropped (assuming its since we only have bedrock for now)

yes exactly. I put it there so that its wired up in the handler once we're ready, but there is no way to provide it.

Let me add some validation to reject this if we pass bedrock to make this more explicit.

notgitika · 2026-08-25T19:03:28Z

+        "model-provider",
+        "api-key",
+        "memory",
+        "runtime-name",


wait so is runtime-name also mutually exclusive? I cant have "mydemoagent" as my runtime name with the template? seems like we are forcing the user too much here folks might want custom runtime name but the basic hello world scaffolding in it.

pulling it out of this list also gives you somewhere to hang the codeLocation fix.

yeah I think I agree we should allow this to be customized, but our templates are not flexible enough to support this yet. The follow-up #2099 refactors the templates to add this functionality which should allow us to allow overrides like this.

notgitika · 2026-08-25T19:05:37Z

    },
  });
+
+function parseScaffoldRuntimeInput(input: Record<string, unknown>) {


if i miss a flag, it would surface the raw Zod error.

for eg: create --name MyAgent --runtime-name foo prints
Invalid input: expected "none" → at framework

it points users to internal camelCase field paths rather than the --kebab flags they typed. can we check for the missing flags up front? or map it back to flag names

could be polished in follow up tbh

good catch. I think it might make sense to circle back here, because this definitely isn't the only case of ugly error messages and I think we should establish some consistent standards.

Wouldn't these kinds of errors get thrown before the handler itself runs? The framework should handle the validations of the given flags assuming they're populated.

Most of them yes, but I think the referenced message is coming from https://github.com/Hweinstock/agentcore-cli/blob/667fb0e60f750d4bed85ffb8c1fc790053375e69/src/handlers/project/create/index.ts#L117-L121 which happens after the flags are parsed and is part of a shared validation between this and the create handler for the scaffolding flags.

We could get rid of this if we share the flags themselves rather than a separate schema, but originally wanted to keep the flags explicit.

notgitika · 2026-08-25T19:10:53Z

notgitika · 2026-08-25T19:24:43Z

this is hardcoded but line 103 now writes the assets to app/${input.runtimeName}.

those are thes ame when runtimeName is hello-world, which is true for the presets but not for the custom flags path. I would say this is a blocker for this PR

Yeah this is a hack to get the same behavior. let me be consistent with the hardcoding and properly remove it in the follow-up.

agentcore-devx-automation · 2026-08-25T19:59:57Z

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

agentcore-devx-automation · 2026-08-25T20:09:01Z

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

agentcore-devx-automation · 2026-08-25T20:12:54Z

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

notgitika · 2026-08-25T21:19:47Z

+    memory: z.enum(["none"]),
+  })
+  .refine(({ modelProvider, apiKey }) => !(modelProvider === "Bedrock" && apiKey !== undefined), {
+    message: "API keys are not compatible with Bedrock model providers",


notgitika · 2026-08-25T21:21:07Z

        build: "CodeZip",
        entrypoint: "main.py",
-        codeLocation: "app/hello-world",
+        codeLocation: "app/hello_world",


😭 I forgot - is not supported in runtime

notgitika

looks great to me!

AlexanderRichey · 2026-08-26T00:13:37Z

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


Will this hang if the api-key param isn't passed? api-key is required only for non-Bedrock model providers, right?

I believe it handles the undefined case internally https://github.com/Hweinstock/agentcore-cli/blob/667fb0e60f750d4bed85ffb8c1fc790053375e69/src/io/source.ts#L62.

And yeah exactly, we only support bedrock atm so this is effectively a placeholder.

AlexanderRichey

Looks good. Left a couple questions that can be addressed in a follow up if necessary.

github-actions Bot added agentcore-harness-reviewing AgentCore Harness review in progress and removed agentcore-harness-reviewing AgentCore Harness review in progress labels Aug 24, 2026

Hweinstock force-pushed the refactor-templates branch 4 times, most recently from 4c16ba0 to 4a80a21 Compare August 24, 2026 22:32

Hweinstock commented Aug 24, 2026

View reviewed changes

Hweinstock marked this pull request as ready for review August 24, 2026 22:37

refactor: align templates with old cli definition

667fb0e

Hweinstock force-pushed the refactor-templates branch from 4a80a21 to 667fb0e Compare August 25, 2026 17:43

github-actions Bot added the size/l PR size: L label Aug 25, 2026

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

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

Hweinstock mentioned this pull request Aug 25, 2026

feat(templates): support rendering strands http template. #2099

Merged

notgitika reviewed Aug 25, 2026

View reviewed changes

notgitika requested changes Aug 25, 2026

View reviewed changes

Hweinstock added 3 commits August 25, 2026 19:44

fix(create): validate runtime name to avoid out of project scaffolding

66b85a5

fix(runtime): reject api key with bedrock model provider

457e397

fix(templates): hardcode the scaffolding dir in both places

978a20c

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Aug 25, 2026

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

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

fix(templates): swap to hello_world to avoid invalid runtime name

20911b3

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Aug 25, 2026

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

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

chore: merge in refactor main branch

e295d4e

github-actions Bot added size/l PR size: L and removed size/l PR size: L labels Aug 25, 2026

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

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

notgitika reviewed Aug 25, 2026

View reviewed changes

notgitika self-requested a review August 25, 2026 21:21

notgitika approved these changes Aug 25, 2026

View reviewed changes

AlexanderRichey reviewed Aug 26, 2026

View reviewed changes

AlexanderRichey approved these changes Aug 26, 2026

View reviewed changes

Hweinstock merged commit f1a651c into aws:refactor Aug 26, 2026
19 of 32 checks passed

Hweinstock deleted the refactor-templates branch August 26, 2026 01:20

	export const AgentNameSchema = z
	.string()
	.min(1, "Name is required")
	.max(48)
	.regex(
	/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/,
	"Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
	);

Uh oh!

Conversation

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

Uh oh!

Problem

Solution

Future Work

Testing

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agentcore-devx-automation Bot commented Aug 25, 2026

Uh oh!

notgitika left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agentcore-devx-automation Bot commented Aug 25, 2026

Uh oh!

agentcore-devx-automation Bot commented Aug 25, 2026

Uh oh!

agentcore-devx-automation Bot commented Aug 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notgitika left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexanderRichey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Hweinstock commented Aug 24, 2026 •

edited

Loading

codecov-commenter commented Aug 24, 2026 •

edited

Loading