Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
55e6f4b
feat(box): Let a boxed agent use the MCP tools of the other gateways …
Nov 20, 2026
ba614e4
Merge box-integration into sa/box-gateway-to-gateway
Nov 21, 2026
7c9536d
fix(box): Accept a China host in the gateway host and URL inputs
Nov 21, 2026
36d4d4a
test(box): Resolve a gateway name with "-" and upper case with the bo…
Nov 21, 2026
7545175
fix(box): Give each gateway of the project its own Box gateway target…
Nov 21, 2026
801cff5
fix(box): Write a gateway target only when the CDK library of the pro…
Nov 21, 2026
743cd84
fix(remove): Remove the Box gateway target of a gateway with the gateway
Nov 21, 2026
ff0c48f
fix(box): Read a project whose build-owned gateway target names a gat…
Nov 21, 2026
a043718
fix(box): Stop build when two gateways of the project get one target …
Nov 21, 2026
869d590
fix(box): Add the server of a gateway named constructor to the Runtim…
Nov 21, 2026
e095a84
fix(box): Give the CUSTOM_JWT gateway notice once, at add gateway, an…
Nov 21, 2026
52f88f1
fix(box): Ask the CDK library about a whole gateway target, as its sc…
Nov 21, 2026
3d739f2
Merge box-integration into sa/box-gateway-to-gateway
Nov 21, 2026
2f39864
fix(schema): Skip the passthrough.gateway check only for an egress- t…
Nov 21, 2026
2f55c31
fix(box): Say why build could not check the CDK library for passthrou…
Nov 21, 2026
1721f47
fix(box): Give the CUSTOM_JWT gateway notice also when add runtime ad…
Nov 21, 2026
33c29a1
docs(box): Name the check parameter and add runtime in the comments o…
Nov 21, 2026
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
23 changes: 20 additions & 3 deletions docs/box-local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,17 @@ A profile that names a pack `box/<name>` fails: box refuses it and names the `@b
`mcp:call`. A host the gateway already has a target for keeps that target. Build owns
only the targets whose name starts with `egress-`: it adds them, changes them, and removes
one when no host needs it. It never changes another target.
- **The other gateways of the project.** A runtime without a box gets each gateway without
`boundRuntime` in `AGENTCORE_GATEWAY_<NAME>_URL`. For a box runtime, each of these gateways gets
the target `egress-gateway-<name>` on `<runtime>-box-egress`, with `passthrough.gateway` set to
the gateway's name. The L3 sets the target's endpoint to that gateway's URL, gives the Box
gateway's role `bedrock-agentcore:InvokeGateway` on that gateway only, and sets
`AGENTCORE_GATEWAY_<NAME>_URL` and `_HOST` on the runtime. A `PRIVATE_VPC` runtime gets none of
them. A `CUSTOM_JWT` gateway gets no target, and `agentcore add gateway`, and `agentcore add runtime` for a
box runtime, give one notice for it. You write nothing for them. A profile
entry that signs for a gateway host with `aws://` stops build. Build writes these targets only when
the `@aws/agentcore-cdk` in `agentcore/cdk` accepts `passthrough.gateway`: it asks that library
with `node`. Otherwise build writes none of them, and gives one warning.
- **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret
sends an API key from AgentCore Identity, and an entry with no secret sends no credential.
- **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard
Expand Down Expand Up @@ -241,13 +252,18 @@ A profile that names a pack `box/<name>` fails: box refuses it and names the `@b
the Runtime's Python, in every table: the agent, each stdio `[mcp.<name>]` server, each
`[tool.<name>]`;
- the `@box/agentcore` packs, the project name, and the build region come in, and each CloudWatch
target signs with the execution role.
target signs with the execution role;
- with `instrumentation.enableOtel` on, which is the default for a box template too, a command
of the Python of the venv starts with `opentelemetry-instrument`. On CodeZip, the
Python of the Runtime runs the script in the zip, `<code>/bin/opentelemetry-instrument`. The
`@box/agentcore` pack gives the agent the ADOT variables and the `OTEL_RESOURCE_ATTRIBUTES`
that the Runtime sets. When your `[agent.env]` sets one of these variables, box uses your value.
The pack sets no `OTEL_EXPORTER_OTLP_*` variable, because box sets each one.
The pack sets no `OTEL_EXPORTER_OTLP_*` variable, because box sets each one;
- each other gateway of the project gets `[mcp.<gateway>]`, to the host that `@box/agentcore`
reads from `AGENTCORE_GATEWAY_<NAME>_HOST`, through its `egress-gateway-<name>` target. The agent
gets `AGENTCORE_GATEWAY_<NAME>_URL`, so the code that calls the gateway without a box works in
the box. Box permits each tool of the server, and a forbid rule of your policy still applies.
A server of your profile with the name of a gateway stops build.

**The default log target.** With no `cloudwatch_logs` target, the Runtime profile gets
`[telemetry.agentcore]`: box sends its deny, permit, and trace records to the log group of the
Expand Down Expand Up @@ -286,7 +302,8 @@ A profile that names a pack `box/<name>` fails: box refuses it and names the `@b

