Skip to content

feat(box): Add a Box template for each Python agent, with its profile fixes - #2857

Merged
mquang-amazon merged 10 commits into
box-integrationfrom
box/mq-5
Nov 19, 2026
Merged

mquang-amazon merged 10 commits into
box-integrationfrom
box/mq-5

Conversation

@mquang-amazon

@mquang-amazon mquang-amazon commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Description

MQ-5 (phase 11) of the Box integration squash plan: a Box template for each Python agent, and the box profile fixes that go with them. Ported from box-integration-development onto box-integration (the SYNC back-merge has not run, so each conflict is fixed here on the boundRuntime design).

  • Templates: agent-python-minimal-box, agent-python-langchain-box, a2a-python-strands-box, agui-python-strands-box, mcp-python-fastmcp-box (2e87f279, f5d17c37, e15c69b1, 0b1ee91e, c205c1ff).
  • Project write, .venv kept read-only (32f4161f): every box profile writes [project] access = "write", and box/base's uname tool lists the agent's deny_write folders.
  • Read-only project for the container agent (f0271bff).
  • Runtime region signing (3e223907): each Box gateway backend signs for ${{ inputs.aws.region }} (from AWS_REGION on the Runtime) instead of a region build wrote in. This removes the us-west-2 fallback leo237 flagged on test(box): Cover the home folder that regionFromConfigFile reads #2852.

