Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
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: 8 additions & 1 deletion docs/box-local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,9 @@ npm install "$L3"/aws-agentcore-cdk-*.tgz

Export `GITHUB_TOKEN` before build. Build reads it and writes its value into
`agentcore/.env.local` under the credential's reserved name `AGENTCORE_CREDENTIAL_GITHUB`.
Build does this on **every** run, so you set only the one variable the box already uses.
On a later build it replaces that value when `GITHUB_TOKEN` holds a different key, as after a
rotation, so deploy provisions the key `agentcore dev` uses. A build with `GITHUB_TOKEN` unset
keeps the stored key.
Comment thread
mquang-amazon marked this conversation as resolved.
Resolved

```
cd "$DEMO/$PROJECT"
Expand Down Expand Up @@ -219,5 +221,10 @@ bun run "$CLI" deploy
- **Deploy says a credential has no secret.** The credential's value did not reach
`agentcore/.env.local`. Export `GITHUB_TOKEN` and run build again, or set
`AGENTCORE_CREDENTIAL_GITHUB` in the deploy environment.
- **`agentcore dev` uses an old key when the shell sets none.** Earlier builds of the
box-integration branches copied each box variable into `agentcore/.env.local`, under a
`# Key for box egress '<route>' (env://<VAR>), read by box under agentcore dev` comment, and
dev still reads it there. Delete those lines (the comment and the `<VAR>=` line under it), then
export the variable in your shell instead.
- **The CDK app uses the published constructs, not yours.** Redo step 5. Confirm with
`cat agentcore/cdk/node_modules/@aws/agentcore-cdk/package.json`.
2 changes: 0 additions & 2 deletions src/assets/templates/agent-python-strands-box/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@ dependencies = [
"aws-opentelemetry-distro ~= 0.21.0",
"bedrock-agentcore[strands-agents] >= 1.18.1, < 2.0.0",
"botocore[crt] ~= 1.43.0",
# start.py reads the box profile with tomllib, which Python 3.10 does not have.
"tomli >= 2.0.0; python_version < '3.11'",
"strands-agents{{#if (eq modelProvider "Anthropic")}}[anthropic]{{else}}{{#if (or (eq modelProvider "OpenAI") (eq modelProvider "OpenAICompatible"))}}[openai]{{else}}{{#if (eq modelProvider "Gemini")}}[gemini]{{else}}{{#if (eq modelProvider "LiteLLM")}}[litellm]{{/if}}{{/if}}{{/if}}{{/if}} >= 1.62.0, < 2.0.0",
]

Expand Down
24 changes: 20 additions & 4 deletions src/assets/templates/box-codezip/start.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,16 @@
# directory from the environment through the box/agentcore and box/agentcore-codezip packs, and
# signs AWS routes with the execution role through a bare `aws://`. So there is nothing to fill in,
# no credentials to write, and no start.sh.
import json
import os
import re
import shutil
import sys

try:
import tomllib
except ModuleNotFoundError: # Python 3.10: the template depends on tomli there.
import tomli as tomllib
except ModuleNotFoundError: # Python 3.10, which has no tomllib.
tomllib = None

CODE = os.path.dirname(os.path.abspath(__file__))
DIST = os.path.join(CODE, ".box-dist")
Expand All @@ -27,12 +29,26 @@
for directory in (HOME, WORKSPACE, PROFILE_DIR):
os.makedirs(directory, exist_ok=True)

def staged_policies(path):
"""The policy files the staged profile's `policies` names.

Deploy writes `policies` on one line, with names of only letters, digits, ".", "_", "-" and
"/", so on Python 3.10 the line reads as a JSON list. The box templates reuse the folders of
the agents without box, so no template has to depend on tomli for it.
"""
with open(path, "rb") as handle:
text = handle.read()
if tomllib is not None:
return tomllib.loads(text.decode("utf-8")).get("policies", [])
match = re.search(rb"^policies = (\[.*\])$", text, re.MULTILINE)
Comment thread
mquang-amazon marked this conversation as resolved.
Resolved
return json.loads(match.group(1)) if match else []


