[notgitika]

Summary

Proposes the high-level design for deploying an AgentCore Runtime from a pre-built private or public ECR image.

The design adds containerUri to each Runtime specification rather than using a deploy-time environment variable. This keeps synthesis deterministic and makes image selection unambiguous for projects with multiple Runtimes.

Deployment model

• build: "CodeZip" retains the existing bundled-code path.
• build: "Container" with containerUri deploys the existing image directly and skips source upload, managed ECR, CodeBuild, and the image-builder custom resource.
• build: "Container" without containerUri retains the existing Dockerfile and CodeBuild path.

The document covers configuration, validation, CLI preparation behavior, CDK resource branching, private/public ECR permissions, compatibility, testing, and delivery sequencing.

Related work

• Tracking issue: Support pre-built container image URI in agentcore deploy (skip CodeBuild) #503
• CLI implementation: feat(runtime): support pre-built ECR container images #2719
• CDK implementation: aws/agentcore-l3-cdk-constructs#440

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other

Testing

Documentation-only change; implementation verification is tracked in #2719 and aws/agentcore-l3-cdk-constructs#440.

Checklist

• I have read the CONTRIBUTING document
• The proposal includes a test plan
• The proposal documents compatibility and delivery sequencing

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Package Tarball

aws-agentcore-1.0.1.tgz

How to install

gh release download pr-2718-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-1.0.1.tgz

[agentcore-devx-automation]

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

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.54%. Comparing base (fe7a568) to head (e651243).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2718   +/-   ##
=========================================
  Coverage     96.54%   96.54%           
=========================================
  Files           706      707    +1     
  Lines         58561    58600   +39     
=========================================
+ Hits          56539    56578   +39     
  Misses         2022     2022           

☔ 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: Changes requested

Design-only PR against refactor, so this is design feedback rather than code review. The direction is right — making the image part of the Runtime spec instead of AGENTCORE_CONTAINER_URI is a better answer than what #503 proposed, and the branching/output contracts match what RuntimeEnvironment and AgentCoreRuntime actually do in @aws/agentcore-cdk 1.0.0 (I verified ecrRepositoryArn is required for Container builds is the current blocker). But several things the implementation will immediately collide with are either missing or specified in a way that will not work.

1. The same feature already ships for harness; the design should say it reuses it (docs/designs/prebuilt-runtime-container-images.md, "Validation and deployment preparation" / "CDK design")

Pre-built ECR images are already implemented end-to-end for the harness primitive, and the doc never mentions it:

• src/projectSchemas/harness.ts:19-21 — CONTAINER_URI_PATTERN (private 12-digit ECR incl. .cn, or public.ecr.aws) and MAX_CONTAINER_URI_LENGTH = 1024, mirroring the CFN ContainerConfiguration.ContainerUri constraint. The "Accept only supported private ECR and public.ecr.aws formats / enforce the service maximum URI length" bullets are already solved; this should be a shared constant, not a second regex.
• src/projectSchemas/harness.ts:550-555 — the containerUri / dockerfile mutual-exclusion refinement.
• src/projectSchemas/constants.ts:77-83 — isContainerBuild() already keys off containerUri.
• CDK side: AgentCoreHarnessEnvironment already branches on a pre-built URI and skips the builder, and AgentCoreHarnessRole already has isPublicEcrUri() / parsePrivateEcrUri() plus the exact repo-ARN-scoped pull statements this doc proposes to invent.
• CLI surface precedent: agentcore add harness --container-uri (src/handlers/project/add/harness/index.ts:219, documented in command.md:281).

Please state explicitly which of these are lifted/shared versus re-derived, and reconsider the "no flag in the initial implementation" stance — agentcore add runtime --container-uri mirrors the harness flag and is unambiguous for multi-Runtime projects, unlike a deploy-time override.

2. Suppressing Dockerfile inference is not enough — syncRuntimeBuild will write an invalid agentcore.json

src/core/project/runtimeBuild.ts:93-96 unconditionally fills in a default for any Container runtime without one:

} else if (runtime.build === "Container" && runtime.dockerfile === undefined) {
  next.dockerfile = DOCKERFILE_NAME;
  reasons.dockerfile = "default";
}