- **No-auth targets need a newer L3.** A passthrough target with no outbound auth synthesizes
only with an `@aws/agentcore-cdk` that accepts it. Until that release is pinned, use a
local L3 build, as in step 5.
local L3 build, as in step 5. A target with `passthrough.gateway` also needs an L3 that
accepts that field.

## 5. Point the generated CDK app at the local L3 tarball

Expand Down
80 changes: 79 additions & 1 deletion src/core/project/backends/cdk/compatibility.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@ import { afterEach, describe, expect, test } from "bun:test";
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { cdkCompatibilityWarning, MINIMUM_COMPATIBLE_CDK_VERSION } from "./compatibility";
import {
cdkAcceptsPassthroughGateway,
cdkCompatibilityWarning,
MINIMUM_COMPATIBLE_CDK_VERSION,
} from "./compatibility";

const tempDirectories: string[] = [];

Expand Down Expand Up @@ -57,3 +61,77 @@ describe("cdkCompatibilityWarning", () => {
expect(await cdkCompatibilityWarning(directory)).toBeUndefined();
});
});

describe("cdkAcceptsPassthroughGateway", () => {
/** A CDK app whose @aws/agentcore-cdk has the module text `index`. */
async function cdkDirectoryWithIndex(index: string | undefined): Promise<string> {
const directory = await mkdtemp(join(tmpdir(), "agentcore-cdk-passthrough-gateway-"));
tempDirectories.push(directory);
if (index === undefined) return directory;
const packageDirectory = join(directory, "node_modules", "@aws", "agentcore-cdk");
await mkdir(packageDirectory, { recursive: true });
await writeFile(
join(packageDirectory, "package.json"),
JSON.stringify({ name: "@aws/agentcore-cdk", version: "1.1.0", main: "index.js" }),
);
await writeFile(join(packageDirectory, "index.js"), index);
return directory;
}
/** A library that exports `AgentCoreGatewayTargetSchema` as `schema`, a JS text. */
const exporting = (schema: string) => `exports.AgentCoreGatewayTargetSchema = ${schema};\n`;
/** As each @aws/agentcore-cdk parses the passthrough of a target: with `gateway`, or `endpoint` only. */
const WITH_GATEWAY = exporting(
"{ safeParse: (target) => ({ success: typeof target.passthrough.gateway === 'string' }) }",
);
const ENDPOINT_ONLY = exporting(
"{ safeParse: (target) => ({ success: typeof target.passthrough.endpoint === 'string' }) }",
);
const withNode = test.skipIf(!Bun.which("node"));

withNode("accepts when the installed library accepts passthrough.gateway", async () => {
expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(WITH_GATEWAY))).toEqual({
accepts: true,
});
});

withNode.each([
["requires passthrough.endpoint", ENDPOINT_ONLY],
["has no AgentCoreGatewayTargetSchema", "exports.Other = 1;\n"],
])("refuses when the installed library %s", async (_, index) => {
expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(index))).toEqual({
accepts: false,
reason: "refuses",
});
});

withNode("says that the library is not installed", async () => {
expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(undefined))).toEqual({
accepts: false,
reason: "not-installed",
});
});

withNode("says that the check failed, with the error of the library", async () => {
const directory = await cdkDirectoryWithIndex('throw new Error("the library is broken");\n');
expect(await cdkAcceptsPassthroughGateway(directory)).toEqual({
accepts: false,
reason: "failed",
detail: "the library is broken",
});
});

withNode("says that the check took too long", async () => {
const directory = await cdkDirectoryWithIndex("while (true) {}\n");
expect(await cdkAcceptsPassthroughGateway(directory, { timeoutMs: 500 })).toEqual({
accepts: false,
reason: "timed-out",
});
});

test("says that build cannot run node", async () => {
const directory = await cdkDirectoryWithIndex(WITH_GATEWAY);
expect(
await cdkAcceptsPassthroughGateway(directory, { node: "/nonexistent/agentcore-test/node" }),
).toEqual({ accepts: false, reason: "no-node" });
});
});
69 changes: 69 additions & 0 deletions src/core/project/backends/cdk/compatibility.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import { execFile } from "node:child_process";
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { promisify } from "node:util";
import semver from "semver";

export const MINIMUM_COMPATIBLE_CDK_VERSION = "1.0.0";
Expand Down Expand Up @@ -31,3 +33,70 @@ export async function cdkCompatibilityWarning(cdkDirectory: string): Promise<str
`Update the CDK dependency, then rebuild or redeploy.`
);
}

/**
* The script that asks the @aws/agentcore-cdk that the CDK app loads whether its schema takes a
* passthrough target with `gateway` in place of `endpoint`, as build writes it. It parses a whole
* target, because the library gives `gateway` a passthrough schema of its own. It prints
* `accepts`, `refuses`, `not-installed`, or `failed` and the error.
*/
const PASSTHROUGH_GATEWAY_CHECK = `
let library;
try {
library = require("@aws/agentcore-cdk");
} catch (error) {
const missing = error && error.code === "MODULE_NOT_FOUND" && /@aws\\/agentcore-cdk/.test(String(error.message));
process.stdout.write(missing ? "not-installed" : "failed " + (error && error.message));
process.exit(0);
}
const schema = library.AgentCoreGatewayTargetSchema;
const accepts =
schema !== undefined &&
schema.safeParse({
name: "egress-gateway-check",
targetType: "passthrough",
passthrough: { gateway: "check", protocolType: "CUSTOM" },
outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-east-1" },
}).success === true;
process.stdout.write(accepts ? "accepts" : "refuses");
`;

