AgentCore Gateway

生成一个 Amazon Bedrock AgentCore Gateway 项目。AgentCore Gateway 是位于您的 MCP 服务器或代理前面的托管入口点，对入站请求进行身份验证（IAM 或 Cognito），并使用 IAM SigV4 对其目标的出站流量进行签名。

protocol 选项选择 Gateway 前置的内容：

• mcp（默认）— 在单个 MCP 端点后面聚合一个或多个 MCP 服务器目标，并针对 Cedar 策略引擎评估每个工具调用。
• http — 通过基于路径的路由（/<targetName>/invocations）直接将请求代理到 AgentCore Runtime 目标（您的代理），无需聚合或协议转换。使用此选项可以通过单个受治理的端点前置代理 — 例如，让网站可以通过 Gateway 访问部署在 VPC 内的代理。

用法

生成 AgentCore Gateway

CLI

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway

npm

npx nx g @aws/nx-plugin:agentcore-gateway

bun

bunx nx g @aws/nx-plugin:agentcore-gateway

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - agentcore-gateway
5. 填写必需参数
6. 点击 Generate

选项

参数	类型	默认值	描述
name 必需	string	-	您的 AgentCore Gateway 项目的名称
directory	string	packages	放置网关项目的父目录。
subDirectory	string	-	项目放置的子目录。默认情况下，这是项目名称。
protocol	mcp | http	mcp	网关公开的入站协议。mcp 网关将 MCP 服务器目标聚合到单个 MCP 端点。http 网关通过基于路径的路由将请求代理到代理运行时目标，以便调用方（例如网站）可以通过网关访问代理。
auth	iam | cognito	iam	用于验证网关入站请求的方法。目前仅支持 iam；未来可能会添加 cognito 和 custom-jwt。
cedarPolicy	boolean	true	是否包含 Cedar 策略引擎以在网关上强制执行细粒度授权。
infra	agentcore | none	agentcore	托管网关的基础设施类型。选择 none 表示不托管。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器在 packages/<name>/ 创建一个新项目，以及用于基础设施的 CDK 构造或 Terraform 模块：

• 文件夹packages/<name>/

  • 文件夹policies/ Cedar 策略源文件（仅限 mcp 协议；当 cedarPolicy: false 时省略）

    • permit-all.cedar 允许经过身份验证的调用者的默认 Cedar 策略
    • README.md 编写 Cedar 策略的参考
  • local-dev.ts 用于本地开发的本地网关 — 聚合附加的 MCP 服务器（mcp）或代理附加的代理（http）
  • project.json 添加 serve 和 dev 目标

基础设施

当 infra 为 agentcore（默认值）时生成基础设施。使用 infra: none 时不生成基础设施 — 稍后使用 infra: agentcore 重新运行生成器以添加它。

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

CDK

• 文件夹packages/common/constructs/src

  • 文件夹core

    • 文件夹agentcore-gateway/ 共享网关构造（就绪探测、Cedar 策略加载）

      • …
  • 文件夹app

    • 文件夹gateways

      • 文件夹<name>/

        • <name>.ts 用于部署 Gateway 的 CDK 构造

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹gateways

      • 文件夹<name>/

        • <name>.tf 用于部署 Gateway 的 Terraform 模块

生成的构造创建以下 AWS 资源：

• 一个具有入站 IAM 身份验证（默认）或 Cognito JWT 身份验证的 AgentCore::Gateway（参见身份验证）。mcp 网关配置为 MCP 协议；http 网关没有协议类型，这是 AgentCore 对其运行时目标的要求
• 一个以 ENFORCE 模式运行的 AgentCore::PolicyEngine，附加到 Gateway（仅限 mcp 网关；当 cedarPolicy: false 时省略）
• policies/ 中每个 .cedar 文件对应一个 AgentCore::Policy（仅限 mcp 网关）
• 与 Gateway 关联的 AWS WAFv2 Web ACL，并将请求日志记录到 CloudWatch（默认启用 — 参见AWS WAF）

Gateway URL 会自动注册到 运行时配置 的 agentcore.gateways.<ClassName> 命名空间中，以便代理可以在运行时发现它。

