AgentCore Gateway

生成一个 Amazon Bedrock AgentCore Gateway 项目。AgentCore Gateway 是一个托管的入口点，它将一个或多个 MCP 服务器目标聚合在单个 MCP 端点后面，对入站请求进行身份验证（IAM 或 Cognito），针对 Cedar 策略引擎评估每个工具调用，并使用 IAM SigV4 对发往 MCP 服务器的出站流量进行签名。

用法

生成 AgentCore Gateway

VSCode

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

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

选项

参数	类型	默认值	描述
name 必需	string	-	您的 AgentCore Gateway 项目的名称
directory	string	packages	放置网关项目的父目录。
subDirectory	string	-	项目放置的子目录。默认情况下，这是项目名称。
protocol	mcp	mcp	您的网关公开的入站协议。目前仅支持 mcp；未来可能会添加其他协议。
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 策略源文件（当 cedarPolicy: false 时省略）

    • permit-all.cedar 默认的 Cedar 策略，允许已认证的调用者（来自同一 AWS 账户的 IAM 调用者，或任何 Cognito 用户——参见 Authentication）
    • README.md 编写 Cedar 策略的参考文档
  • local-dev.ts 用于本地开发的本地网关，聚合附加的 MCP 服务器
  • project.json 添加 serve 和 dev 目标

基础设施

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

由于该生成器会根据您选择的 iac 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

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

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的基础设施构造体

      • …
    • 文件夹core/ 被 app 目录构造体重用的通用构造体

      • …
    • index.ts 导出 app 目录构造体的入口文件
  • project.json 项目构建目标与配置

生成的项目

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

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的 Terraform 模块

      • …
    • 文件夹core/ 被 app 目录模块重用的通用模块

      • …
  • project.json 项目构建目标与配置

生成的项目

此项目使用 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 资源：

• 一个为 MCP 协议配置的 AgentCore::Gateway，使用入站 IAM 身份验证（默认）或 Cognito JWT 身份验证（参见 Authentication）
• 一个以 ENFORCE 模式运行的 AgentCore::PolicyEngine，附加到 Gateway（当 cedarPolicy: false 时省略）
• policies/ 中每个 .cedar 文件对应一个 AgentCore::Policy
• 与 Gateway 关联的 AWS WAFv2 Web ACL，并将请求日志记录到 CloudWatch（默认启用——参见 AWS WAF）

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

架构

已部署的 Gateway 具有以下架构，入站请求通过 AWS WAFv2 Web ACL，然后路由到下游 MCP 服务器目标：

Authentication

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

IAM

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

Cognito

当您选择 Cognito 时，Gateway 配置为指向 Cognito 用户池的自定义 JWT 授权器。调用者通过提供 JWT bearer token 进行身份验证，token 的 sub 声明作为 AgentCore::OAuthUser 主体可用于 Cedar 策略。当您的调用者是通过 Cognito 进行身份验证的最终用户时（例如网站或非 AWS 客户端），请使用此选项。

生成的基础设施使用现有的 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 和允许的客户端替换为您的提供商的。Agent to Gateway 连接生成器仅支持 IAM 身份验证的网关，因为代理使用 SigV4 签名其调用。

编写策略

cedarPolicy = true

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

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

添加策略

要添加策略，请在 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 语句匹配（principal、action、resource）元组，请求将被拒绝。被拒绝的工具调用返回：

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 授权器在评估策略之前已经验证了 token 的用户池和客户端）：

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

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

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

策略范围参考

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

对于 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 token 的 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，其中包含实际原因。

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

将窄的 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：一个本地网关，公开单个 MCP 端点，聚合每个附加的 MCP 服务器（通过 agentcore-gateway#mcp-connection 生成器连接），工具前缀为 <target>___<tool> 以匹配已部署的 Gateway。运行它会一起启动本地网关和所有附加的 MCP 服务器：

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

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

部署您的 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