Repository navigation
feat(box): Let a boxed agent use the MCP tools of the other gateways of its project - #2887
SaiAbhishek98 wants to merge 17 commits into
Conversation
…of its project
## Problem
A runtime without a box gets the URL of each gateway of its project in
`AGENTCORE_GATEWAY_<NAME>_URL`, and its code uses the MCP tools of that gateway. A boxed agent on
AgentCore Runtime cannot do this. Its box has no route to the host of the gateway, so the box
refuses each request. The user cannot add the route. Build refuses `aws://` for a gateway host
with `UNSIGNABLE_HOST`, and the ID of the gateway is not known before the first deploy. A target
and a grant that you make by hand operate, but build does not keep them in `agentcore.json`.
## Solution
- **Which gateways.** A box runtime gets each gateway without `boundRuntime`, the same gateways
that the L3 binds to a runtime without a box (`projectGatewaysOf`). A `PRIVATE_VPC` runtime gets
none. A `CUSTOM_JWT` gateway gets a warning and no target, because the Box gateway signs only
with its role.
- **The target.** Build writes `egress-gateway-<name>` on the Box gateway of the runtime, with
`passthrough.gateway: "<name>"` and `GATEWAY_IAM_ROLE` for `bedrock-agentcore` in the build
region. A `NONE` gateway gets no outbound auth. Build changes and removes the target as it does
each other `egress-` target. A host of the profile cannot use its name
(`TARGET_NAME_COLLISION`), and the limit of 100 targets counts it.
- **The schema.** `passthrough` can have `gateway` or `endpoint`, but not the two.
The name must be a gateway of the project without `boundRuntime`, and not the gateway of the
target.
- **The pack.** The `@box/agentcore` pack of each box runtime declares `gateways.<name>.url` from
`env:<prefix>_URL` and `gateways.<name>.host` from `env:<prefix>_HOST`, each with a pattern. The
agent gets `<prefix>_URL` in `[agent.env]` from the input, so the code that uses the gateway
without a box operates in the box.
- **The Runtime profile.** Only the Runtime profile gets `[mcp.<name>]`, with
`destinations = ["${{ inputs.gateways.<name>.host }}"]` and one backend to the URL of the Box
gateway and `/egress-gateway-<name>`, signed with `aws://` for `bedrock-agentcore`. Box adds a
permit for each tool of a declared server, and a forbid rule of the policy stays. The local
profile does not change. A server of the local profile with the name of a gateway stops build
(`RUNTIME_GATEWAY_SERVER_NAME_TAKEN`).
- **Gateway hosts in the profile.** `AWS_ENDPOINTS` has the gateway host, with the service
`bedrock-agentcore`. An entry that signs for a gateway host with `aws://` stops build with
`UNSIGNABLE_HOST`, and the message names the route that build adds. Build cannot tell a gateway
of this project from a gateway of a different project by its host, because the ID of a gateway
is known only after deploy.
- **IAM warnings.** `boxGatewayIamWarnings` gives no warning for a target with
`passthrough.gateway`, because the L3 gives the grant. It gives a warning for a target to a gateway host
when the role has no `bedrock-agentcore:InvokeGateway`.
- **Interfaces that changed.** `PassthroughConfigSchema` (`endpoint` is optional, `gateway` is
new), `BoxNetwork.projectGateways`, `RuntimeProfileContext.projectGateways`,
`renderAgentCorePack(spec, gateways)`, and the problem code
`RUNTIME_GATEWAY_SERVER_NAME_TAKEN`.
- **Dependency.** The target needs the L3 branch `sa/box-gateway-to-gateway` of
aws/agentcore-l3-cdk-constructs. That branch gives the endpoint, the grant, and
`<prefix>_HOST`.
- **Not done.** box 0.1.11-preview.10 takes an input in `destinations` only when its value is a
host. Thus the pack reads `<prefix>_HOST` and not the URL. If the CLI wrote the target from
`deployed-state.json`, each new project must deploy two times.
## Tests
- `src/core/project/boxNetwork/network.test.ts`, "the gateways of the project": the gateways that
the agent gets, a `PRIVATE_VPC` runtime, a `CUSTOM_JWT` gateway, the name collision, the target that
build wrote, the limit of 100, and the refusal of a signed gateway host in `[egress]` and
`[mcp]`. "boxGatewayIamWarnings for a gateway of the project" pins the two warnings.
- `src/core/project/boxNetworkWriters.test.ts`, "gatewayTargetsWriter for the gateways of the
project": the writer adds, changes, and removes the target. "stages the inputs of each gateway
that the agent calls in the @box/agentcore pack" pins the staged pack.
- `src/core/project/runtimeProfile/rules/gateway.test.ts`, "the gateway rule for a gateway of the
project": the `[mcp.<name>]` server, no server with no gateway, and the stop for a server name
that a gateway has.
- `src/core/project/templates/boxProfile.test.ts`, "for a gateway of the project that the agent
calls" (a test name): the two inputs, the agent variable, and the host and URL patterns.
- `src/projectSchemas/project.test.ts`, "a passthrough target that names a gateway": the spec that
it accepts and the five refusals.
- `src/core/project/boxNetwork/projectGateways.test.ts`: the two target shapes. "the box on PATH"
operates box 0.1.11-preview.10 on the Runtime profile and the pack that build makes, with the
variables that the L3 sets. Box resolves the server to the host, the backend to the target, the
agent variable to the URL, and adds its `net:connect` permit for the host. The test skips when no
box is on `PATH`.
- Without the change in `src/`, 35 of the 265 tests of these six files fail. Each of 19 mutations
of `src/` fails one or more of these tests.
- `bun test` with box 0.1.11-preview.10 on `PATH`: 5867 pass, 6 skip, 1 fail. The one failure is "the box on
PATH > resolves a profile into the rules the tests fake" in `boxProfileResolver.test.ts`. It
fails on `upstream/box-integration` too, with this box. CI has no box, so CI skips it.
- `bun run typecheck`, `bun run lint:check`, and `bun run format:check` pass.
- Live test in a test account in us-west-2: a new project from this branch and the L3 branch, with a
second gateway `toolsgw` (`AWS_IAM`) and one Lambda target that gives a known answer. I added the
gateway and the target with `agentcore add gateway` and `agentcore add gateway-target`. I did not
change the box profile, the targets of the Box gateway, or IAM. One deploy made the target, the
grant, and the variables. The agent used `echo___known_answer` and gave the known answer
`gw2gw-known-answer-7319`. Box logged a permit for `mcp:call toolsgw/echo___known_answer`, the
Box gateway sent the request to `egress-gateway-toolsgw`, and `toolsgw` logged the tool call and
the known answer. The test project only had these changes: agent code that uses the gateway,
`enableApplicationLogs` on `toolsgw`. I did `agentcore deploy` two more times for that agent code. `add gateway`
gives `protocolType: "None"`, so `_URL` has no `/mcp`, and the agent code must add it, the same
as without a box.
- I did not do these: `bun run test:e2e`, `bun run audit`, `bun run secrets:check`, and `bun run build`.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## box-integration #2887 +/- ##
===================================================
+ Coverage 96.80% 96.81% +0.01%
===================================================
Files 766 767 +1
Lines 66928 67245 +317
===================================================
+ Hits 64790 65105 +315
- Misses 2138 2140 +2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
leo237
left a comment
There was a problem hiding this comment.
Thanks for this. The design holds together: the CLI writes the target, the L3 resolves the endpoint and the grant in the same stack, and the agent reads the same AGENTCORE_GATEWAY_<NAME>_URL it reads without a box. I checked the parts I was worried about and they're fine:
- The Box gateway itself isn't selected, because it has
boundRuntime, so there's no self-loop. - Two gateways with the same prefix are already a schema error (the existing
discoveryPrefixcollision check). gatewayDiscoveryPrefixmatches the existing non-box naming.- The L3 #478 grant is scoped to the named gateway only.
- Nothing internal shows up in the diff or the commit message.
- The must-survive fixes from earlier PRs are all still in place:
inputs.gateway.url,inputs.aws.region,writesBedrockRoute,tomlKey, the xray grants, theenableApplicationLogsnotice, the preview.10 pin and--containment.
CI is green on 55e6f4b (Linux/macOS/Windows verify, CodeQL, e2e CodeBuild). The branch is 2 commits behind box-integration (#2884) and merges into it cleanly.
Blocking
-
Merging now breaks the deploy of an existing Box project that has another gateway.
box-integrationpins@aws/agentcore-cdk1.1.0 insrc/assets/cdk/package.json. At v1.1.0 the L3PassthroughConfigSchemais.strict()and requiresendpoint. aws/agentcore-l3-cdk-constructs#478 is still open and unmerged, and v1.2.0 doesn't have it either. With this PR, build writes anegress-gateway-<name>target with onlypassthrough.gatewayfor every unboundAWS_IAM/NONEgateway. The user doesn't have to do anything for this to happen, so any Box project with one more gateway will fail synth on the pinned L3. Today that same project deploys: its boxed agent just can't reach the gateway. The NONE-auth note indocs/box-local-testing.mdis opt-in, and this isn't. Please do one of these: hold this PR (draft) until #478 ships and the pin is bumped in the same PR; gate it behind an L3 version check or a flag; or make it explicitly opt-in until then. (The PR body's Follow-ups still say the L3 change "is not a pull request yet". It is #478 now.) -
agentcore remove gateway <name>fails after one build. Once build has writtenegress-gateway-<name>withpassthrough.gateway: "<name>", removing that gateway leaves the reference dangling.commitSpecre-validates withProjectSpecSchema, and the new refine rejects it ("...names the gateway ... but the project has no gateway of that name. Name a gateway of this project without boundRuntime"). Build never runs, so it can't prune the target. The user has to know to runremove gateway-target egress-gateway-<name> --gateway <runtime>-box-egressfirst, for each box runtime. Hand-addingboundRuntimeto that gateway hits the same error. The writer test "removes the target of a gateway that the agent no longer calls" bypasses the schema, so this path isn't covered. Suggested fix:removeResourceforgatewayshould also drop the build-ownedpassthrough.gatewaytargets that name it, with a test. Alternatively, the refine could tolerate a dangling reference in a build-ownedegress-target and let build prune it.
Non-blocking
- Names with
-or uppercase.GatewayNameSchemaallowsmy-gw/MyGw. That produces[inputs.gateways.my-gw.url]and${{ inputs.gateways.my-gw.host }}. The TOML side is fine. What I couldn't verify is whether box's${{ }}expression parser accepts-in an input path segment. Memory names never contain-, so there's no precedent. The box-on-PATH test and the live test only usetools/toolsgw. Could you add a hyphenated name to the box-on-PATH test, or normalize the input key? - Target-name collisions.
targetNameForcollapses runs of non-alphanumerics and truncates to 93 chars. Soa--banda-bboth map toegress-gateway-a-b, and so do two 100-char names that share a long prefix. Their prefixes differ (A__BvsA_B), so the prefix check doesn't catch this, and the writer would push two targets with the same name. A collision check inprojectGatewaysOfwould make this fail loudly instead. - China partition.
PROJECT_GATEWAY_HOST_PATTERN/_URL_PATTERNstop atamazonaws.com.AWS_ENDPOINTSaccepts(?:\.cn)?, and #2883 adds.amazonaws.com.cnfor the Bedrock/Memory hosts. In a China build, box would refuse the input when the run starts. That failure is loud, and the existingGATEWAY_URL_PATTERNhas the same gap, but the two patterns should agree once #2883 lands. - Box permits every tool of each project gateway automatically. This matches what a runtime without a box gets, and the docs cover it. Still, it widens the boxed agent's reach without the user writing anything. Consider saying so in a build message (e.g. "adding gateway target ... the agent may call every tool of ''"), or offering an opt-out.
- The CUSTOM_JWT warning repeats on every build for every box runtime. A JWT gateway that is meant for external clients only will warn forever. Consider a way to acknowledge it.
- Interaction with #2877. #2877 (open) moves build-owned targets from the
egress-prefix to the record inagentcore/box-gateway-targets.json. Whichever PR lands second has to record theegress-gateway-*targets as build-owned. The trial merge with #2877 conflicts indocs/box-local-testing.mdandboxNetwork/network.test.ts. - Trial merges with the other open PRs. #2883 is clean. #2885 conflicts in
docs/box-local-testing.md,boxNetworkWriters.tsandtemplates/boxProfile.ts. #2886 conflicts indocs/box-local-testing.md. - Back-merge. This also needs a back-merge to
box-integration-development. boxMemory.ts. The one-line change (passthrough?.endpoint &&) is correct for the now-optionalendpoint.
Review feedback: the `<prefix>_HOST` and `<prefix>_URL` patterns of `@box/agentcore` stopped at `amazonaws.com`, and the gateway host of `AWS_ENDPOINTS` also accepts `amazonaws.com.cn`. Thus box refused the two inputs in a China region. Each pattern now accepts `amazonaws.com.cn`. Test: "the host pattern takes ... amazonaws.com.cn: true" and "the URL pattern takes https://....amazonaws.com.cn/mcp: true" in `boxProfile.test.ts` fail before this change.
…x on PATH
Review question: a gateway name can hold "-" and upper case, so the Runtime profile has
`${{ inputs.gateways.My-Tools-GW.host }}` and `[mcp.My-Tools-GW]`. The test "the box on PATH" now
also uses the gateway `My-Tools-GW`. box 0.1.11-preview.10 resolves the input, the server, the
backend, the agent variable, and the permit `context.input.server == "My-Tools-GW"`.
No code changes, because box accepts these names. This test does not fail before this commit. It
pins the behaviour, and it skips when no box is on PATH.
… name Review feedback: `targetNameFor` changes `--` to `-` and cuts a name at 100 characters. Thus the gateways `a--b` and `a-b`, or two long names with the same start, got the same target name, and the writer added two targets with one name. The target name stays `egress-gateway-<name>` when that name keeps the gateway name whole. When `targetNameFor` changes the name, the target name ends in 8 hex digits of the SHA-256 of the gateway name, and it has at most 100 characters. The name is the same on each build. Test: "is not the same for a--b and a-b" and "is not the same for" two names of 96 characters with the same start, in `projectGateways.test.ts`, fail before this change.
…ject accepts it
Review feedback (blocking): `@aws/agentcore-cdk` 1.1.0, which `box-integration` pins, has a
strict `PassthroughConfigSchema` that requires `endpoint`. It refuses `passthrough.gateway`. Build
wrote that target for each gateway without `boundRuntime` of a Box project, so the synth of such a
project failed until a new library ships.
Build now asks the library of the CDK app, with `node` in `agentcore/cdk`, whether
`PassthroughConfigSchema` accepts `{ gateway, protocolType }` (`cdkAcceptsPassthroughGateway`).
Thus it reads the same library as synth, and a local build of the library works too. A version
number cannot tell this, because aws/agentcore-l3-cdk-constructs has not released the change, and
a local build of its `box-integration` branch has the version 1.0.2. Build asks only when a box
runtime and a gateway without `boundRuntime` are in the project. When the library refuses the
field, is not there, or the check fails, build writes no target, no server, and no pack input. It
removes a target that it wrote before, and gives one warning that names the gateways. The manager
takes the check in `cdkAcceptsPassthroughGateway`, so tests do not run `node`. Equal warnings of two
box runtimes show once.
Tests that fail before this change:
- `compatibility.test.ts`, "cdkAcceptsPassthroughGateway": true for a library that accepts the
field, false for one that requires `endpoint`, and false with no library or no schema.
- `network.test.ts`, "gives the agent no gateway when the @aws/agentcore-cdk of the project
refuses passthrough.gateway, and warns once".
- `manager.boxNetwork.test.ts`, "writes no target and no server, and warns once, when it does
not". The test "writes the target and the server when the @aws/agentcore-cdk of the project
accepts passthrough.gateway" pins the other case.
I also ran the check on two real libraries: `@aws/agentcore-cdk` 1.1.0 from npm gives false, and
the build of aws/agentcore-l3-cdk-constructs branch `sa/box-gateway-to-gateway` gives true.
Review feedback (blocking): after one build, each Box gateway has the target `egress-gateway-<name>` with `passthrough.gateway: "<name>"`. `agentcore remove gateway <name>` kept that target, the project schema refused the new spec because the target names no gateway, and thus the user could not remove the gateway, and build could not remove the target. `removeResource` now also removes, from each other gateway, each target that build owns (its name starts with `egress-`) and that names the removed gateway in `passthrough.gateway`. A target of the user's that names the gateway stays, and the schema still refuses it with its name, so build never removes a target that the user wrote. I did not make the schema accept a target that names no gateway, because the spec then is not valid for the CDK library until the next build. Test: `manager.boxNetwork.test.ts`, "lets remove gateway remove the gateway after a build, with the target build wrote for it", fails before this change with the schema error. It builds, removes the gateway, and then builds again. The user's own target stays.
leo237
left a comment
There was a problem hiding this comment.
Re-review at 743cd84 (since 55e6f4b: merge of box-integration, plus 5 fix commits). Both earlier blockers are fixed. Approving.
Earlier blockers
- Deploy breaks for existing Box projects (CDK 1.1.0 refuses
passthrough.gateway): fixed in 801cff5.cdkAcceptsPassthroughGatewayrunsnode -einagentcore/cdk. That loads the same@aws/agentcore-cdkthat synth loads, and it callsPassthroughConfigSchema.safeParse({ gateway, protocolType }). I checked the L3 side. At the #478 head the package is CJS (exports["."].require) and re-exportsPassthroughConfigSchemathroughexport * from './schema'. On 1.1.0 the schema is strict and needsendpoint, so the probe returns false. On #478 it returns true. When the answer is unknown it is safe: a missing library, a missingnode, a throw or a timeout all givefalse. Build then writes no target, no[mcp]server and no pack input, drops any target it wrote before, and gives one deduplicated warning. Whennode_modulesis missing, synth already stops with "CDK dependencies are missing", so a first build beforenpm installis fine. Tests cover accepts / refuses / not installed / no export (gated onBun.which("node")), the network model withprojectGatewayTargets: false, and both manager paths through an injected probe. remove gatewayfails after one build: fixed in 743cd84.removeResourcenow drops each build-owned target (egress-prefix) whosepassthrough.gatewaynames the removed gateway. A user target that names it stays and is still refused by name, which is correct. The new manager test runs through the real manager andcommitSpec(with schema validation). It removes after a build, keeps the user's target, and builds again with no target coming back. #2877 is still open and not on base, so there is nobox-gateway-targets.jsonrecord to update yet.
Other earlier items
- China hosts: fixed in 7c9536d.
([.]cn)?is on the host and URL patterns, with a negative test for….cn.evil.example.com. - Target-name collisions: fixed in 7545175. Names that survive
targetNameForunchanged keepegress-gateway-<name>, so nothing tested live is renamed. Changed names get an 8-hex SHA-256 suffix, stay at most 100 chars, and are the same on every build. Tests covera--bvsa-band long names that share a prefix. No migration is needed because nothing has shipped. -/uppercase gateway names in inputs: partly addressed in 36d4d4a. The box-on-PATH test now also coversMy-Tools-GWand checks the input, server, backend, agent env and policy. It is gated on a box with--format json --full, so CI never runs it; the commit message says box 0.1.11-preview.10 passes it locally. That is fine as a pin.- Merge ba614e4: clean. The PR's diff against the new base is identical, apart from hunk headers, to its diff at 55e6f4b against the old merge-base: 17 files, +875/-40. So no PR change was lost and no #2883/#2884 change was reverted.
- Still open (non-blocking): automatic tool access (a message or opt-out); the
CUSTOM_JWTwarning repeats on every build (the newSetonly dedupes across runtimes in one build); the interaction with #2877 once it lands; back-merge to dev.
New nits (non-blocking)
- PR body: the top says it depends on aws/agentcore-l3-cdk-constructs#478, but Follow-ups still says the L3 change "is not a pull request yet". With the probe, merging before #478 now degrades to a warning, not a broken synth. The body could say that.
- The warning always says the library "does not accept passthrough.gateway", even when the probe failed for another reason (see inline).
No internal references in the diff or commit messages. Test patterns look safe: tmpdir paths, and node/box spawns gated on PATH.
CI at 743cd84: CodeQL, Analyze, verify / Windows, verify / macOS and CodeBuild e2e pass. verify / Linux was still pending when I posted, so this approval assumes it goes green. e2e is skipped.
…eway that it cannot call Review feedback: after a build, a gateway of the project that gets `boundRuntime`, or that is removed from agentcore.json by hand, left the target `egress-gateway-<name>` with a reference that the project schema refused. Each command then stopped when it read agentcore.json, so build could not remove the target. The schema does not do this check for a target whose name starts with `egress-` (`BOX_EGRESS_TARGET_PREFIX`), because build writes and removes each such target. The next build removes the target. A target of the user that names such a gateway is still refused. The prefix moves to `projectSchemas/project.ts`, and `boxNetwork/egress.ts` exports it from there. Tests that fail before this change: `manager.boxNetwork.test.ts`, "reads the project and removes the target after a build when the gateway gets boundRuntime" and "reads the project and removes the target when the gateway is gone from agentcore.json". `project.test.ts`, "accepts a target that build owns and that names ...", pins the schema. The refusals in that file now use a target of the user.
…name Review feedback: `hostTargets` put the target of each gateway of the project in `owners` with `owners.set`. When two gateways got one target name, the second name replaced the first one with no report, and the writer added two targets with one name. The target names of 7545175 already differ for gateway names that share their first 90 characters: the test now has "a".repeat(90) + "x1" and + "x2". A gateway can still have, as its name, the name that a different gateway gets with its hash, for example `a--b` and `a-b-<hash of a--b>`. Build now stops with `TARGET_NAME_COLLISION` for two gateways with one target name, as it does for two hosts. Thus the writer never runs with two targets of one name. Test: `network.test.ts`, "fails two gateways whose targets still have one name, as for two hosts", fails before this change. `projectGateways.test.ts`, "is not the same for" the two names of 92 characters, passes before and after.
…e profile Review feedback: the gateway rule checked `gateway.name in mcp`, which is true for a key that each object has from its prototype. Thus a gateway named `constructor` or `toString` stopped build with `RUNTIME_GATEWAY_SERVER_NAME_TAKEN`. The rule now uses `Object.hasOwn(mcp, gateway.name)`. Test: `gateway.test.ts`, "adds the server of a gateway whose name is a key of every object, such as constructor", fails before this change.
…d not on each build Review feedback: build gave the warning for a `CUSTOM_JWT` gateway on each build, one time for each boxed runtime. The CLI gives a notice about a resource when a command writes that resource: `create` and `add runtime` give the notices of the Box gateway logs and of the default log target. This change does the same. `agentcore add gateway` gives `customJwtGatewayNotice` one time, after it writes a `CUSTOM_JWT` gateway without `boundRuntime` to a project that has a boxed runtime that is not `PRIVATE_VPC`. Build gives no warning for the gateway. I did not add an opt-out, because a notice at the write is simpler and is what the CLI does for its other notices. Tests that fail before this change: `network.test.ts`, "gives the agent no route to a CUSTOM_JWT gateway, and no warning on each build", and `manager.boxNetwork.test.ts`, "add gateway gives one notice for a CUSTOM_JWT gateway, and build gives none".
leo237
left a comment
There was a problem hiding this comment.
Re-review of the four commits since my approval at 743cd84 (git diff 743cd84c e095a842): ff0c48f, a043718, 869d590, e095a84.
Why COMMENT and not APPROVE: the branch conflicts with box-integration. GitHub reports it as CONFLICTING/DIRTY, and no CI has run (gh pr checks reports no checks). A trial merge against the current origin/box-integration conflicts in:
docs/box-local-testing.mdsrc/core/project/boxNetworkWriters.tssrc/core/project/templates/boxProfile.ts
Please merge or rebase onto box-integration, then let CI run. The code in the new commits looks right except for the schema point below.
New commits
-
a043718 (one target name for two gateways): looks good.
hostTargetsnow fails withTARGET_NAME_COLLISION, and the message names both gateways and says to rename one. The test builds a real hash collision (a--banda-b-<hash>), andprojectGateways.test.tsgets a new long-name case. -
869d590 (
constructor): looks good.Object.hasOwn(mcp, gateway.name)takes the place ofin, and there is a test forconstructor. I checked the other lookups by gateway name in the PR. They useMaporfind, or they assign to an own key (mcp[gateway.name] = ...).GatewayNameSchema(^[0-9a-zA-Z](?:[0-9a-zA-Z-]*[0-9a-zA-Z])?$) refuses_, so__proto__cannot be a gateway name.toStringand similar names go through the samehasOwnpath. -
ff0c48f (reading a project whose build-owned target names a gateway it cannot call): the build side is good. The two new manager tests show that build removes
egress-gateway-toolsafter the gateway getsboundRuntime, and after it is removed from agentcore.json, with the right step message. But the schema change is wider than the fix needs. See the inline comment. In short, theegress-skip applies to every gateway in every project, not only to the Box gateways that build manages. -
e095a84 (CUSTOM_JWT notice once, at
add gateway): this answers my earlier item (e). The notice is sent after the spec write, only for an unbound CUSTOM_JWT gateway when some runtime runs in a box and is not PRIVATE_VPC. A test shows thatadd gatewaygives it once and build gives none. Non-blocking: with this change, these cases get no notice at all:- A CUSTOM_JWT gateway added before the boxed runtime.
add runtimegives notices for log targets and the Box gateway, but not this one. - A gateway whose
authorizerTypeis changed to CUSTOM_JWT by hand, or added by hand. - Projects that already had a CUSTOM_JWT gateway before this change.
In all three cases the boxed agent silently has no route to that gateway. Two options: also give
customJwtGatewayNoticefromadd runtimefor each unbound CUSTOM_JWT gateway when the new runtime is boxed, or state in the docs that build adds no route and says nothing. I'm fine with either one, or with doing it as a follow-up. - A CUSTOM_JWT gateway added before the boxed runtime.
Earlier non-blocking items
- (a)
compatibility.ts: still open, and not touched by these commits. Ifnodeis missing, or the check fails or times out, the result is stillfalse, so the warning tells the user to update@aws/agentcore-cdk. - (b) PR body Follow-ups: addressed. It now links aws/agentcore-l3-cdk-constructs#478.
- (c) The box-on-PATH test for
-/uppercase names: unchanged, so it still does not run in CI. - (d) Opting out of automatic tool access: still open (follow-up).
- (e) Addressed by e095a84 (see above).
- (f) #2877 (
box-gateway-targets.jsonrecord): both are still open. A trial merge of this PR with #2877's head conflicts widely (boxNetwork/network.ts,boxNetworkWriters.ts,manager.tsx,projectSchemas/project.ts, and others), partly from base drift. When the second of the two lands, it must make sure the record coversegress-gateway-*targets, and that theegress-schema skip agrees with the record. - (g) Back-merge to dev: still pending.
Interaction with #2889 (not blocking, FYI)
This PR adds no uses of getBoxGatewayAgentCoreTargetSpec, boxGatewayAgentCoreHost, or agentCoreDataPlaneHost. The existing import in network.test.ts comes from the base. A trial merge with #2889's head conflicts in boxNetwork/network.test.ts, boxNetworkWriters.ts, and runtimeProfile/types.ts. Whichever PR lands second has to adapt.
Other checks
- Tests: the new tests have no hard-coded host paths, no splitting on
:, no POSIX modes, no subprocess spawns, and no network calls (the JWT discovery URL is only data, onexample.com). - Public repo: I found no internal references or account IDs in the diff or the commit messages.
…hema now splits passthrough aws/agentcore-l3-cdk-constructs PR 478, commit a1c7d24 (for its review), keeps `PassthroughConfigSchema` with a required `endpoint`, and gives `passthrough.gateway` the schema `GatewayPassthroughConfigSchema`. Thus the check of 801cff5, which parsed `{ gateway }` with `PassthroughConfigSchema`, gave false for the library that accepts the field, and build wrote no target. `cdkAcceptsPassthroughGateway` now parses a whole target as build writes it with `AgentCoreGatewayTargetSchema`, which both libraries export. `@aws/agentcore-cdk` 1.1.0 from npm gives false, and the build of PR 478 at d57f789 gives true. Test: in `compatibility.test.ts`, "is true when the installed library accepts passthrough.gateway" fails before this change. Its fake library now exports `AgentCoreGatewayTargetSchema`.
…arget of a Box gateway Review feedback on ff0c48f: the schema skipped the check for each target whose name starts with `egress-`, on each gateway of each project. Build manages `egress-` targets only on the Box gateway of a runtime: a gateway with `boundRuntime` in a project with `"projectType": "box"`. The skip now applies only to such a target. An `egress-` target on a gateway without `boundRuntime`, or in a project that is not a Box project, gets the check, as each other target does. Tests: in `project.test.ts`, "is refused on a gateway without boundRuntime, which build does not write" and "is refused in a project that is not a Box project" fail before this change. "is accepted on the Box gateway of a Box project when it names ..." pins the case that build removes.
…gh.gateway
Review feedback: `cdkAcceptsPassthroughGateway` gave false for a library that refuses the field,
and also when `node` is not there, when the check takes more than 60 seconds, and when the check
fails. In each case, the warning told the user to update the library.
The check now gives `PassthroughGatewayCheck`: `{ accepts: true }`, or `{ accepts: false, reason }`
with the reason `refuses`, `not-installed`, `no-node`, `timed-out`, or `failed`, and for `failed`
the first line of the error. The one warning of build says that reason and its fix. Build still
writes no target, no server, and no pack input in each case that is not `accepts`.
`cdkAcceptsPassthroughGateway` also takes `node` and `timeoutMs`, for tests.
Tests that fail before this change: in `compatibility.test.ts`, one test for each answer, with a
fake library, a library that throws, a library that does not stop, and a `node` that is not
there; in `network.test.ts`, "gives the agent no gateway, and one warning that says why, when the
check gives ..." for each reason.
…ds a boxed runtime Review feedback: `customJwtGatewayNotice` came only from `add gateway`, when a boxed runtime was in the project already. A boxed runtime that `add runtime` adds after the gateway got no notice. `add runtime` now gives `customJwtGatewayNotice` after it writes agentcore.json, for each `CUSTOM_JWT` gateway without `boundRuntime`, when the new runtime runs in a box and is not `PRIVATE_VPC`. `docs/box-local-testing.md` says so. Test: in `manager.box.test.ts`, "add runtime gives the notice of each CUSTOM_JWT gateway without boundRuntime, as the new runtime is boxed" fails before this change.
|
This comment lists each item of the review in the shared doc and of the second review by @leo237, with the commit that changes it. The head is 1721f474. Items of the review doc
Items of the second review
A change for the L3 review: aws/agentcore-l3-cdk-constructs PR 478 now gives Tests: each code change has a test that fails before it. |
leo237
left a comment
There was a problem hiding this comment.
Re-review at 1721f47 (since e095a84: 52f88f1, merge 3d739f2, 2f39864, 2f55c31, 1721f47).
Merge conflict (was blocking): fixed. No conflict markers left. I checked 3d739f2 with remerge-diff. docs/box-local-testing.md, boxNetworkWriters.ts and templates/boxProfile.ts keep both sides. renderAgentCorePack(spec, runtime, gateways) keeps the #2885 OTEL inputs and env, then appends the gateway inputs and env. The one non-test caller passes entry and network?.projectGateways, and the test callers were updated. No base change is reverted. GitHub now reports the PR as mergeable.
Addressed
- Schema skip for
egress-targets (project.ts): the skip now needs a Box project, a gateway withboundRuntime, and theegress-prefix. New tests check that the target is refused on a gateway withoutboundRuntimeand in a project that is not a Box project. They also check that it is still accepted on the Box gateway of a Box project. Resolved. - (a)
compatibility.ts:PassthroughGatewayChecknow returns a reason:refuses,not-installed,no-node,timed-out, orfailedwith the error. Each reason has its own warning and fix. It is still fail-safe: anything other thanacceptswrites no target. Each answer has a test. 52f88f1 also probes with a whole target throughAgentCoreGatewayTargetSchema, which matches the new split passthrough schema in L3 #478. Resolved. - CUSTOM_JWT notice:
add runtimenow also gives the notice for a boxed runtime that is not PRIVATE_VPC, for each unbound CUSTOM_JWT gateway. There is a test, and the docs are updated. Mostly resolved. Hand edits and existing projects still get no notice. That is fine as a follow-up (for example, a build-time info line).
Still open (non-blocking, as before)
- (c) The test for box on PATH still never runs in CI.
- (d) There is still no opt-out for tool access, and the opt-out message is still missing.
- (f) The #2877 record must cover the
egress-gateway-*targets. - (g) Back-merge to dev.
- Conflicts with open PRs (FYI): a trial merge with #2889 conflicts in
boxNetwork/network.test.ts,boxNetworkWriters.tsandmanager.test.ts. A trial merge with #2877 conflicts indocs/box-local-testing.md,boxNetwork/network.ts,network.test.ts,boxNetworkSource.ts,boxNetworkWriters.tsand its test, among others. Whichever PR lands second needs a careful resolution. - L3 #478 is still open and not merged. Until it ships, build writes no target and gives the
refuseswarning. That is the intended fail-safe.
New nits (non-blocking)
projectGateways.ts: the doc comment ofprojectGatewaysOfstill says "Withtargetsfalse". The parameter is nowcheck. The doc ofcustomJwtGatewayNoticementions onlyadd gateway(see inline).- The
timed-outmessage hard-codes "60 seconds", buttimeoutMscan be overridden. That is only for tests, so this is cosmetic. add runtimehas no negative test showing that a PRIVATE_VPC or non-box runtime gets no CUSTOM_JWT notice.- In the check script,
process.stdout.writefollowed byprocess.exit(0)could cut off output on platforms where pipe writes are asynchronous. The output is short and falls through tofailedwith no detail, so this is low risk.
CI: at posting time, CodeQL, Analyze, verify/Windows, verify/macOS and CodeBuild e2e pass. verify/Linux is still pending. Approving on the code. Please merge only after all checks pass.
…f projectGateways.ts (comment of Leo on projectGateways.ts line 53)
|
The head is now 33c29a1c. It changes only the two comments of |
leo237
left a comment
There was a problem hiding this comment.
Re-review of 1721f47..33c29a1. Approving again.
The new commit changes only comments in projectGateways.ts (+4/-3). The code is unchanged. Both fixes are accurate:
- The
projectGatewaysOfdoc now names thecheckparameter. "Whencheckdoes not acceptpassthrough.gateway" matches the!check.acceptsbranch anduncheckedBecause. - "
add gatewayoradd runtime" matches the twocustomJwtGatewayNoticecall sites inmanager.tsx: thegatewayandruntimebranches of the add flow.
That resolves my nit on line 53.
CI is green: verify Linux/macOS/Windows, CodeQL, CodeBuild e2e. The PR is mergeable; the blocked state is only branch protection.
Still open from earlier, none blocking this PR:
- The box-on-PATH test never runs in CI.
- A tool-access opt-out or message.
- The #2877 record must cover
egress-gateway-*. - The back-merge to dev.
- Nits from my last review: the hard-coded "60 seconds" in the timeout message; no test that a PRIVATE_VPC or non-box runtime gets no CUSTOM_JWT notice;
process.exitright after writing the check answer. - FYI: this conflicts with #2889 and #2877.
- L3 #478 is still open and not merged.
Description
The route needs aws/agentcore-l3-cdk-constructs#478. With the pinned
@aws/agentcore-cdk1.1.0, build writes no gateway-to-gateway target and gives one warning, and the project builds and deploys as before. The route starts to operate when the CLI pins a CDK release that has aws/agentcore-l3-cdk-constructs#478.Problem
A runtime without a box gets the URL of each gateway of its project in
AGENTCORE_GATEWAY_<NAME>_URL, and its code uses the MCP tools of that gateway. A boxed agent onAgentCore Runtime cannot do this. Its box has no route to the host of the gateway, so the box
refuses each request. The user cannot add the route: build refuses
aws://for a gateway host withUNSIGNABLE_HOST, and the ID of the gateway is not known before the first deploy.What changes
For each gateway without
boundRuntime, build does these steps for each box runtime. The userwrites nothing.
egress-gateway-<name>, withpassthrough.gateway: "<name>"andGATEWAY_IAM_ROLEforbedrock-agentcore. ANONEgateway gets no outbound auth.@box/agentcorepackgateways.<name>.urlfromenv:<prefix>_URLandgateways.<name>.hostfromenv:<prefix>_HOST, each with a pattern. The agent gets<prefix>_URLin[agent.env].[mcp.<name>], withdestinations = ["${{ inputs.gateways.<name>.host }}"]and a backend to the URL of the Box gateway and/egress-gateway-<name>, signed withaws://.passthroughhasgatewayorendpoint. The value ofgatewaymust be the name of a gateway of the project withoutboundRuntime.Decisions
PRIVATE_VPCruntime gets none, because the L3 binds noneto it. A
CUSTOM_JWTgateway gets a warning and no target, because the Box gateway signs onlywith its role.
AGENTCORE_GATEWAY_<NAME>_URL.Box reads the host from
AGENTCORE_GATEWAY_<NAME>_HOST, because box 0.1.11-preview.10 takes aninput in
destinationsonly when its value is a host. The L3 sets_HOST.CLI does not wait for
deployed-state.json, because that needs a second deploy.aws/agentcore-cli#2866, only what must be
different on the Runtime changes.
[mcp]server. A forbidrule of the user's policy stays, so the user can stop a tool.
a gateway of a different project by its host, because the ID exists only after deploy. The message
of
UNSIGNABLE_HOSTalso names the route that build adds.context.input.server == "<name>". A local server with that name stops build.gateways., notgateway., becausegateway.urlis the input of theBox gateway, and a gateway with the name
urlwould have the same input name.target, it runs
nodeinagentcore/cdkand asks the installed@aws/agentcore-cdkif itsPassthroughConfigSchemaaccepts{ gateway, protocolType }(cdkAcceptsPassthroughGateway).Thus the check reads the same library as synth.
of the L3
box-integrationbranch has the version 1.0.2.boundRuntime.no
[mcp]server, and no pack input. It removes a target that it wrote before, and gives onewarning that names the gateways.
@aws/agentcore-cdk1.1.0 from npm gives false. The build ofaws/agentcore-l3-cdk-constructs#478 gives true.
remove gatewayremoves the target that build wrote for that gateway. After a build, each Boxgateway has
egress-gateway-<name>for the gateway<name>.remove gateway <name>alsoremoves, from each other gateway, each
egress-target withpassthrough.gateway: "<name>".Thus the spec stays correct for the schema. A target that the user wrote and that names the
gateway stays, and the schema refuses it with its name.
egress-gateway-<name>whentargetNameForkeeps all of the gateway name.targetNameForchanges--to-and cuts a nameat 100 characters. For such a name, the target name ends in 8 hex digits of the SHA-256 of the
gateway name. It has 100 characters at most, and it is the same on each build.
_HOSTand_URLpatterns acceptamazonaws.com.cn, as the gateway hostof
AWS_ENDPOINTSdoes.Verified outside CI
(55e6f4b4)
and the L3 branch
(860f8093),
with box 0.1.11-preview.10. I added a second gateway
toolsgw(AWS_IAM) and one Lambda targetwith
agentcore add gatewayandagentcore add gateway-target. I did not change the box profile,the targets of the Box gateway, or IAM.
egress-gateway-toolsgwwith the endpoint oftoolsgw, the grant on the roleof the Box gateway, and
AGENTCORE_GATEWAY_TOOLSGW_URLand_HOSTon the runtime.echo___known_answerandgave
gw2gw-known-answer-7319.mcp:call toolsgw/echo___known_answer, permit, rulemcp_toolsgw_call.egress-gateway-toolsgw.toolsgw:tools/call echo___known_answerwith{text=hello from the box}, and the reply withgw2gw-known-answer-7319.MCPClient, andenableApplicationLogsontoolsgw. I didagentcore deploytwo more times for that agent code.add gatewaygivesprotocolType: "None", so_URLhas no/mcp. The agent code must add it,the same as without a box.
Follow-ups
gives one warning. To test the route before that, use a local L3 build, as in step 5 of
docs/box-local-testing.md.removes the shared gateway grants from a boxed runtime. With it, the runtime of this change gets
the variables of a gateway only through its Box gateway target, and no grant on that gateway.
agentcore devgets no route to the gateways. The local profile is the user's.GATEWAY_URL_PATTERN, for the inputgateway.urlof the Box gateway itself, also stops atamazonaws.com. That pattern was there before this PR.Related Issue
None.
Documentation PR
docs/box-local-testing.mdis in this change.Type of Change
Testing
bun test, with box 0.1.11-preview.10 onPATH. 5889 pass, 6 skip, 1 fail. The onefailure is "the box on PATH > resolves a profile into the rules the tests fake". It fails on
box-integrationtoo with this box, and CI has no box, so CI skips it.bun run test:e2e, or explained why they are notapplicable. I did the live test above, and not the e2e tests.
bun run typecheckbun run lint:checkbun run format:checkbun run auditbun run secrets:checkbun run buildsrc/assets/, I updated affected snapshots. This change does not changesrc/assets/.explained by this PR. I did not record fixtures.
command.md(the release workflow regenerates it)Without the change in
src/, 35 of the 265 tests of the six changed test files fail. Each of 19mutations of
src/fails one or more of the new tests. For the review changes, each new test failsbefore its change, and each of 5 more mutations fails one or more of them. The test for a gateway
name with
-and capital letters passes before and after, because box 0.1.11-preview.10 accepts thatname. CI passes on Linux, Windows, and macOS.
Checklist
docs are needed
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this
contribution, under the terms of your choice.