feat(project): scaffold add runtime handler by Hweinstock · Pull Request #2035 · aws/agentcore-cli

Hweinstock · 2026-08-19T01:51:35Z

Problem

add runtime is missing.

Solution

add support for project add runtime mostly mirroring the schema shapes.
support two modes template and byo (import OOS here). We then use this input schema to scaffold the project, and resolve the config that goes into agentcore.json (to be implemented).
new template flag describes templates like strands-python, which can be adjusted with flags (ex. --build Container, or --protocol mcp, with defaults for each template. This will keep us flexible to support more templates in the future.

Testing

added unit tests for handler parsing, with implementation details to be filled in.

… in handler

codecov-commenter · 2026-08-19T01:54:08Z

Codecov Report

❌ Patch coverage is 99.64286% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.15%. Comparing base (63ed69c) to head (9811509).
⚠️ Report is 1 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/handlers/project/add/runtime/index.ts	99.52%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2035      +/-   ##
============================================
+ Coverage     97.11%   97.15%   +0.04%     
============================================
  Files           384      386       +2     
  Lines         22711    22984     +273     
============================================
+ Hits          22055    22330     +275     
+ Misses          656      654       -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.

nborges-aws · 2026-08-21T14:44:48Z

+      flag("entrypoint", "entrypoint file, e.g. main.py:handler (BYO only)", z.string().optional()),
+      flag("protocol", "server protocol: HTTP, MCP, A2A, AGUI", ProtocolModeSchema.optional()),
+      flag(
+        "api-key",


We should mark this as sensitive

nborges-aws · 2026-08-21T14:50:35Z

+          `--${templateOnlyFlags[0]} is only available on the template path (--template)`,
+        );
+
+      const inputEnvironmentVariables = parseJsonFlag<Record<string, string>>(


Might be worth changing this to parseJsonFlagWithSchema, and passing in z.record(EnvVarNameSchema, z.string()). That way we aren't accepting null, 0, etc. into env vars

I believe this should get validated on line 209 below, since we borrow the env var shape from the existing schema.

nborges-aws · 2026-08-21T14:56:43Z

+]);
+export type RuntimeMemoryConfig = z.input<typeof runtimeMemoryConfigSchema>;
+
+const RuntimeInfraConfigSchema = z.object({


qq: I see ProjectRuntimeSchema has a bunch of superRefines validating/invalidating flags that need to be used in combination (etc. ensures VPC always has a network config). Is that something we'll account for in the implementation PR or do we need those here?

we should still surface these errors to the customer since we validate the schema before write, but this made me realize a small bug where this wouldn't rollback the scaffolded files. Fixing that here.

Nice catch on the rollback. With that fix I have no concerns about the validation happening later in the chain

notgitika · 2026-08-21T19:03:01Z

+  RuntimeResourceConfigSchema,
+} from "./types";
+
+export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>


OOS but a suggestion that we should try to adopt across the board. Can we divide flags into "basic" and "advanced" so that it is decluttered for the user to see when they type in agentcore project add runtime --help

here is how vercel does it:

I like this idea

this is interesting!

notgitika · 2026-08-21T19:18:07Z

+        tags: parseTags(flags["tags"]),
+      };
+
+      const runtimeInput = isTemplate


it looks like --build is accepted for templates but never added to runtimeInput, and the template schema strips it as well.

This means --build Container is silently ignored. Could we include build in the template config?

yeah good catch. I was initially thinking build would go in here, but the existing asset templates don't actually leverage it and instead have separate templates for build.

I'm working on the template doc now, so this behavior will likely change. I'm making a note to come back to this when we implement the handler to make sure its consistent.

jariy17

Its good, the nits could be a follow up pr.

jariy17 · 2026-08-21T19:31:06Z

+  RuntimeResourceConfigSchema,
+} from "./types";
+
+export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>


I like this idea

jariy17 · 2026-08-21T19:35:01Z

+      const entrypoint = flags.entrypoint ?? "main.py";
+
+      const source = new SourceResolver({ stdin: config.io.stdin });
+      const apiKey = await source.resolveText("api-key", flags["api-key"]);


After looking at Tejas's PR, we shouldn't allow inline secrets. I asked Tejas to shift this helper functino into SourceResolver.

It looks like there is some inconsistency here since runtime does allow this:

agentcore-cli/src/handlers/runtime/invoke/request.ts

Line 46 in d7f3fd4

const bearerToken = await resolver.resolveText("bearer-token", sources.bearerToken);

.

I'm going to merge to avoid conflicts, and make a follow-up task to align on consistent behavior here.

Hweinstock added 11 commits August 17, 2026 21:10

feat(proj): add handler scaffolding for runtime

b13c8a0

refactor(runtime): simplify add runtime to leverage a template setup

f9714a4

chore(runtime): undo entrypoint schema change, punt to follow-up

360dda2

refactor(runtime): clean up handler flags

559facf

feat(runtime): default to hello world python

a51a3a6

fix(runtime): remove dead space

4adff64

feat(runtime): bring parity with old command

f97e512

fix(runtime): default runtime to hello world template

0ad1145

fix(runtime): strongly type protocol

ef9de8d

refactor: add-runtime flags mirror spec schema, remove toX mappers

9316bd8

refactor: define RuntimeResourceConfigSchema, validate with safeParse…

4cc3fe2

… in handler

github-actions Bot added the agentcore-harness-reviewing AgentCore Harness review in progress label Aug 19, 2026

github-actions Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label Aug 19, 2026

refactor(runtime): move runtime specific types to their own file

473c989

Hweinstock force-pushed the refactor-add-runtime branch from 4423362 to 473c989 Compare August 19, 2026 15:18

Hweinstock changed the title ~~feat(project): scaffold add runtime handler (2)~~ feat(project): scaffold add runtime handler Aug 19, 2026

Hweinstock marked this pull request as ready for review August 19, 2026 18:50

refactor(tags): swap tags to shared shape

e3ea407

Hweinstock mentioned this pull request Aug 19, 2026

feat(project): scaffold add runtime handler #2018

Closed

Hweinstock added 2 commits August 19, 2026 23:00

chore: merge in mainline

a065be5

chore: merge in refactor-main

80486a4

nborges-aws reviewed Aug 21, 2026

View reviewed changes

Hweinstock added 2 commits August 21, 2026 15:43

fix(runtime): mark api-key as sensitive

7c0a301

fix(add): ensure failed schema writes cause scaffold rollback

9811509

nborges-aws approved these changes Aug 21, 2026

View reviewed changes

notgitika reviewed Aug 21, 2026

View reviewed changes

jariy17 approved these changes Aug 21, 2026

View reviewed changes

Hweinstock merged commit b566b33 into aws:refactor Aug 21, 2026
8 of 16 checks passed

Hweinstock deleted the refactor-add-runtime branch August 21, 2026 19:58

Uh oh!

Conversation

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

Uh oh!

Problem

Solution

Testing

Uh oh!

codecov-commenter commented Aug 19, 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!

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!

jariy17 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Hweinstock commented Aug 19, 2026 •

edited

Loading

codecov-commenter commented Aug 19, 2026 •

edited

Loading