/** The answer of {@link cdkAcceptsPassthroughGateway}, with the reason when it is not `accepts`. */
export type PassthroughGatewayCheck =
| { readonly accepts: true }
| {
readonly accepts: false;
readonly reason: "refuses" | "not-installed" | "no-node" | "timed-out" | "failed";
readonly detail?: string;
};

/**
* Asks the @aws/agentcore-cdk of the CDK app in `cdkDirectory` whether it accepts
* `passthrough.gateway`. Node runs the check in that folder, so it loads the same library as synth.
* Each answer other than `accepts` says why: the library refuses the field, is not installed, the
* check took more than `timeoutMs`, `node` is not there, or the check failed.
*/
export async function cdkAcceptsPassthroughGateway(
cdkDirectory: string,
options: { readonly node?: string; readonly timeoutMs?: number } = {},
): Promise<PassthroughGatewayCheck> {
let stdout: string;
try {
({ stdout } = await promisify(execFile)(
options.node ?? "node",
["-e", PASSTHROUGH_GATEWAY_CHECK],
{ cwd: cdkDirectory, timeout: options.timeoutMs ?? 60_000 },
));
} catch (error) {
const failure = error as NodeJS.ErrnoException & { killed?: boolean; stderr?: string };
if (failure.code === "ENOENT") return { accepts: false, reason: "no-node" };
if (failure.killed) return { accepts: false, reason: "timed-out" };
const detail = (failure.stderr ?? failure.message).trim().split("\n")[0];
return { accepts: false, reason: "failed", ...(detail && { detail }) };
}
const answer = stdout.trim();
if (answer === "accepts") return { accepts: true };
if (answer === "refuses" || answer === "not-installed") return { accepts: false, reason: answer };
const detail = answer.replace(/^failed\s*/, "");
return { accepts: false, reason: "failed", ...(detail && { detail }) };
}
2 changes: 1 addition & 1 deletion src/core/project/boxMemory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ function boxGatewayFor(spec: ProjectSpec, runtime: ProjectRuntime): AgentCoreGat
*/
function servesTarget(targets: readonly AgentCoreGatewayTarget[], wanted: AgentCoreGatewayTarget) {
const endpoint = (target: AgentCoreGatewayTarget) =>
target.passthrough && new URL(target.passthrough.endpoint).host;
target.passthrough?.endpoint && new URL(target.passthrough.endpoint).host;
return targets.some(
(target) => target.name === wanted.name || endpoint(target) === endpoint(wanted),
);
Expand Down
24 changes: 19 additions & 5 deletions src/core/project/boxNetwork/egress.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { z } from "zod";
import { BOX_EGRESS_TARGET_PREFIX } from "../../../projectSchemas/project";
import type { BoxEgressAuth } from "./network";
import type { FailureCode } from "./types";

Expand Down Expand Up @@ -132,6 +133,12 @@ const AWS_ENDPOINTS = [
api: "lambda-url",
service: "lambda",
},
{
pattern:
/^[a-z0-9][a-z0-9-]*\.gateway\.bedrock-agentcore\.([a-z0-9-]+)\.amazonaws\.com(?:\.cn)?$/,
api: "gateway",
service: "bedrock-agentcore",
},
] as const;

/** The API of an AWS endpoint that the gateway signs for. */
Expand All @@ -154,11 +161,7 @@ export function signingService(host: string): { service: string; region: string
return endpoint && { service: endpoint.service, region: endpoint.region };
}

/**
* The start of the name of each target that build adds to a Box gateway. Build manages every
* target whose name has it, and no other.
*/
export const BOX_EGRESS_TARGET_PREFIX = "egress-";
export { BOX_EGRESS_TARGET_PREFIX };

/**
* The gateway target name build gives `name`: {@link BOX_EGRESS_TARGET_PREFIX}, then the letters
Expand Down Expand Up @@ -191,6 +194,17 @@ export function outboundAuthFor(
if (!secret) return { ok: true, auth: { kind: "none" } };
const [scheme, value = ""] = secret.ref.split("://", 2);
if (scheme === "aws") {
if (awsEndpoint(host)?.api === "gateway") {
return {
ok: false,
code: "UNSIGNABLE_HOST",
reason:
`signs requests to ${host}, the host of an AgentCore gateway, with ${secret.ref}. ` +
"Build signs only for the gateways of this project, and it adds the route to each of " +
"them on AgentCore Runtime itself, as [mcp.<gateway name>], with the host that the " +
"deploy gives the gateway. Remove this entry. To call a gateway, add it to this project.",
};
}
const signing = signingService(host);
if (!signing) {
return {
Expand Down
Loading
Loading