架构

部署的 Gateway 具有以下架构，在 Gateway 前面有一个 AWS WAFv2 Web ACL，它路由到其下游 MCP 服务器目标：

身份验证

auth 选项配置 Gateway 如何对入站请求进行身份验证。在 iam（默认）和 cognito 之间选择。

IAM

默认情况下，Gateway 配置为 GatewayAuthorizer.usingAwsIam()。调用者使用 SigV4 签名请求，调用者的 IAM 身份作为 AgentCore::IamEntity 主体可用于 Cedar 策略。当您的调用者是在 AWS 中运行的代理或服务时，这是推荐的选项 — 例如，通过 代理到 Gateway 连接生成器连接的代理，它使用自己的执行角色签名其调用。

Cognito

当您选择 cognito 时，Gateway 配置为指向 Cognito 用户池的自定义 JWT 授权器。调用者通过提供 JWT 承载令牌进行身份验证，令牌的 sub 声明作为 AgentCore::OAuthUser 主体可用于 Cedar 策略。当您的调用者通过 Cognito 进行身份验证时使用此选项 — 例如，通过 ts#dcr-proxy 生成器连接的网站或编码代理。

生成的基础设施使用现有的 Cognito 用户池和客户端 — 它不会创建它们。您可以使用 ts#website#auth 生成器生成 UserIdentity，或提供您自己的。

CDK

生成的构造需要一个 identity 属性来提供用户池和客户端：

packages/infra/src/stacks/application-stack.ts

import { MyGateway, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'Identity');

    new MyGateway(this, 'MyGateway', {
      identity,
    });
  }
}

Terraform

生成的模块需要 user_pool_id 和 user_pool_client_ids 变量：

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

自定义 OIDC 提供商

要使用非 Cognito OIDC 提供商进行身份验证，请直接修改生成的 Gateway 构造或 Terraform 模块 — 将授权器的发现 URL 和允许的客户端替换为您的提供商的。代理到 Gateway 连接生成器仅支持 IAM 身份验证的网关，因为代理使用 SigV4 签名其调用。

编写策略

cedarPolicy = true

Cedar 是 AgentCore Gateway 用于授权工具调用的策略语言。流经 Gateway 的每个 tools/list 和 tools/call 请求都会针对附加的策略集进行评估，调用者必须至少有一个匹配的 permit 语句（并且没有匹配的 forbid）才能使请求成功。

有关完整参考，请参阅 AgentCore Gateway 策略的 AWS 文档，包括常见策略模式。

添加策略

要添加策略，请在 permit-all.cedar 旁边创建一个新的 .cedar 文件。policies/ 中的每个 .cedar 文件必须恰好包含一个 permit 或 forbid 语句，并作为单个 AWS::BedrockAgentCore::Policy 资源部署。策略资源的名称派生自文件名：permit-all.cedar 变为 PermitAll（kebab/snake-case 转换为 PascalCase）。包含多个语句的文件在部署时会产生 unexpected token 'forbid' 错误 — 将它们拆分为单独的文件。

例如，要仅允许特定代理角色调用特定工具，请创建：

packages/<name>/policies/ts-agent-divide.cedar

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

将角色名称作为模板变量传入（参见下面的模板变量），而不是硬编码它。重新合成或重新计划以部署新策略。

模板变量

策略是 EJS 模板，在合成/计划时渲染，以便它们在帐户和 Gateway 重新部署之间保持可移植性：

变量	替换为
<%= gatewayArn %>	已部署 Gateway 的 ARN
<%= accountId %>	此 Gateway 部署到的 AWS 帐户

始终引用这些变量，而不是硬编码值。

添加您自己的变量

在渲染策略的位置添加新变量，例如将代理的执行角色名称传递给上面的 ts-agent-divide.cedar 示例：

CDK

在 packages/common/constructs/src/app/gateways/<name>/<name>.ts 中，将 cedarPolicyVariables 传递给共享构造：

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

Terraform

在 packages/common/terraform/src/app/gateways/<name>/<name>.tf 中，添加到 rendered_policies 数据源的 query：

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