# box reads a profile's policy files from beside it, so copy the profile and each file its
# `policies` names out of the read-only zip, into this user's folder, outside the workspace.
staged_profile = os.path.join(DIST, "profile.toml")
shutil.copyfile(staged_profile, PROFILE)
with open(staged_profile, "rb") as handle:
policies = tomllib.load(handle).get("policies", [])
policies = staged_policies(staged_profile)
for policy in policies:
destination = os.path.join(PROFILE_DIR, policy)
os.makedirs(os.path.dirname(destination), exist_ok=True)
Expand Down
138 changes: 132 additions & 6 deletions src/core/dev/box.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { afterEach, describe, expect, test } from "bun:test";
import { existsSync } from "node:fs";
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
Expand All @@ -8,6 +9,9 @@ import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project
import type { ProcessStreamer, StreamProcessOptions } from "../../io";
import { MissingToolError } from "../../io/exec";
import { BOX_INSTALL_HINT } from "../project/backends/boxRelease";
import { renderBoxProfile } from "../project/templates/boxProfile";
import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts";
import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal";
import { BoxDevRunner } from "./box";

/** The line of a CodeZip profile that names its runtime's folder. */
Expand All @@ -33,15 +37,20 @@ async function temp(prefix: string): Promise<string> {
}

/** A project named `Demo` that holds the agent's box profile in .box/agent/local when `profiled`. */
async function scene(profiled: boolean, boxOnPath = true) {
async function scene(
profiled: boolean,
boxOnPath = true,
options: { profile?: string; processEnv?: NodeJS.ProcessEnv } = {},
) {
const projectRoot = await temp("agentcore-box-project-");
await mkdir(join(projectRoot, "agentcore"));
await writeFile(join(projectRoot, "agentcore", "agentcore.json"), '{"name":"Demo"}');
if (profiled) {
const local = join(projectRoot, ".box", "agent", "local");
await mkdir(local, { recursive: true });
await writeFile(join(local, "profile.toml"), PROFILE);
await mkdir(join(projectRoot, "app", "agent", ".venv"), { recursive: true });
await writeFile(join(local, "profile.toml"), options.profile ?? PROFILE);
await mkdir(join(projectRoot, "app", "agent", ".venv", "bin"), { recursive: true });
await writeFile(join(projectRoot, "app", "agent", ".venv", "bin", "python"), "");
}

const calls: { command: string[]; options: StreamProcessOptions }[] = [];
Expand All @@ -64,6 +73,7 @@ async function scene(profiled: boolean, boxOnPath = true) {
checked.push(tool);
if (!boxOnPath) throw new MissingToolError(tool, installHint);
},
...(options.processEnv && { processEnv: options.processEnv }),
});
return { projectRoot, calls, fallbackRuns, runner, checked };
}
Expand Down Expand Up @@ -122,7 +132,7 @@ describe("BoxDevRunner", () => {
expect(fallbackRuns).toHaveLength(1);
});

test("runs the project's box profile from the project folder", async () => {
test("runs a profile written before from the project folder", async () => {
const { projectRoot, calls, fallbackRuns, runner } = await scene(true);

const events = await collect(runner.run(input(projectRoot)));
Expand All @@ -142,6 +152,28 @@ describe("BoxDevRunner", () => {
]);
});

test("starts box in the runtime's folder for a profile create writes now", async () => {
// So the agent's workspace, and the project grant, are app/agent and nothing else of the
// project: not agentcore/.env.local, which holds the model's key.
const runtime = resolveRuntimeTemplateShortcut("agent-python-strands-box", {
runtimeName: "agent",
});
const { projectRoot, calls, runner } = await scene(true, true, {
profile: renderBoxProfile("Demo", runtime)!,
});

const events = await collect(runner.run(input(projectRoot)));

expect(calls.map(({ command }) => command)).toEqual([
["box", "run", "../../.box/agent/local/profile.toml", "--no-banner"],
]);
expect(calls[0]!.options.cwd).toBe(join(projectRoot, "app", "agent"));
expect(events).toContainEqual({
type: "status",
message: "Starting the agent in a box (box run ../../.box/agent/local/profile.toml)",
});
});

test("hands box run the .env.local values, so it can attach the API key, and not dev's OTEL ones", async () => {
const { projectRoot, calls, runner } = await scene(true);

Expand All @@ -162,6 +194,96 @@ describe("BoxDevRunner", () => {
expect(env.OTEL_SERVICE_NAME).toBe(process.env.OTEL_SERVICE_NAME);
});

describe("with an env:// key in the profile", () => {
const GITHUB_PROFILE =
PROFILE +
'[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n';

test("hands box run the shell's value, and writes no .env.local", async () => {
const { projectRoot, calls, runner } = await scene(true, true, {
profile: GITHUB_PROFILE,
processEnv: { GITHUB_TOKEN: "ghp_shell" },
});

const events = await collect(runner.run({ ...input(projectRoot), env: {} }));

expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_shell");
expect(existsSync(join(projectRoot, "agentcore", ".env.local"))).toBe(false);
expect(events.some((event) => "message" in event && event.message.includes("not set"))).toBe(
false,
);
});

test("prefers the shell's value to .env.local's, and says which, with no value", async () => {
// A wide-scope GITHUB_TOKEN in a shell profile would otherwise silently replace a narrow
// project token in .env.local.
const { projectRoot, calls, runner } = await scene(true, true, {
profile: GITHUB_PROFILE,
processEnv: { GITHUB_TOKEN: "ghp_shell" },
});

const events = await collect(
runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } }),
);

expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_shell");
expect(events).toContainEqual({
type: "status",
message:
"GITHUB_TOKEN, which [egress.github] of the box profile reads, is set in this shell and " +
`in ${ENV_LOCAL_RELATIVE_PATH} to different values; box uses the shell's`,
});
expect(JSON.stringify(events)).not.toMatch(/ghp_shell|ghp_file/);
});

test("uses .env.local's value when the shell has none", async () => {
const { projectRoot, calls, runner } = await scene(true, true, {
profile: GITHUB_PROFILE,
processEnv: {},
});

await collect(runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } }));

expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_file");
});

