AgentCore Gateway 到 Agent

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

连接后，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 协议生成代理。

使用方法

运行生成器

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

VSCode

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

选择 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。请自行添加一个对 gateway.addAgent(agent) 的调用。

CDK

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

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

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

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <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', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct 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"

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  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 进行身份验证（IAM SigV4 或 Cognito JWT，取决于 Gateway 的 auth），而不是使用代理进行身份验证。

要将网站连接到 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>

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