Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,9 +210,8 @@ to a Box project, and refuses a TypeScript runtime and a Bedrock Agent import th
box profile; build and deploy stop without them. Build derives the AgentCore Runtime profile of
each runtime from its local profile. box comes from the public GitHub release `v0.1.11-preview.10` of
[mquang-amazon/box-releases](https://github.com/mquang-amazon/box-releases). No token or account
is needed to download it. When that release has no build for your machine, use the build of
`v0.1.11-linux-preview.7`, or of a later release that has one, for `agentcore dev` and the profile
checks of `build`.
is needed to download it. Use that release's build for your machine for `agentcore dev` and the
profile checks of `build`: an older box cannot read the profiles that this CLI writes.

`src/core/project/backends/boxRelease.json` pins the Linux build of box that ships to AgentCore
Runtime, with its repository, version and SHA-256. `bun scripts/bump-box-release.ts --box <version>`
Expand All @@ -235,8 +234,8 @@ How each command uses it:
with that instruction when `box` is not on your PATH. Container agents need no local box.

Each box runtime names its release in `agentcore.json` with `"box": { "version": "<version>" }`,
which `agentcore create` writes. It must be the pinned version, whose checksums `boxRelease.json`
keeps; build, deploy and container `dev` stop on any other version and say to set the pinned one.
which `agentcore create` writes. Every box runtime runs the pinned version, whose checksums
`boxRelease.json` keeps: build and deploy set `box.version` to it, and say so when it named another.

On AgentCore Runtime, box signs the agent's Bedrock and Memory calls with the execution role: the
profile's bare `aws://` resolves the AWS default credential chain, which box reads and refreshes
Expand Down
256 changes: 128 additions & 128 deletions docs/box-local-testing.md

Large diffs are not rendered by default.

16 changes: 8 additions & 8 deletions e2eTest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ The tests that deploy also need `AGENTCORE_E2E_BOX_CDK`: the pinned `@aws/agentc
cannot deploy a Box project yet. Set it to an `@aws/agentcore-cdk` version or a `file:` tarball
that can, for example one packed from the `box-integration` branch of
[agentcore-l3-cdk-constructs](https://github.com/aws/agentcore-l3-cdk-constructs) with
`npm run build && npm pack --ignore-scripts`. The tests install it in each Box project's
`agentcore/cdk`. Without it, as in CI, they skip.
`npm run build && npm pack --ignore-scripts`. The tests install it in the `agentcore/cdk` of each
Box project that deploys. Without it, as in CI, they skip.

The `dev` tests also need a machine where `box run` can start its sandbox, and for the container
template a container tool. Box listens on the protocol's fixed port (8080, 8000 or 9000), so the
Expand All @@ -46,13 +46,13 @@ AGENTCORE_E2E_BOX_CDK=file:/path/to/aws-agentcore-cdk-1.1.0.tgz bun run test:e2e

That runs each Box template on its default Python. The CodeZip box template on Python 3.10 to 3.13
(`py_strands_box_3_10` to `py_strands_box_3_13`) is in the runtime templates describe, so it runs
with `--tagsFilter='runtime'` or a full run, given `box` and the same opt-in. Those four cases
pass only once box runs CodeZip agents without the ffi shim (#2867): until then `boxRelease.json`
pins a shim for `PYTHON_3_14` only, so they fail on any machine.
with `--tagsFilter='runtime'` or a full run, given `box` and the same opt-in.

The `box-egress` test checks that box, under `agentcore dev`, lets the agent reach the host its
profile allows (`checkip.amazonaws.com`) and blocks any other (`example.com`). It reaches public
hosts, so the network can make it fail. It retries twice, and `--tagsFilter='box'` leaves it out:
The `box-egress` tests check that box lets the agent reach the host its profile allows
(`checkip.amazonaws.com`) and blocks any other (`example.com`): one under `agentcore dev`, and one
on AgentCore Runtime, where the allowed host's calls go through the runtime's Box gateway. The
second deploys, so it also needs `AGENTCORE_E2E_BOX_CDK`. They reach public hosts, so the network
can make them fail. They retry twice, and `--tagsFilter='box'` leaves them out:

```sh
bun run test:e2e -- --tagsFilter='box-egress'
Expand Down
113 changes: 97 additions & 16 deletions e2eTest/project/templates.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -276,7 +276,7 @@ describe(
TIMEOUT_MS.PROJECT_REMOVE,
},
async (runtime) => {
const projectDir = await createTemplateProject(cli, runtime);
const projectDir = await createTemplateProject(cli, runtime, { deploys: true });
let scenarioCompleted = false;
try {
if (!runtime.skipDev) {
Expand Down Expand Up @@ -363,7 +363,7 @@ describe.skipIf(!BOX_DEPLOYS)(
TIMEOUT_MS.PROJECT_REMOVE,
},
async (runtime) => {
const projectDir = await createTemplateProject(cli, runtime);
const projectDir = await createTemplateProject(cli, runtime, { deploys: true });
let scenarioCompleted = false;
try {
const deployment = parseResult(
Expand Down Expand Up @@ -425,7 +425,7 @@ describe.skipIf(!BOX_ON_PATH)(
"$name",
{ timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE },
async (runtime) => {
const projectDir = await createTemplateProject(cli, runtime);
const projectDir = await createTemplateProject(cli, runtime, { deploys: false });
const { devOutput } = await invokeLocally(
cli,
runtime,
Expand Down Expand Up @@ -489,29 +489,105 @@ describe.skipIf(!BOX_ON_PATH)(
},
async () => {
const template = runtime;
const projectDir = await createTemplateProject(cli, template);
await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT);
const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml");
const host = new URL(EGRESS_ALLOWED_URL).host;
await writeFile(
profile,
`${await readFile(profile, "utf8")}\n[egress.checkip]\ndestinations = ["${host}"]\n`,
);
const projectDir = await createTemplateProject(cli, template, { deploys: false });
await useEgressAgent(projectDir);

const { response } = await invokeLocally(
cli,
template,
projectDir,
BOX_DEV_PORTS[template.protocol],
);
const reply = EgressReplySchema.parse(JSON.parse(response.body));
expect(reply.allowed).toEqual({ status: 200 });
expect(reply.blocked.error).toMatch(/403/);
assertEgressReply(response.body);
},
);
},
);

// The same egress check on AgentCore Runtime, where box sends the allowed host's calls through the
// runtime's Box gateway. It deploys, so it needs the AGENTCORE_E2E_BOX_CDK opt-in as well.
describe.skipIf(!BOX_DEPLOYS)(
"egress on AgentCore Runtime for a Strands Box template",
{ tags: [TAGS.BOX_EGRESS] },
() => {
const cli = new CliRunner();
const runtime = BOX_TEMPLATES.find((t) => t.template === "agent-python-minimal-box");
if (!runtime) throw new Error("BOX_TEMPLATES has no agent-python-minimal-box case");

test(
"allows the profile's host through the Box gateway and blocks any other",
{
retry: 2,
timeout:
TIMEOUT_MS.PROJECT_CREATE +
TIMEOUT_MS.PROJECT_INVOKE +
2 * TIMEOUT_MS.PROJECT_DEPLOY +
TIMEOUT_MS.PROJECT_REMOVE,
},
async () => {
const projectDir = await createTemplateProject(cli, runtime, { deploys: true });
await useEgressAgent(projectDir);
let scenarioCompleted = false;
try {
const deployment = parseResult(
DeployResponseSchema,
await cli.run(["deploy", "--yes", "--json"], projectDir),
);
expect(deployment.message).toContain("deployed project");

const response = parseResult(
RuntimeInvokeResponseSchema,
await cli.run(
[
"invoke",
"--runtime",
CREATED_RUNTIME_NAME,
"--session-id",
getSessionId(`${runtime.name}-egress`),
"--payload",
JSON.stringify(runtime.payload),
"--json",
],
projectDir,
),
);
expect(response.statusCode).toBeGreaterThanOrEqual(200);
expect(response.statusCode).toBeLessThan(300);
assertEgressReply(response.body);
scenarioCompleted = true;
} finally {
// Tear the stack down even when a step above failed.
await cli.run(["remove", "all", "--yes", "--json"], projectDir);
const cleanup = await cli.run(["deploy", "--yes", "--json"], projectDir);
// A cleanup error must not replace the scenario's primary diagnostic.
if (scenarioCompleted) parseResult(JsonObjectSchema, cleanup);
}
},
);
},
);

/**
* Gives the project in `projectDir` the egress agent, and allows its one host, with no credential,
* in the runtime's local box profile, which build derives the AgentCore Runtime profile from.
*/
async function useEgressAgent(projectDir: string): Promise<void> {
await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT);
const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml");
const host = new URL(EGRESS_ALLOWED_URL).host;
await writeFile(
profile,
`${await readFile(profile, "utf8")}\n[egress.checkip]\ndestinations = ["${host}"]\n`,
);
}

/** Checks the egress agent's reply: the allowed host answers, and box refuses the other one. */
function assertEgressReply(body: string): void {
const reply = EgressReplySchema.parse(JSON.parse(body));
expect(reply.allowed).toEqual({ status: 200 });
expect(reply.blocked.error).toMatch(/403/);
}

/**
* Given a deployed Box project, waits for the Runtime's logs to show that box started the agent,
* then checks they show no box error. The logs arrive a little after the invoke, so it retries.
Expand Down Expand Up @@ -558,10 +634,15 @@ async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise<void
expect(errors.stdout).not.toMatch(/ERROR|blocked by egress control|AccessDenied/);
}

/** Given a template test case, creates a project scaffolded from it and returns its path. */
/**
* Given a template test case, creates a project scaffolded from it and returns its path. A Box
* project that `deploys` gets the AGENTCORE_E2E_BOX_CDK build; one that only runs `agentcore dev`
* has no use for it.
*/
async function createTemplateProject(
cli: CliRunner,
runtime: RuntimeTemplateTestCase,
{ deploys }: { deploys: boolean },
): Promise<string> {
const parent = await mkdtemp(join(tmpdir(), "agentcore-e2e-"));
// A per-template suffix keeps concurrent projects (and their stacks) apart;
Expand All @@ -582,7 +663,7 @@ async function createTemplateProject(
for (const entry of spec.runtimes) entry.runtimeVersion = runtime.runtimeVersion;
await writeFile(specPath, `${JSON.stringify(spec, null, 2)}\n`);
}
if (runtime.box && BOX_CDK) {
if (deploys && runtime.box && BOX_CDK) {
// The pinned @aws/agentcore-cdk cannot deploy a Box project yet; use the opted-in build.
const installed = await runCommand(
"npm",
Expand Down
2 changes: 1 addition & 1 deletion src/assets/templates/a2a-python-strands/gitignore.template
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ env/

# OS
.DS_Store
Thumbs.db
Thumbs.db
5 changes: 5 additions & 0 deletions src/assets/templates/agent-python-langchain/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,14 @@ agentcore deploy
agentcore invoke --runtime {{name}} --payload '{"prompt":"Hello!"}'
```

{{#if box}}
Traces are not collected yet: the agent runs in a box, which `opentelemetry-instrument` does not
reach, so `agentcore create` sets `instrumentation.enableOtel` to `false` for this runtime.
{{else}}
Traces are collected automatically: AgentCore Runtime starts the agent under
`opentelemetry-instrument`, which picks up `opentelemetry-instrumentation-langchain`
from the dependencies.
{{/if}}

## Extending

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ env/

# OS
.DS_Store
Thumbs.db
Thumbs.db
68 changes: 0 additions & 68 deletions src/assets/templates/agent-python-strands-box/README.md

This file was deleted.

This file was deleted.

Loading
Loading