feat(project): add gateway resources by aidandaly24 · Pull Request #2028 · aws/agentcore-cli

aidandaly24 · 2026-08-18T20:18:39Z

Summary

Adds project-based Gateway resource management:

agentcore project add gateway
agentcore project add gateway-target
agentcore project add gateway-connector

agentcore project remove gateway
agentcore project remove gateway-target --gateway <name>
agentcore project remove gateway-connector --gateway <name>

Project-command JSON maps directly to the existing version 1 agentcore.json schemas:

--authorizer-configuration accepts GatewayAuthorizerConfigSchema;
--target-configuration accepts one complete AgentCoreGatewayTargetSchema object;
--connector-configuration accepts the same complete Target object and requires targetType: "connector";
JSON sources work inline, through file://, and through stdin;
SDK request shapes are not accepted or translated.

Scalar endpoint, Runtime, and curated Connector shortcuts construct the same
project-schema objects accepted through JSON. Connector removal is an alias over
Gateway Target removal because Connectors are stored as ordinary Targets.

Gateway protocol behavior preserves the existing schema and L3 contract:

omitting --protocol-type persists protocolType: "None" and creates an unrestricted Gateway;
--protocol-type MCP persists protocolType: "MCP" and creates an MCP-only Gateway;
"None" is not exposed as a flag value because omission already selects it;
semantic search requires --protocol-type MCP.

The change also:

makes project-owned compute Target branches reachable through direct Target JSON;
validates OAuth/API-key credential-name references in complete Target JSON and OAuth shortcuts;
validates Runtime and Runtime endpoint references;
validates the complete candidate project before one agentcore.json write;
uses the existing generic project-resource mutation flow, with only nested Target placement and removal handled specially;
rejects duplicate Target names across all Gateways and unassignedTargets[], matching the existing L3 Target-output contract.

The CLI does not create or copy files referenced by Target JSON. Paths such as
schemaSource.inline.path and lambdaFunctionArn.toolSchemaFile remain explicit
in agentcore.json.

Testing

Verification on CLI head 523a5b35:

focused Gateway add/remove and schema tests: 90 passed;
bun test src --coverage outside the restricted sandbox: 1,794 passed;
project line coverage: 97.86%;
modified Gateway add handlers, remove handler, and Gateway schema: 100% line coverage;
bun run typecheck;
bun run lint:check;
bun run format:check;
bun run build;
built CLI help verified for Gateway, Gateway Target, and removal commands.

Live deployment

Earlier end-to-end verification of the persisted Gateway and Target shapes used
a generated project with @aws/agentcore-cdk@0.1.0-alpha.45:

Runtime and direct MCP Targets reached READY;
Runtime invocation through Gateway returned HTTP 200;
MCP initialize and tools/list returned HTTP 200;
the stack and all resources were destroyed and verified absent.

Credential-provider authoring is owned by the separate project credentials
commands. This PR validates Gateway Target references to those project
credentials but does not create them.

codecov-commenter · 2026-08-18T20:22:00Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.30%. Comparing base (38c30ae) to head (523a5b3).
⚠️ Report is 3 commits behind head on refactor.

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2028      +/-   ##
============================================
+ Coverage     97.24%   97.30%   +0.05%     
============================================
  Files           396      400       +4     
  Lines         24019    24544     +525     
============================================
+ Hits          23357    23882     +525     
  Misses          662      662

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jariy17 · 2026-08-22T13:00:34Z

+        );
+        if (gatewayIndex < 0) {
+          throw new InputValidationError(
+            `gateway '${input.gatewayName}' does not exist in agentCoreGateways[]`,


nit: does not exist in project. Please check agentCoreGateway in agentcore.json

jariy17 · 2026-08-22T13:06:53Z

    };
  }