ProjectManager.syncRuntimeBuilds (src/core/project/manager.tsx:1511-1527) patches those changes into the raw file and re-parses with ProjectSpecSchema, throwing ProjectStateError on failure. So with the proposed containerUri↔dockerfile exclusion, the first agentcore dev/deploy on a pre-built-image runtime writes "dockerfile": "Dockerfile" and then fails its own validation. The doc only covers "not inferring a Dockerfile merely because one exists in the code directory." Options: skip both the inference and the default fill when containerUri is set; or drop dockerfile from the exclusion list and let containerUri win at synth (less safe, since it makes two conflicting sources legal).

Related: because isContainerBuild() returns true whenever containerUri is set, the CodeBuild five-security-group cap in ProjectRuntimeSchema.superRefine (src/projectSchemas/runtime.ts:347-358) will still fire for pre-built images. The "skip CodeBuild-only checks" bullet needs an explicit containerUri === undefined guard rather than relying on the shared helper (the harness schema has the same latent gap at harness.ts:578-590).

3. The codeLocation directory existence check isn't addressed

prepareRuntimes hard-fails before sync if the folder is missing (src/core/project/runtimeBuild.ts:528-534: runtime "x": app/x/ does not exist.). The doc says entrypoint/codeLocation stay required but "their local files are not build inputs" — that still leaves a user who only has an image URI unable to deploy without creating a stub directory (there's also no agentcore add runtime path that creates one without scaffolding code). Decide and document: keep requiring the folder, or skip the existence check (and the entrypoint re-derivation from pyproject.toml/package.json) when containerUri is set.

4. agentcore dev (and agentcore build) behavior is unspecified

prepareRuntimes is shared by dev and deploy (purpose: "dev" | "deploy"), and dev selects the runner by build type — const runner = config.runners[runtime.build] (src/handlers/project/dev/index.ts:621) — where the Container runner builds a local image from a Dockerfile (src/core/dev/container.ts). Skipping the Dockerfile precheck for containerUri therefore pushes the failure into the dev runner with a worse message. The design needs a decision: pull-and-run the referenced image, or refuse dev for pre-built runtimes with an actionable error. Same question for agentcore build, which currently just synthesizes.

5. IAM section is incomplete for public ECR and for CMK-encrypted repositories

• For public.ecr.aws, ecr:* actions are not what's needed. AgentCoreHarnessRole grants ecr-public:GetAuthorizationToken and sts:GetServiceBearerToken for exactly this case. The doc only says public images "must not require a private repository ARN."
• The managed path passes ecrEncryptionKeyArn and grants kms:Decrypt (AgentCoreRuntime). A customer-owned pre-built repo encrypted with a CMK will fail to pull unless the execution role gets kms:Decrypt. Either add an optional key-ARN field or state the limitation explicitly.
• Worth noting under validation: the URI embeds account and region, and the CLI knows the deploy target's region, so a region/account mismatch is catchable at precheck rather than at CREATE.

6. Compatibility: an older pinned CDK will silently drop containerUri

Generated projects pin an exact version (src/assets/cdk/package.json → "@aws/agentcore-cdk": "1.0.0"), and the CDK's AgentEnvSpec is not a strict object, so an existing project whose installed CDK predates this feature will strip containerUri and take the source-asset → CodeBuild path — which, with Dockerfile validation skipped, fails inside CodeBuild instead of saying why. The "release CDK first" note doesn't cover existing projects. The design should require bumping MINIMUM_COMPATIBLE_CDK_VERSION (src/core/project/backends/cdk/compatibility.ts) and, for a containerUri runtime specifically, erroring rather than emitting the current soft warning.

7. Mutable tags produce silent no-op deployments

If containerUri ends in a mutable tag (:latest, :prod) and the user pushes a new image, nothing in the template changes, so CloudFormation performs no runtime update and the new image never rolls out. This is the main UX trap of the feature and isn't mentioned anywhere (non-goals cover tag existence, not this). Either document it and recommend digests, or state how the CLI nudges users.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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