ENFORCE 模式和默认拒绝

PolicyEngine 以 ENFORCE 模式运行，这意味着应用默认拒绝语义：如果没有 permit 语句匹配（主体、操作、资源）元组，则请求被拒绝。被拒绝的工具调用返回：

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

此外，Gateway 过滤 tools/list 的响应，以便调用者只能看到他们至少有一个匹配 permit 的工具：如果代理缺少给定工具的权限，该工具将完全隐藏，而不是出现并在调用时失败。

默认 permit-all.cedar

生成器提供了一个默认策略，其范围限定为 Gateway 的身份验证类型。

对于 IAM Gateway，它允许来自 Gateway 部署到的 AWS 帐户的任何 IAM 调用者：

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

对于 Cognito Gateway，它允许任何经过身份验证的 OAuth 用户（JWT 授权器在评估策略之前已经验证了令牌的用户池和客户端）：

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

要进一步锁定，请在其旁边添加更窄的策略。始终在策略集中保留至少一个匹配的 permit，否则默认拒绝将阻止每个调用。

策略范围参考

主体类型取决于 Gateway 如何对调用者进行身份验证（参见身份验证）。

对于 IAM Gateway，调用者是 IAM 主体：

principal is AgentCore::IamEntity

调用者被评估为去除会话名称的 STS assumed-role ARN，因此可以精确匹配角色 — 不需要通配符：

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

相同的值作为 principal.id 可用于 when 子句。为真正的模式保留 like，例如默认 permit-all.cedar 中的帐户范围匹配。

对于 Cognito Gateway，调用者是从 JWT 令牌的 sub 声明构建的 OAuth 用户，JWT 声明（用户名、范围等）作为主体标签可用：

principal is AgentCore::OAuthUser

在 when 子句中匹配单个声明 — 例如，要求范围：

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.scope == "gateway/invoke"
};

工具调用以以下形式的操作到达策略引擎：

AgentCore::Action::"<target-name>___<tool-name>"

其中 <target-name> 是 Gateway 目标名称（使用 gateway.addMcpServer(...) 时默认为 MCP 服务器的 mcpServerName，派生自 MCP 项目的 kebab-case 类名 — 例如 TsMcp → ts-mcp），<tool-name> 是 MCP 工具的名称，分隔符是 ___（三个下划线）。Cedar 不支持操作上的通配符 — 匹配精确操作，或省略 action == 以匹配所有操作。

资源始终是 Gateway 本身：

resource == AgentCore::Gateway::"<%= gatewayArn %>"

验证注意事项

生成的基础设施使用 IGNORE_ALL_FINDINGS 创建策略：AgentCore 的 Cedar 分析器（FAIL_ON_ANY_FINDINGS，服务默认值）拒绝许多合法策略 — 例如，为每个调用者禁用单个工具的 forbid 被拒绝为”过度限制”，即使使用 when 子句限定范围也是如此。执行不受影响；它由策略引擎的 ENFORCE 模式配置。

仍然适用一个排序约束：引用 AgentCore::Action::"<target>___<tool>" 的策略仅在目标向 Gateway 注册该工具后才验证，这就是为什么生成的基础设施在 Gateway 目标之后创建策略。

如果策略部署失败，CloudFormation 会将拒绝显示为不透明的 Resource stabilization failed 错误 — 运行 aws bedrock-agentcore-control list-policies --policy-engine-id <id> 以检索验证器的 statusReasons，其中包含实际原因。

示例：禁止一个工具同时保留更广泛的许可

将窄的 forbid 与更广泛的 permit 配对（Cedar 评估 forbid 优先于 permit）：

packages/<name>/policies/forbid-divide-for-py-agent.cedar

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

这拒绝 Python 代理角色调用 ts-mcp___divide，同时为所有其他调用者保留更广泛的 permit-all.cedar。

本地开发

生成器向 Gateway 项目添加一个 dev 目标，它运行 local-dev.ts。运行它会同时启动本地网关和每个附加的目标：

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

本地网关公开一个单一的 MCP 端点，聚合每个附加的 MCP 服务器（通过 agentcore-gateway#mcp-connection 生成器连接），工具前缀为 <target>___<tool> 以匹配已部署的 Gateway。