+  private assertUniqueGatewayTargetName(project: Project["spec"], name: string): void {


Are all gateway target names required to be unique across every gateway, or must they only be unique inside a single gateway?

This is due to a limitation with the current CDK. The name technically only has to be unique to the gateway but the L3 CDKs require them to be globally unique. This is a change we could make on the L3 CDK but for now I was just trying to make the implementaion compatible.

I'm going to inline this function

jariy17 · 2026-08-22T13:09:10Z

+      ),
+      flag(
+        "knowledge-base",
+        "project Knowledge Base name or external ten-character Knowledge Base ID",


add that this could only be used with bedrock-knowledge-base

jariy17 · 2026-08-22T13:12:37Z

+import type { Project } from "../../types";
+import type { AddProjectResourceConfig } from "../types";
+
+export const createAddGatewayTargetHandler = (config: AddProjectResourceConfig) =>


If you check how the help looks for the old cli, you will notice that it divides based on target

Target types and their options: http-runtime — Route to an AgentCore runtime --runtime <name> Runtime from your project --runtime-endpoint <name> Endpoint / version alias (optional) mcp-server — Connect to an MCP-compatible server --endpoint <url> Server endpoint URL --host <host> Lambda or AgentCoreRuntime --language <lang> Python, TypeScript, or Other api-gateway — Connect to an Amazon API Gateway REST API --rest-api-id <id> REST API ID --stage <stage> Deployment stage open-api-schema / smithy-model — Auto-derive tools from a schema --schema <path> Schema file path or S3 URI --schema-s3-account <id> S3 bucket owner account ID lambda-function-arn — Connect to an AWS Lambda function --lambda-arn <arn> Lambda function ARN --tool-schema-file <path> Tool schema JSON file connector — Wire a managed AWS connector (bedrock-knowledge-bases, web-search) --connector <id> bedrock-knowledge-bases or web-search --knowledge-base-id <id> Project KB name or 10-char external KB id (for KB connectors) --exclude-domains <list> Comma-separated domains to exclude (for web-search connector) passthrough — Route to an external HTTPS endpoint --passthrough-endpoint <url> HTTPS endpoint URL --stickiness-identifier <expr> Session routing expression (optional) --stickiness-timeout <seconds> Sticky session timeout in seconds (optional) Auth (--outbound-auth <type>, --credential-name <name>) — valid types per target: mcp-server oauth or none lambda-function-arn oauth or none http-runtime oauth or none open-api-schema oauth or api-key (required) api-gateway api-key or none smithy-model none (uses gateway IAM role) passthrough gateway-iam-role, oauth, or jwt-passthrough

jariy17 · 2026-08-22T13:28:17Z

+        configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+      };
+    case "bedrock-knowledge-bases":
+      if (!knowledgeBase) {


Don't we do this validation at line 60?

jariy17 · 2026-08-22T13:30:47Z

+      ),
+      flag("exception-level", "exception detail level: debug", z.enum(["debug"]).optional()),
+      flag(
+        "tags",


Check runtime and harness, we don't do SourceResolver for this.

jariy17 · 2026-08-22T13:32:41Z

+        "restrict Target protocols to MCP; omitted allows every Target protocol",
+        z.enum(["mcp"]).optional(),
+      ),
+      flag(


nit: The description should say enable semantic search to search tools on gateway

jariy17 · 2026-08-22T13:34:02Z

+        z.string().optional(),
+      ),
+      flag(
+        "policy-engine-name",


Should we expand this for policy engines outside of this project? What is cons of doing that?

jariy17 · 2026-08-22T13:35:30Z

+  testIO,
+} from "../../../testing";
+
+export function createGatewayProjectTestHarness(directoryPrefix: string) {


combine this with index.test.ts. If no one other test file is using it, it should be combine with the test file

jariy17 · 2026-08-22T13:35:59Z


 export type RemoveResourceInput = {
-  resourceType: ProjectResource;
+  resourceType: Exclude<ProjectResource, "gateway" | "gateway-target">;


Why are we excluding it from remove?

Hweinstock · 2026-08-24T13:30:38Z


Run ./dist/bin/agentcore-linux-x64 --help
ResourceUnavailable: C:\codebuild\tmp\output\src2220336954\src\actions-runner\_work\_temp\6e195c49-dc39-49f6-be19-336eeffd6cd8.ps1:2
Line |
   2 |  ./dist/bin/agentcore-linux-x64 --help
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Program 'agentcore-linux-x64' failed to run: Class not registeredAt
     | C:\codebuild\tmp\output\src2220336954\src\actions-runner\_work\_temp\6e195c49-dc39-49f6-be19-336eeffd6cd8.ps1:2 char:1 + ./dist/bin/agentcore-linux-x64 --help + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.

Is this failure related to the changes here? I don't see this failure on main.

github-actions Bot added the agentcore-harness-reviewing AgentCore Harness review in progress label Aug 18, 2026

github-actions Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label Aug 18, 2026

aidandaly24 force-pushed the feat/project-gateway-add branch 4 times, most recently from dbcb3b6 to fd627a1 Compare August 21, 2026 19:05

aidandaly24 marked this pull request as ready for review August 21, 2026 19:26

aidandaly24 marked this pull request as draft August 21, 2026 20:17

aidandaly24 force-pushed the feat/project-gateway-add branch from fd627a1 to 41a946d Compare August 21, 2026 20:28

aidandaly24 added 6 commits August 21, 2026 22:43

feat(project): add gateway resources

db6a077

refactor(project): use project schema for gateway JSON

820945b

test(project): restore gateway manager assertion

51adfd5

fix(project): enforce global gateway target names

c9423e0

refactor(project): simplify gateway resource mutation

a5df428

test(project): update gateway credential fixtures

7753af0

aidandaly24 force-pushed the feat/project-gateway-add branch from 41a946d to 7753af0 Compare August 21, 2026 22:47

test(project): refactor gateway add coverage

854514e

aidandaly24 marked this pull request as ready for review August 21, 2026 23:13

jariy17 requested changes Aug 22, 2026

View reviewed changes

aidandaly24 added 2 commits August 24, 2026 16:46

feat(project): complete gateway resource management

1b8df59

fix(project): preserve gateway protocol compatibility

523a5b3

This was referenced Aug 24, 2026

Scope Gateway Target names to their parent Gateway #2083

Open

Make omitted Gateway protocolType mean unrestricted #2084

Open

Uh oh!

Conversation

aidandaly24 commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Live deployment

Uh oh!

codecov-commenter commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hweinstock commented Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aidandaly24 commented Aug 18, 2026 •

edited

Loading

codecov-commenter commented Aug 18, 2026 •

edited

Loading