[mquang-amazon]

Description

agentcore deploy runs the agent that agentcore create boxes in a box on AgentCore Runtime. Before this, only agentcore dev ran it in a box (#2790). Nothing shipped box to the Runtime or started it there.

• CodeZip start scripts: create writes start.py and start.sh into every Python CodeZip template (Strands HTTP/A2A/AG-UI, LangChain, minimal, FastMCP) and sets entrypoint to start.py. The Runtime needs a .py entry point, so start.py hands over to start.sh. start.sh fills in the Runtime profile and runs box run in /tmp/box/workspace. If box fails or the agent does not answer within 22s, it serves main.py without box (the Runtime allows 30s). BOX_START_DISABLE=1 skips box.
• Container image: the Strands container template's Dockerfile copies box, its helpers, packs, profile, and start.sh into /opt/box, and its ENTRYPOINT is start.sh. Under agentcore dev (LOCAL_DEV=1), start.sh only runs box run with the project's profile, which dev stages (feat(dev): Run CodeZip and container agents with box run #2790).
• Staging on build and deploy: CdkBackend stages .box-dist/ from AGENTCORE_BOX_SOURCE before synth. That covers each CodeZip runtime whose entry point is start.py and each container whose Dockerfile copies .box-dist/. The Linux build comes from a staging-boxy checkout's target-al2023/, plus the libffi shim for CodeZip. If a boxed runtime has no AGENTCORE_BOX_SOURCE, build fails with an actionable error.
• Runtime box profile: renderRuntimeBoxProfile renders the profile from agentcore.json. It has no reload. Bedrock is signed with a bare aws://, the default chain, i.e. the execution role. It includes placeholders (@CODE@, @PYTHON@, @PYTHON_PREFIX@, @GATEWAY_BOX_URL@, # @AGENT_ENV@) that start.sh fills in. Only the deployed Memory/Gateway IDs and URLs reach the agent's env. A non-Bedrock provider gets no route yet: on the Runtime its key comes from AgentCore Identity.
• Memory through the Box gateway: when a boxed runtime has its default Memory, build and deploy add the Box gateway's agentcore passthrough target, bedrock-agentcore.us-west-2, signed with the gateway role. They also write agentcore/box-memory-policy.json (Memory data-plane actions on <project>_*<memory>-*) and list it in the gateway's new additionalPolicies. The raw agentcore.json is patched, as syncRuntimeBuilds does, so unknown fields survive. Running it again changes nothing.
• Schema: agentCoreGateways[].additionalPolicies, which cannot be combined with executionRoleArn.
• dev guard: a runtime whose entry point is start.py but has no .box/profile.toml is refused, because start.py runs no agent of its own.

The local (agentcore dev) profile is byte-identical to #2788's for every template and model provider (checked across 29 combinations).

Out of scope (follow-ups): TypeScript CodeZip/container templates (no TS box profile in #2788 yet), and the Bedrock Managed Agents executor box.

Depends on

• feat(dev): Run CodeZip and container agents with box run #2790 (base of this PR), which is stacked on feat(create): Write a box profile for each Python template #2788
• feat(create): Declare the Bedrock target on the runtime's Box gateway #2789, merged into this branch (a5a5a81b) until it lands. That resolves one conflict in shortcuts.ts / boxProfile.ts (DEFAULT_EGRESS_BEDROCK_REGION → BOX_GATEWAY_BEDROCK_REGION). The diff shows feat(create): Declare the Bedrock target on the runtime's Box gateway #2789's commits until it merges
• @aws/agentcore-cdk with Box gateway additionalPolicies support (agentcore-l3-cdk-constructs box-v3: "Attach additionalPolicies to the Box gateway role"), not yet released or pinned
• A Linux box build via AGENTCORE_BOX_SOURCE, until box ships a Linux release

Related Issue

N/A (box integration)

Documentation PR

Not applicable.

Type of Change

• New feature

Testing

• I ran bun test: 4903 pass. 3 fail on this host and also fail on an unmodified base: toolAvailable, requireTool, SourceResolver bytes ... under node
• bun run test:e2e: not run. A boxed deploy needs AGENTCORE_BOX_SOURCE and the unreleased CDK library
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run audit
• I ran bun run secrets:check
• I ran bun run build
• I modified src/assets/ and updated manager.test.ts.snap (new start.py/start.sh, entrypoint: start.py)
• This PR does not change command.md

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• Any dependent changes have been merged and published

---

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