protocol = http

本地网关将 /<targetName>/... 路径代理到每个附加代理的本地服务器（通过 agentcore-gateway#agent-connection 生成器连接），匹配已部署 Gateway 的基于路径的路由。

有关完整的本地开发故事，请参阅连接指南。

部署您的 AgentCore Gateway

AgentCore Gateway 生成器根据您选择的 iac 创建 CDK 或 Terraform 基础设施即代码。您可以使用它来部署您的 Gateway。

CDK

用于部署 Gateway 的 CDK 构造位于 common/constructs 文件夹中。您可以在 CDK 应用程序中使用它，例如：

packages/infra/src/stacks/application-stack.ts

import { MyGateway } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyGateway(this, 'MyGateway');
  }
}

这会设置您的 Gateway 基础设施，包括 AgentCore::Gateway、其 Cedar PolicyEngine 和 AWS WAF Web ACL（参见下面的 AWS WAF）。使用 gateway.addMcpServer(...) 注册 MCP 服务器目标 — 参见 MCP 服务器连接指南。

Terraform

用于部署 Gateway 的 Terraform 模块位于 common/terraform 文件夹中。您可以在 Terraform 配置中使用它，例如：

packages/infra/src/main.tf

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

这会设置您的 Gateway 基础设施，包括 aws_bedrockagentcore_gateway、其 Cedar 策略引擎和 AWS WAF Web ACL（参见下面的 AWS WAF）。使用 aws_bedrockagentcore_gateway_target 资源注册 MCP 服务器目标 — 参见 MCP 服务器连接指南。

AWS WAF

默认情况下，生成的构造将 AWS WAFv2 Web ACL 与 Gateway 关联。AWS WAF 在每个入站请求到达目标_之前_内联检查它，保护您的 Gateway 免受 Web 漏洞、机器人流量和容量攻击。Web ACL 使用 AWS 托管的默认规则集（AWSManagedRulesCommonRuleSet 和 AWSManagedRulesKnownBadInputsRuleSet），提供针对常见 Web 漏洞（包括 OWASP Top 10）的保护。WAF 请求日志写入 CloudWatch Logs 日志组。

Web ACL 是 REGIONAL 的，并在 Gateway 的区域中创建，这是 AgentCore Gateway 关联所必需的。

SizeRestrictions_BODY 偏离默认值

AWSManagedRulesCommonRuleSet 中的 SizeRestrictions_BODY 规则被覆盖为 Count 而不是 Block，因为该规则的 8 KB 限制对于典型的 MCP 工具有效负载来说过于严格。超大请求仍将记录为指标，以便您可以监控它们。有关更多详细信息，请参阅 AWS WAF 正文大小限制指南。

您可以编辑生成的 Gateway 构造以添加、删除或调整规则（例如，添加基于速率的规则或其他托管规则组）。

CDK

要选择退出（例如，附加您自己的 Web ACL），在实例化 Gateway 构造时将 enableWaf 设置为 false：

new MyGateway(this, 'MyGateway', {
  enableWaf: false,
});

构造将创建的 Web ACL 公开为 webAcl 以进行进一步配置。

Terraform

要选择退出（例如，附加您自己的 Web ACL），在 Gateway 模块上将 enable_waf 设置为 false：

module "my_gateway" {
  enable_waf = false
}

模块将创建的 Web ACL ARN 输出为 waf_web_acl_arn 以进行进一步配置。

连接

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

AgentCore Gateway to MCP Server在 AgentCore Gateway 后面聚合 MCP 服务器

AgentCore Gateway to AgentCore Gateway在另一个 AgentCore Gateway 后面聚合 AgentCore Gateway

TypeScript Agent to AgentCore Gateway将 TypeScript Agent 连接到 AgentCore Gateway

Python Agent to AgentCore Gateway将 Python Agent 连接到 AgentCore Gateway

AgentCore Gateway to Agent使用 AgentCore Gateway 作为运行时目标前置代理

React Website to AgentCore Gateway通过 AgentCore Gateway 将 React 网站连接到代理