test("uses .env.local's value, with no warning, when the shell's is blank", async () => {
// A blank shell value, such as an unset CI secret, hid the .env.local one from the check
// but not from box run, so dev warned that box would not start, and box started.
const { projectRoot, calls, runner } = await scene(true, true, {
profile: GITHUB_PROFILE,
processEnv: { GITHUB_TOKEN: "" },
});

const events = await collect(
runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } }),
);

expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_file");
expect(JSON.stringify(events)).not.toContain("GITHUB_TOKEN for [egress.github]");
});

test("warns when neither has it, before box run reports it", async () => {
const { projectRoot, calls, runner } = await scene(true, true, {
profile: GITHUB_PROFILE,
processEnv: {},
});

const events = await collect(runner.run({ ...input(projectRoot), env: {} }));

expect(events).toContainEqual({
type: "status",
message:
"the box profile .box/agent/local/profile.toml reads GITHUB_TOKEN for [egress.github], " +
"but it is not set, and box does not start without it. Export it in this shell " +
"(export GITHUB_TOKEN=...) or put it in " +
`${ENV_LOCAL_RELATIVE_PATH}, then restart dev.`,
});
// box run still starts, so its own error follows the warning.
expect(calls).toHaveLength(1);
});
});

test("runs the agent the usual way when the project has no box profile", async () => {
const { projectRoot, calls, fallbackRuns, runner } = await scene(false);

Expand Down Expand Up @@ -273,9 +395,13 @@ describe("BoxDevRunner", () => {
expect(events).toEqual([{ type: "stdout", line: "fallback" }]);
});

test("tells the user to run uv sync when the runtime has no .venv", async () => {
test.each([
["has no .venv", true],
["has the empty .venv that create --skip-install leaves", false],
])("tells the user to run uv sync when the runtime %s", async (_, removeVenv) => {
const { projectRoot, calls, runner } = await scene(true);
await rm(join(projectRoot, "app", "agent", ".venv"), { recursive: true });
const venv = join(projectRoot, "app", "agent", ".venv");
await rm(removeVenv ? venv : join(venv, "bin"), { recursive: true });

const run = collect(runner.run(input(projectRoot)));

Expand Down
60 changes: 47 additions & 13 deletions src/core/dev/box.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
import { existsSync } from "node:fs";
import { join } from "node:path";
import { existsSync, readFileSync } from "node:fs";
import { join, posix } from "node:path";
import { InputValidationError, ProjectStateError, ResourceNotFoundError } from "../../errors";
import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
import { streamProcess, type ProcessStreamer } from "../../io";
import { requireTool } from "../../io/exec";
import { BOX_INSTALL_HINT } from "../project/backends/boxRelease";
import { boxDevSecrets, missingBoxSecretWarning, shadowedBoxSecretNote } from "./boxDevSecrets";
import {
boxIngressPort,
boxLocalProfileFile,
boxLocalProfilePath,
boxStartFolder,
runsInBox,
} from "../project/templates/boxProfile";

Expand All @@ -18,24 +20,31 @@ type BoxDevRunnerConfig = {
streamProcess?: ProcessStreamer;
/** Fails when `box` is not on PATH, with the install hint; tests inject one. */
checkTool?: (tool: string, installHint: string) => Promise<void>;
/** The environment `box run` starts from, the shell's by default; tests inject one. */
processEnv?: NodeJS.ProcessEnv;
/** The platform, whose rules for variable names apply to `processEnv`; tests inject one. */
platform?: NodeJS.Platform;
};

/**
* Runs a CodeZip agent with `box run .box/<agentName>/local/profile.toml` in the project folder
* when the project has that box profile, the one `agentcore create` writes,
* and with the fallback runner otherwise. `box` is the one on PATH, which the
* user installs from the box release. The box listens on the profile's
* ingress port and relays to the agent, so the dev port must be that port.
* Runs a CodeZip agent with `box run` in the runtime's folder when the project has the agent's
* box profile, `.box/<agentName>/local/profile.toml`, and with the fallback runner otherwise.
* `box` is the one on PATH, which the user installs from the box release. The box listens on the
* profile's ingress port and relays to the agent, so the dev port must be that port.
*/
export class BoxDevRunner implements DevRunner {
private readonly fallback: DevRunner;
private readonly streamProcess: ProcessStreamer;
private readonly checkTool: NonNullable<BoxDevRunnerConfig["checkTool"]>;
private readonly processEnv: NodeJS.ProcessEnv;
private readonly platform: NodeJS.Platform;

constructor(config: BoxDevRunnerConfig) {
this.fallback = config.fallback;
this.streamProcess = config.streamProcess ?? streamProcess;
this.checkTool = config.checkTool ?? requireTool;
this.processEnv = config.processEnv ?? process.env;
this.platform = config.platform ?? process.platform;
}

public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
Expand Down Expand Up @@ -65,30 +74,55 @@ export class BoxDevRunner implements DevRunner {
"Restore the profile that `agentcore create` or `agentcore add runtime` wrote.",
);
}
const profileText = readFileSync(profile, "utf8");
const listen = boxIngressPort(input.runtime.protocol);
if (input.port !== listen) {
throw new InputValidationError(
`the box profile ${profile} listens on port ${listen}, but dev chose port ` +
`${input.port}. Free port ${listen}, then retry.`,
);
}
// `create --skip-install` leaves an empty .venv, which `uv sync` fills; the profile runs its
// Python.
const venv = join(input.projectRoot, input.runtime.codeLocation, ".venv");
if (!existsSync(venv)) {
if (!existsSync(join(venv, "bin", "python"))) {
throw new ResourceNotFoundError(
`${venv} does not exist. Run \`uv sync\` in ${input.runtime.codeLocation}, then retry.`,
`${venv} has no Python. Run \`uv sync\` in ${input.runtime.codeLocation}, then retry.`,
);
}
await this.checkTool("box", BOX_INSTALL_HINT);
if (input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
yield { type: "status", message: "Traces are not collected when the agent runs in a box" };
}
const fileEnv = credentialEnvironment(input.env);
// box reads each env:// key of the profile from its own environment, picked as build picks it:
// the shell's value when set and not blank, else agentcore/.env.local's. Dev writes neither.
const secrets = boxDevSecrets(
profileText,
{ env: this.processEnv, envLocal: fileEnv },
this.platform,
);
for (const missing of secrets.missing) {
yield { type: "status", message: missingBoxSecretWarning(profileFile, missing) };
}
for (const shadowed of secrets.shadowed) {
yield { type: "status", message: shadowedBoxSecretNote(shadowed) };
}
// box starts in the folder the profile names, the runtime's own for a CodeZip profile, so the
// agent reaches no other folder of the project; box finds the profile from there.
const startFolder = boxStartFolder(profileText);
const cwd =
startFolder === ""
? input.projectRoot
: join(input.projectRoot, ...startFolder.split("/").filter(Boolean));
const profileArg = posix.relative(startFolder, profileFile);
yield {
type: "status",
message: `Starting the agent in a box (box run ${profileFile})`,
message: `Starting the agent in a box (box run ${profileArg})`,
};
yield* this.streamProcess(["box", "run", profileFile, "--no-banner"], {
cwd: input.projectRoot,
env: { ...process.env, ...credentialEnvironment(input.env) },
yield* this.streamProcess(["box", "run", profileArg, "--no-banner"], {
cwd,
env: { ...this.processEnv, ...fileEnv, ...secrets.env },
Comment thread
mquang-amazon marked this conversation as resolved.
Resolved
signal: input.signal,
});
}
Expand Down
Loading
Loading