AgentCore Gateway 到 Agent

connection 生成器可以将代理（TypeScript 或 Python）注册为使用 protocol: http 生成的 AgentCore Gateway 的 AgentCore 运行时目标。

连接后，Gateway 会在 <gatewayUrl>/<targetName>/invocations 下代理对代理的请求，使用 IAM SigV4 对发往运行时的出站流量进行签名。这为您的代理提供了一个统一的受管入口点——由于调用者只需访问 Gateway，代理运行时本身可以部署在其后的 VPC 内部。

前置条件

在使用此生成器之前，请确保您具备：

1. 使用 protocol: http 生成的 agentcore-gateway 项目
2. 使用 infra: agentcore 创建的代理组件（ts#agent 或 py#agent）。auth: iam（Gateway 使用自己的角色调用它）或 auth: cognito（Gateway 转发调用者的 JWT——参见将调用者身份转发到运行时）都可以使用。

TypeScript HTTP 代理

TypeScript http 代理通过 WebSocket 提供 tRPC 服务，而 AgentCore Gateway 不支持 WebSocket 或双向流——生成器会拒绝此组合。请改用 ag-ui 协议生成代理。

使用方法

运行生成器

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

选择 Gateway 项目作为源，选择代理项目作为目标。如果代理项目包含多个组件，请指定 targetComponent 以消除歧义。

选项

参数	类型	默认值	描述
sourceProject 必需	string	-	源项目
targetProject 必需	string	-	要连接到的目标项目
sourceComponent	string	-	要从其连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。
targetComponent	string	-	要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器将现有项目连接在一起，而不是生成新的源文件。以下文件会被修改：

• 文件夹packages/<gateway>

  • project.json Gateway 的 dev 目标获得对代理的 <agent>-dev 的依赖
  • local-dev.ts ATTACHED_AGENTS 已更新，以便本地网关代理到代理

将代理目标添加到您的堆栈

生成器无法自动将代理目标连接到您的基础设施中，因为它不知道哪个堆栈或模块实例化了 Gateway。您需要自己添加一个对 gateway.addAgent(agent) 的调用。

CDK

在实例化 Gateway 的堆栈中，将代理注册为目标：

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

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// 将代理注册为 Gateway 的运行时目标。目标名称
// 默认为代理的 `agentName`（其类名的 kebab-case 形式，
// 例如 `MyAgent` -> `my-agent`），并构成目标的调用路径：
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

要覆盖默认目标名称，请传递 gatewayTargetName：

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

该构造授予 Gateway 的执行角色对代理运行时的调用访问权限，并使用 GATEWAY_IAM_ROLE 凭证提供程序配置目标，以便 Gateway 使用自己的角色对出站调用进行签名。

将代理部署到 VPC 中

在代理前面放置 Gateway 正是让部署在 VPC 中的代理可以被访问的方式：调用方与 Gateway 的公共端点通信，而 Gateway 在内部访问运行时。将 VPC 网络配置传递给代理构造：

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // 为每个代理提供自己的网络配置作用域 — usingVpc
  // 在您传递的作用域下创建一个名为 `SecurityGroup` 的安全组，
  // 因此为多个代理传递 `this` 会在构造 ID 上发生冲突。
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

请使用具有出口的私有子网，而不是私有隔离子网：运行时需要出站互联网访问以访问 Bedrock 并从 AWS AppConfig 读取其配置。

AgentCore Runtime VPC 部署仅在某些可用区中受支持。如果部署失败并显示 subnets are in unsupported availability zones，请将 VPC（或子网选择）限制为您所在区域的受支持区域。

Terraform

在实例化 Gateway 的 Terraform 文件中，连接代理目标：

packages/infra/src/main.tf

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
  # ...
}

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

  # Gateway 使用自己的角色对运行时的出站调用进行签名，并在
  # 目标创建时验证访问权限，因此它首先需要调用访问权限。
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A 目标还通过网关提供其代理卡
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# 将代理注册为 Gateway 的运行时目标。目标名称
# 构成调用路径：<gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore 在未设置描述时会填充一个描述，提供程序会
  # 将其报告为应用后的不一致结果——因此始终设置一个。
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

将代理部署到 VPC 中

使用 Gateway 前置代理是使 VPC 部署的代理可访问的方式：调用者与 Gateway 的公共端点通信，Gateway 在内部访问运行时。设置代理模块的 VPC 变量：

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

使用具有出口的私有子网（到 NAT 网关的路由），而不是私有隔离子网：运行时需要出站互联网访问以访问 Bedrock 并从 AWS AppConfig 读取其配置。

通过 Gateway 调用代理

对 <gatewayUrl origin>/<targetName>/invocations 的请求会被转发到代理运行时，无需协议转换，因此调用者使用与直接针对运行时相同的请求形式——SSE 流（AG-UI）、JSON 流（Python HTTP）和 A2A JSON-RPC 都可以代理通过。调用者使用 Gateway 进行身份验证（根据 Gateway 的 auth 使用 IAM SigV4 或 Cognito JWT），而不是与代理进行身份验证。

要将网站连接到 Gateway 的代理，请使用 connection 生成器。

将调用者身份转发到运行时

默认情况下，Gateway 使用自己的 IAM 角色（GATEWAY_IAM_ROLE 凭证提供程序）对出站调用进行签名，因此运行时看到的是 _Gateway 的_身份，而不是调用者的身份。如果您希望代理基于调用者进行授权——例如读取用户的 sub 或 scope 声明——请使用 Cognito Gateway 前置 Cognito 代理。然后 Gateway 会将调用者的 JWT 原封不动地转发到运行时（JWT_PASSTHROUGH 凭证提供程序），运行时会重新验证它。

使用 auth: cognito 生成两端并按上述方式连接它们：

• 使用 auth: cognito 创建的代理（ts#agent 或 py#agent），以及
• 使用 auth: cognito 创建的 Gateway，前置相同的 Cognito 用户池。

其他一切都是自动的——gateway.addAgent(agent)（CDK）和生成的 Terraform 运行时模块会根据代理的 auth 为您处理连接：

• 目标使用 JWT_PASSTHROUGH 凭证提供程序（而不是 GATEWAY_IAM_ROLE）创建，并且
• 运行时将 Authorization 标头列入允许列表，以便转发的令牌到达您的代理代码。如果没有此允许列表，AgentCore 会验证令牌但在到达您的容器之前剥离标头。

调用者使用 Authorization: Bearer <jwt>（无 SigV4）调用 Gateway，代理从 Authorization 标头读取声明——跳过签名验证，因为运行时的入站授权器已经验证了令牌：

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

注意

JWT 透传适用于单个身份提供程序，其令牌受众已经覆盖运行时。如果一个 Gateway 前置跨多个租户或受众的代理，请改用 OAuth 代表令牌交换。

本地开发

使用以下命令在本地运行 Gateway：

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

启动本地网关以及每个附加代理在其分配的本地端口上。本地网关将 /<targetName>/... 路径代理到每个代理的本地服务器，与已部署的 Gateway 的基于路径的路由相匹配。