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

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

Summary

Adds project-based Gateway mutation commands:

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

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 remain. They construct the same
project-schema objects accepted through JSON.

The change also:

replaces SDK protocol JSON with the direct --enable-semantic-search project field;
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
handled specially;
rejects duplicate Target names across all Gateways and unassignedTargets[], matching the old
CLI and existing L3 output contract.

No project schema files change. 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

Rebased onto upstream/refactor at 38c30ae4; verification ran on PR head 854514eb.

bun run format:check
bun run lint:check
bun run typecheck
focused Gateway command tests: 50 passed
Gateway add handler line coverage: 100%
bun test src outside the restricted sandbox: 1,789 passed
bun run build
built CLI help verified for all three command leaves
tests are colocated with each Gateway command and share only project-routing setup
verified complete Target JSON round-trips without translation
verified direct Target JSON works inline, through file://, and through stdin
verified project-owned Lambda compute Target JSON is accepted
verified duplicate Target names are rejected across Gateways and unassignedTargets[]
verified synthesis uses the existing Target-name-only L3 output contract without CDK changes

Live deployment

Earlier end-to-end verification of the same persisted Gateway shapes used a clean generated project
in account 603141041947, region us-west-2, with
@aws/agentcore-cdk@0.1.0-alpha.45.

Added an unrestricted Gateway and project Runtime Target through scalar command flags.
Added an MCP Gateway and external MCP Target through complete direct project JSON.
Added a Web Search Target through gateway-connector; synthesis produced the expected connector
configuration and IAM dependency. The service rejected live Target creation because
Connector integration web-search is not available for this account.
Alpha.45 emits SearchType: NONE when MCP semantic search is disabled, which current
CloudFormation rejects. The deployment fixture used project add gateway --protocol mcp --enable-semantic-search, allowing deployment without changing the CLI or L3 dependency.
Deployed the Runtime, both Gateways, and the Runtime/direct-MCP Targets; all reported READY.
Invoked runtime-target/invocations through the Gateway and received HTTP 200 with
runtime gateway works.
Sent MCP initialize and tools/list through the MCP Gateway; both returned HTTP 200 and the
direct DeepWiki Target tools were listed.
Destroyed the stack and independently verified the stack, Runtime, both Gateways, and both
Targets return not-found.

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 (854514e).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2028      +/-   ##
============================================
+ Coverage     97.24%   97.30%   +0.05%     
============================================
  Files           396      400       +4     
  Lines         24019    24531     +512     
============================================
+ Hits          23357    23869     +512     
  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?

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?

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

Navigation Menu

Uh oh!

feat(project): add gateway resources - #2028

feat(project): add gateway resources#2028
aidandaly24 wants to merge 7 commits into
aws:refactorfrom
aidandaly24:feat/project-gateway-add

aidandaly24 commented Aug 18, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Aug 18, 2026 •

edited

Loading

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

jariy17 Aug 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aidandaly24 commented Aug 18, 2026 •

edited

Loading

codecov-commenter commented Aug 18, 2026 •

edited

Loading