Left out:

  • 24711c5c and the pin in f0271bff/3e223907: box-integration already pins 0.1.11-linux-preview.6.
  • 10dcd08e: already on box-integration through VV-3 (feat(box): run container and CodeZip agents with box run, and box only for the box templates #2853).
  • 28c34c48: its venv, uv and LiteLLM fixes are already on box-integration. Its add-runtime profile cleanup needs SA-5's .box/<agent>/local layout, so it goes with SA-5.
  • --isolation private-vpc hunks and tests (TK-1, out of scope).
  • README and testing-guide edits (DOCS-2).

box-network-build-stopped.golden.txt is re-recorded: the [project] table moves the profile line numbers down by 7.

--skip-install fix (fix(create): Keep a skip-install CodeZip box profile valid): with [project] access = "write", box 0.1.11-linux-preview.6 drops the profile's optional .venv deny_write while the folder is missing, and then refuses the profile (.venv/bin/python lies under the write grant). On box-integration, without [project], the same profile resolves, so this was new with 32f4161f. create --skip-install now makes an empty .venv for a CodeZip box agent, which uv sync fills later. Checked by hand: create --skip-install then box profile show resolves, and uv sync into the empty .venv works.

Related Issue

Box integration squash plan, phase 11.

Testing

  • bun test: 5347 pass, 1 fail (the known the box on PATH > resolves a profile test, which fails only with the local box preview.6)
  • bun run typecheck, bun run lint:check, Prettier, bun run build, bun run compile:darwin-arm64, bun run secrets:check: pass
  • agentcore create --template <t> for each of the five new templates from the built dist/, then box profile show .box/profile.toml --format json in each project: all resolve.
  • Not run: the e2e suite, and deploy.

Also covers the langchain and minimal box templates in the project and box profile tests.
Also lists the box templates in the README.
Newer box (staging-boxy main #496) gives a profile without a [project] table no project access, and then drops the agent's deny_write. Write [project] access = "write" in every box profile, and list the agent's deny_write folders on box/base's uname tool, which box gives its own project write grant. Without it box refuses to run the venv's Python.

Needs box 0.1.11-linux-preview.4 or later: preview.3 refuses the [project] key, so bump the box pin in boxRelease.json before this ships.
Build now resolves the box profile on the host with box profile show --format json. The container image's /app/.venv does not exist there, so a project write grant left the venv Python unprotected and box refused the profile. The image's agent writes nothing in /app, so its profiles take [project] access = "read" and need no tool deny_write.

Pin box 0.1.11-linux-preview.5, which has box profile show --format json (staging-boxy #547) and a Box Core fix that leaves X-Amzn-Trace-Id out of the SigV4 signature.
…own region

box 0.1.11-linux-preview.6 lets a backend's auth.aws.region read a ${{ inputs.<name> }} placeholder (staging-boxy #549). The generated box/agentcore pack now declares aws.region from AWS_REGION, which the Runtime sets, and each Box gateway backend signs for ${{ inputs.aws.region }} instead of a region build wrote in. Pin preview.6 and require it in the testing guide.

Tested: bun test (5304 pass), the box e2e suite (7 box templates: create, deploy, invoke, box running on the Runtime, teardown), and a CodeZip and a container deploy that answered with Memory.
@mquang-amazon
mquang-amazon requested a review from a team November 19, 2026 21:30
@codecov-commenter

codecov-commenter commented Nov 19, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.72%. Comparing base (dd36f7b) to head (c1bc457).

Additional details and impacted files
@@               Coverage Diff                @@
##           box-integration    #2857   +/-   ##
================================================
  Coverage            96.72%   96.72%           
================================================
  Files                  738      738           
  Lines                64603    64674   +71     
================================================
+ Hits                 62486    62557   +71     
  Misses                2117     2117           

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

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Review: MQ-5 (phase 11) of the Box integration squash plan

This is a first review. There is no earlier review from me on this PR.

Which plan PR this is. The PR is MQ-5, not TK-1 or the rest of SA-4. I couldn't read the plan doc (it returned 401), so I checked the commit list against box-integration-development directly.

Commit-list check. The base is box-integration, at the current tip dd36f7b2, and the PR is mergeable. It has 8 commits, each a port of a dev commit that exists on box-integration-development:

  • the five templates: 2e87f279, f5d17c37, e15c69b1, 0b1ee91e, c205c1ff;
  • 32f4161f, f0271bff and 3e223907.

The exclusions are correct:

  • 24711c5c and the boxRelease.json pins: box-integration already pins preview.6.
  • 10dcd08e: already merged through VV-3 #2853.
  • 28c34c48: left for SA-5.
  • The --isolation private-vpc message in c205c1ff: TK-1.
  • The README and docs/box-local-testing.md hunks: DOCS-2. The only doc change in 3e223907 is the preview.5 to preview.6 pin, which is already on the base.

Nothing already merged is applied twice. The diff against the base is 8 files, and none of them repeats #2845–#2853 content.

Protected fixes. The only protected file this PR touches is boxProfile.ts. Its removed lines are only the region parameters of the gateway backend helpers. writesBedrockRoute, tomlKey, policies, runtimeRunsInBox, boxTemplate, ABSOLUTE_PATH_PATTERN, the ${{ inputs.gateway.url }} backend with the bare aws:// signer, the aws.region input (with its pattern) and preview.6 are all intact. There are no @GATEWAY_BOX_URL@ or @AGENT_ENV@ placeholders. boxTelemetry.ts, boxMemory.ts and boxProfileCredentials.ts are untouched, so #2851's xray:PutTraceSegments grant and required region survive. The new shortcuts use box: true, which is the shortcut-table field on the base; resolveRuntimeTemplateShortcut maps it to boxTemplate, so this is not a regression of the rename.

What I checked.

  • Each new template's entry point matches the box runner. The HTTP templates expose main:app. AG-UI reads PORT, FastMCP reads FASTMCP_PORT, and serve_a2a reads A2A_PORT (bedrock-agentcore 1.26.1), so the workload port +1 works.
  • CODEZIP_BOX_FRAMEWORKS covers langchain and none.
  • The affected test files (boxProfile, shortcuts, project, manager.boxNetwork) pass locally: 205/205.

Open items from earlier PRs.

  • The renderRuntimeBoxProfile us-west-2 fallback: partly addressed. The Box gateway signing region now comes from ${{ inputs.aws.region }}, which ports 3e223907. const region = network?.region ?? DEFAULT_EGRESS_BEDROCK_REGION is still there for bedrock.region and the Bedrock host. Build cannot reach it, because BoxNetwork.region is required and boxNetworkWriters.ts always passes a network, so it only fires in tests. Dev's 3e223907 drops the ?? here, but dev's renderBoxProfile still defaults its region parameter. Non-blocking; consider dropping the ?? so a missing region fails in tests instead of turning into us-west-2.
  • Not addressed here, and still planned for later: the credential refresh and AWS_PROFILE reporting in agentcore dev, box.version in agentcore dev, the "before anything is written" comment, the refusal message after remove, the seven duplicated template files, the start.py test, and #2851's telemetry messages (29d283d6).

Non-blocking findings.

  1. Comment accuracy. runtimeGatewayBackend ends with "so the profile names no region". The Runtime profile still names bedrock.region under [options] and region = in each [telemetry.*] table. Only the backend names no region. (Inline comment.)
  2. BOX_BASE_PROJECT_WRITE_TOOLS = ["uname"] is a hard-coded copy of what box/base's tools are. If a later box/base adds a tool that gets the project write grant, box refuses every CodeZip box profile. That refusal is loud, not silent, but it is easy to miss when the pin is bumped. Consider a check in the box-on-PATH resolver test, or a comment saying where the list comes from. (Inline comment.)
  3. The --skip-install known issue. The refusal names "the write grant", and this PR adds the explicit [project] access = "write". Please confirm it also reproduces on the base with agent-python-strands-box, which the PR description says it does, and track it, since the new templates inherit it.
  4. Tests. selectTemplate in create.screen.test.tsx silently does nothing for a name missing from PROJECT_TEMPLATE_NAMES (indexOf is -1). waitForText catches it later, but an expect(index).toBeGreaterThan(-1) would fail with a clearer message. Coverage for the new [project] and [tool.uname] sections is good: the local CodeZip, Runtime CodeZip and container cases all assert the full parsed profile. No test renders the local profile of an A2A, AG-UI or MCP box template, and the uname deny_write is only asserted for HTTP. That is acceptable, because serve() and toolDenyWrite are protocol-independent.
  5. No new types. There is only the BOX_BASE_PROJECT_WRITE_TOOLS constant. There are no new error paths or catches, so I found no silent failures. There are no Windows-unsafe test patterns: no : path splitting, no hard-coded /, no file modes, no sh spawns and no empty env.

CI. CodeQL, Analyze, verify / Linux, verify / Windows and the CodeBuild e2e pass. verify / macOS was still pending when I posted, after about 10 minutes. If it fails only on the known 5 s screen-test timeouts, that is the known flake and non-blocking.

Decision: APPROVE. I found no correctness bugs, silent failures or missing tests for important logic, and no protected fix is lost. The items above are non-blocking.

Say that the backend, not the profile, names no region; name the box
release the box/base tool list comes from; and fail selectTemplate at
once for a template name that is not in the list.
With [project] access = "write", box drops the profile's optional
.venv deny_write while the folder is missing, and then refuses the
profile: the venv's Python would be under the project's write grant.
So 'create --skip-install' left a CodeZip box agent that 'build' and
'deploy' could not run. create now makes an empty .venv for it, which
'uv sync' fills later.
@mquang-amazon

Copy link
Copy Markdown
Contributor Author

Thanks @leo237. On the review body:

3. --skip-install: I was wrong in the description. It does not reproduce on box-integration: there, agent-python-strands-box --skip-install resolves, because the profile has no [project] table. 32f4161f (3df66a24 here) brings it in. While .venv is missing, box preview.6 drops the optional .venv deny_write, and then refuses the profile, because the venv's Python lies under the new project write grant.

Fixed in c1bc4576: create --skip-install makes an empty .venv for a CodeZip box agent, and uv sync fills it later. I checked it with the built CLI and box preview.6: create --skip-install for agent-python-strands-box and agent-python-minimal-box, then box profile show resolves, and build gets past box. uv sync into the empty .venv works. One gap left for MQ-6, which owns src/core/dev/box.ts: dev checks only that .venv exists, so after --skip-install it reports box's error about the missing Python instead of its own "run uv sync" hint. The fix there is to check for .venv/bin/python. The development branch has the same bug, and this fix is not on it.

The ?? DEFAULT_EGRESS_BEDROCK_REGION fallback: I left it for now. As you note, build always passes a region, so only tests reach it, and removing it changes the helper's signature for the tests SA-5 and SA-6 also touch. I'll raise it with them.

Other items (the 7 duplicated template files, start.py test, credential refresh, and the rest): they stay with the later phases, as you listed.

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Re-review: MQ-5 (phase 11) of the Box integration squash plan

The last review (5983914397) was on d6eec45d. Since then the branch has two new commits, 68d2bbb4 and c1bc4576, added on top of the earlier ones. It was not rebased: the base is still dd36f7b2 (#2853), and d6eec45d is still in the history. The change is 4 files, +43/-3. Only comments and the import line are removed, so none of the protected box-integration fixes from #2845 through #2853 are touched. Neither commit pulls in work from another plan PR or applies something twice. c1bc4576 is new content that is not on box-integration-development.

Earlier items

  1. network?.region ?? DEFAULT_EGRESS_BEDROCK_REGION: not changed (still at boxProfile.ts:723). The author explains that build always passes a region, so only tests reach this fallback, and that the helper's signature is shared with SA-5/SA-6. Fine to leave for later. Non-blocking.
  2. "the profile names no region": addressed in 68d2bbb4. It now says "the backend names no region".
  3. BOX_BASE_PROJECT_WRITE_TOOLS: addressed in 68d2bbb4. The comment now names the box release it comes from (0.1.11-linux-preview.6, which matches boxRelease.json) and says to recheck box/base's tools when the pin moves. Leaving out a resolver test that needs box on PATH is reasonable.
  4. --skip-install: answered and fixed. It does not happen on the base, because there is no [project] table before 32f4161f/3df66a24. c1bc4576 fixes it.
  5. selectTemplate: addressed in 68d2bbb4 (expect(index).toBeGreaterThan(-1)).
  6. No local-profile render for the A2A, AG-UI and MCP box templates: not changed. This is still non-blocking.

New changes

  • c1bc4576 (empty .venv on create --skip-install for a CodeZip box agent): this looks right. It is gated on skipInstall && startsInBoxOnCodeZip(...), so container and non-box agents are unaffected. mkdir(..., { recursive: true }) throws on failure rather than swallowing it, and .venv/ is already gitignored. uv sync accepts an empty existing .venv, and the author checked that against preview.6. The new manager.test.ts case covers the CodeZip box case and both negative cases (container and plain). It uses join and readdirSync, so it is Windows-safe. The code comment is accurate.
  • Non-blocking, a follow-up to track: this does weaken an existing guard. src/core/dev/box.ts:77-82 checks only existsSync(.venv) before it gives its "Run uv sync in …" hint. After create --skip-install, agentcore dev now gets past that check and fails on box's missing-Python error instead. The author already raised this and assigned it to MQ-6 (check .venv/bin/python, plus a test next to box.test.ts's "tells the user to run uv sync when the runtime has no .venv"). I checked: box-integration-development has the same existsSync(.venv) check, so no dev commit fixes this. Please file it so it does not get lost, since the plan does not carry it as a commit.
  • No new types. No silent failures in the new code.

Cross-PR

  • #2859 is still open. Its manager.tsx hunks do not overlap the new block, but the earlier conflict in __fixtures__/box-network-build-stopped.golden.txt still means whichever PR merges second needs a rebase.
  • #2860 is not affected by these two commits.

CI

Analyze, CodeQL, verify / Linux, verify / Windows and the CodeBuild e2e all pass; e2e is skipped. verify / macOS was still pending after the roughly 10-minute wait, so I am posting without it. If it fails with a 5 s screen-test timeout, that is the known macOS flake on the base and is non-blocking.

Decision: APPROVE. Everything open is non-blocking or planned for a later PR.

@mquang-amazon
mquang-amazon merged commit f5503f0 into box-integration Nov 19, 2026
7 checks passed
@mquang-amazon
mquang-amazon deleted the box/mq-5 branch November 19, 2026 22:44
mquang-amazon added a commit that referenced this pull request Nov 19, 2026
- Build the expected warnings from ENV_LOCAL_RELATIVE_PATH, so the
  tests pass on Windows, where it is agentcore\.env.local.
- Skip an env:// ref with a blank name, as parseBoxEnvRoutes did.
- Pin that a box container gets the shell's key over .env.local's.
- Remove parseBoxEnvRoutes and readBoxEnvRoutes, which no code calls
  since writeBoxDevEnvLocal went.
- Check for the venv's Python, not only .venv: create --skip-install
  (#2857) leaves an empty .venv, which dev must not take for an
  installed one.

@tejaskash tejaskash left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Requesting changes for a follow-up, since this one is merged. The templates and region signing look good: every box template creates a project with projectType, box.version, the bound gateway and start.py, the non-box templates are unchanged, and boxed is decided by runsInBox only. The one I'd fix first is the project-wide grant (inline), which lets the boxed agent read the real API key in agentcore/.env.local.

Others without a line in the diff:

  1. The five new box templates don't git-ignore .box-dist/. They reuse the non-box asset folders, whose .gitignore has no .box-dist/ or .box-dev/ line (agent-python-minimal has no .gitignore at all). After a build, git add . commits the box binaries. Having stageBoxCodeZip write a .gitignore with * inside .box-dist/ would cover every template and existing projects.
  2. OpenTelemetry: the L3 runs opentelemetry-instrument start.py, start.py hands over to box run, and the agent in the box gets nothing, so five more CodeZip templates send no traces while the reused LangChain README says traces are collected automatically. Until traces work in a box, could CodeZip box templates write instrumentation.enableOtel: false like the container one, and the warning in cdk.ts:256-268 drop its Container condition?
  3. The A2A localhost URL comes from serve() in boxProfile.ts:320-325, which runtimeCodeZipRunner reuses, so it's in the deployed profile too (see the comment on shortcuts.ts).
  4. The reused folders lack tomli for Python 3.10, which start.py imports when tomllib is missing, so setting PYTHON_3_10 gives an import error at start.
  5. Small: the error at manager.tsx:2264-2265 still lists two box templates, there are seven now. The profile tests force boxTemplate: true onto non-box names (boxProfile.test.ts:29-34), so nothing checks the new shortcut entries. Resolving the real box names would.

// The image's agent reads /app and writes nothing there. Build resolves the profile on the host,
// where the image's /app/.venv does not exist, so a write grant would leave its Python unprotected
// and box would refuse the profile. A CodeZip agent writes in the folder box starts in.
const projectSection = container

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Every local CodeZip profile now gets [project] access = "write", and under agentcore dev box starts in the project root, so the agent can read and write the whole project. That includes agentcore/.env.local with the real model provider key, which the keyed route is meant to keep away from it, and .git/hooks, agentcore/cdk/ and agentcore.json, which would run outside the box on the next commit or deploy. A sandboxed Python process with the pinned box release can read a dummy credential from that file. Could this be "read" like the container profile, with agentcore/ and .git in deny_read and deny_write, or start box in app/<runtime> instead? A check that the agent can't read .env.local would keep it that way.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I would do start box in app/runtime instead, since ever read can still have .env.local. THis is simpler

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed on box-integration: agentcore dev now starts box in the runtime's folder, app/<runtime>, so the [project] access = "write" grant covers only the code folder, not agentcore/.env.local, .git or agentcore/cdk. box.test.ts:192 checks the start folder.

build: "CodeZip",
language: "Python",
framework: "strands",
protocol: "A2A",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

For this template, serve() sets AGENTCORE_RUNTIME_URL to http://localhost:9000/ for any target, and runtimeCodeZipRunner reuses it, so the deployed profile has it too. serve_a2a() in bedrock_agentcore 1.24.2 gives that variable precedence for the agent card URL, so a deployed boxed A2A agent advertises localhost and clients that discover it connect to themselves. Could the override be local only, with the Runtime's own value passed through the box/agentcore pack? boxProfile.test.ts:126 only covers the local case.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

i agree this is a bug

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed on box-integration in 0dce816: the deployed profile reads AGENTCORE_RUNTIME_URL from the Runtime through the @box/agentcore pack, so only the local profile sets the localhost URL.

supportsModelProviderOverride: false,
runtimeVersion: "PYTHON_3_14",
},
"agent-python-minimal-box": {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Small one: each box entry copies its twin and differs only in runtimeName, description and box, so a later change (a runtimeVersion bump, a protocol fix) has to be made twice with nothing checking they match. A spread like { ...A2A_PYTHON_STRANDS, runtimeName, description, box: true } keeps them in step, and the as const satisfies check still holds.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

will make this change

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in #2886 (08fb943): each box shortcut is now a spread of its twin, e.g. { ...A2A_PYTHON_STRANDS, runtimeName, description, box: true }. The resolved table is identical to before, key order included.

const appDir = join(destination, "app", scaffoldRuntimeInput.runtimeName);
yield* this.ensureLockFileExists(appDir);
}
if (input.skipInstall && scaffoldRuntimeInput && startsInBoxOnCodeZip(scaffoldRuntimeInput)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Small one: the empty .venv could be part of the template tree in withBoxStartScript, next to start.py, rather than a --skip-install branch in create. uv sync fills an existing empty .venv, and it keeps the box layout in one place.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I think I have this in later commit, will include it herer

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in #2886 (08fb943): the empty .venv is part of boxCodeZipFiles with start.py in templates/project.ts, which both create and add runtime write. The --skip-install branch in create and the copy in add runtime are gone.

@mquang-amazon

Copy link
Copy Markdown
Contributor Author
  1. update .gitignore template for .box-dist/*. Agree, doing it in
  2. Agreed. Today the agent in the box gets no OTEL: opentelemetry-instrument wraps start.py, not the boxed agent. The fix (8cb595b, run the agent under opentelemetry-instrument in the box profile) waits on a Box Core change: box signs X-Amzn-Trace-Id, which X-Ray rewrites, so the gateway rejects the call (plan Phase 15 / SA-7). Until then, I'll make every box template write instrumentation.enableOtel: false and drop the Container condition from the warning. Box's own telemetry from feat(build): Send the CloudWatch telemetry and the HTTP MCP servers of the box profile on AgentCore Runtime #2851 is not affected
  3. This is a bug, I can address it
  4. This will be addressed by future commit , I can bring it here as well
  5. Will update the error and the test

SaiAbhishek98 pushed a commit to SaiAbhishek98/agentcore-cli that referenced this pull request Nov 20, 2026
The README said that two templates run their agent in a box, and that a
Box project holds one runtime, so add runtime and export harness refuse
it. Since aws#2857 there are seven box templates, and
since aws#2859 add runtime adds a box runtime to a Box
project. The pre-review of
[aws#2866](aws#2866)
found this. The paragraph now names the seven templates, says that each
runtime has its own box profile, says what add runtime and export
harness do in a Box project, and says that build derives the Runtime
profile from the local profile.

Tests: none; this changes only the README.
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
[#2857](#2857)
changes the AgentCore Runtime profile that renderRuntimeBoxProfile
writes, and adds five box templates. The rules did not have these
changes, so the derived profile was different from the profile of the
old renderer:

- [d6eec45](d6eec45)
  signs each Box gateway backend for ${{ inputs.aws.region }}, the
  region of the Runtime. The gateway rule signed it for the build
  region.
- [3df66a2](3df66a2)
  and
  [f1f55b8](f1f55b8)
  write [project] access, and a CodeZip local profile gets
  [tool.uname.filesystem] deny_write for the venv. The Runtime profile
  has no venv, so the old renderer wrote no [tool.uname]. The derived
  profile kept that table, with the venv path moved to the code
  directory.

With this change:

- The gateway rule signs each backend for ${{ inputs.aws.region }},
  which the agentcore pack reads from AWS_REGION. The build region
  does not go into a backend.
- The additions rule replaces each [tool.<name>] table that the local
  profile keeps as the template writes it with the Runtime table of the
  template. The Runtime template has no tool table, so [tool.uname]
  goes. A tool table that the user writes or changes stays.
- [project] goes through as the local profile has it. The old renderer
  wrote the same value for the local and the Runtime profile.

Tests: additions.test.ts "deriveRuntimeProfile on each box template of
create" compares the whole derived profile with renderRuntimeBoxProfile
of box-integration (f5503f0) for each of the seven box templates, the
model provider of the template and OpenAI where the template lets the
user change it, with and without Memory, and with three telemetry
inputs: 66 inputs. The test that compares the owned tables for each
build and protocol also compares [project] and [tool]. additions.test.ts
"removes the [tool.uname] table that a CodeZip template writes, and
keeps each tool table of the user". gateway.test.ts "gives each host of
an entry with several destinations its own route, signed for the
Runtime's region and not the build region", and the tests that compare
the gateway rule with renderRuntimeBoxProfile.

Dev port: dev does not have #2857, but the renderer of
dev also signs each backend for ${{ inputs.aws.region }}, and the
tests compare the rules with the renderer of dev. The tests use the
dev Box gateway name and the dev renderBoxProfile arguments.

(cherry picked from commit a3ee1f1)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…local profile

Build staged the AgentCore Runtime profile that renderRuntimeBoxProfile
made from agentcore.json and from the Box network model. That renderer
did not read the local profile of the runtime. Thus each stdio
[mcp.<name>] server and each [tool.<name>] of the local profile was not
on AgentCore Runtime, and build gave no message.

With this change, the runtime profile writer stages the profile that
deriveRuntimeProfile makes from the local profile, with the comment
lines of runtimeProfileHeader. buildBoxNetwork keeps the profile and
its comment lines in BoxNetwork.runtimeProfile and
BoxNetwork.runtimeProfileHeader. A staged runtime with no Box network
stops build with a message, because the writer has no profile for it.

- renderBoxProfile writes only the local profile.
  runtimeAgentTemplate gives the [agent] table of a box template on
  AgentCore Runtime, in the paths of the local profile. The additions
  rule gives that table to each value that is the template's own, and
  the paths rule then moves its paths. Thus only the rules move a path
  to AgentCore Runtime.
- This commit removes renderRuntimeBoxProfile, runtimeGatewayRoutes,
  runtimeGatewayRouteSection, runtimeMcpServerSection,
  runtimeMcpServers, runtimeGatewayBackend, runtimeTelemetrySection,
  runtimeRegionEnv, RUNTIME_AWS_SIGNER, RUNTIME_AWS_STAND_IN_LINES, the
  Runtime branch of renderBoxProfile, and its runtimeRoutes and
  runtimePolicies parameters. The rules do this work.
- cloudWatchTelemetry keeps its CloudWatch filter. The telemetry policy
  writer reads it for the IAM grant. The refusals rule stops build for
  a target of a different type in the local profile.
- The guide tells how build derives the Runtime profile.

The derived profile is the same as the profile of the old renderer for
each box template, with the default telemetry target. Only the
sequence of the keys is different. Before this commit removed the
renderer, a test wrote the tables of the renderer of box-integration
(f5503f0, with
[#2857](#2857))
into runtimeProfile/__fixtures__/old-renderer-tables.json: the owned
tables for 72 inputs (CodeZip HTTP, MCP, A2A, and AGUI, container HTTP
and MCP, Bedrock and OpenAI, with and without Memory, and 3 telemetry
inputs), the whole profile for 66 inputs of the seven box templates of
create, and 4 gateway inputs.

Tests: additions.test.ts "gives the tables the old renderer wrote" (72
inputs), "gives the whole profile that the old renderer wrote" (66
inputs), and gateway.test.ts "the gateway rule and the Runtime renderer it
replaced" compare deriveRuntimeProfile with that file.
boxProfile.test.ts "runtimeAgentTemplate". boxNetworkWriters.test.ts
"writes the Runtime profile and a byte copy of each policy file beside
it" and "stops for a runtime that it stages with no derived Runtime
profile". The staging, build, and cdk tests stage the derived profile
of their model. The tests of the old renderer are removed: the rule
tests and the fixture cover them.

Dev port: old-renderer-tables.json holds the tables of the renderer of
box-integration-development (da8df85), not of box-integration. A
temporary test wrote them on this branch before this commit removed
that renderer: the same 72, 66, and 4 inputs, and 6 inputs with an
otlp or langfuse target and AGENTCORE_BOX_SECRETS_MANAGER=1
(secretsManager). The dev runtime profile writer keeps its container
and codezip flags. renderBoxProfile keeps the dev region default, the
dev header, and the dev Bedrock rule. The tests of the old renderer go,
also the dev tests of its Secrets Manager output: the derivation tests
of the next dev commit replace them. The test of the trace warning of a
box container and the test of a box runtime with no box.version are not
in this port, because dev does not have that warning or that rule.

(cherry picked from commit bab52a9)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
The README said that two templates run their agent in a box, and that a
Box project holds one runtime, so add runtime and export harness refuse
it. Since #2857 there are seven box templates, and
since #2859 add runtime adds a box runtime to a Box
project. The pre-review of
[#2866](#2866)
found this. The paragraph now names the seven templates, says that each
runtime has its own box profile, says what add runtime and export
harness do in a Box project, and says that build derives the Runtime
profile from the local profile.

Tests: none; this changes only the README.

Dev port: the README of dev names the seven templates and the box
release already, and dev does not have the add runtime of
#2859. This port adds only the sentences on the local
profile of each box runtime and on the derived Runtime profile.

(cherry picked from commit cbd378c)
* finds the pack beside its binary at {@link AGENTCORE_CODEZIP_PACK_PATH}.
*/
export function renderAgentCoreCodeZipPack(): string {
return `# The CodeZip Runtime's Python and code directory, read from the environment start.py exports.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We can fix later, but handlebar templates are generally easier to maintain than inline string sub.

box: true,
supportsModelProviderOverride: true,
runtimeVersion: "PYTHON_3_14",
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I thought we were just doing this for strands and not all templates, but I guess we are duplicating all templates and "boxifying" them?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants