React 网站到 AgentCore Gateway

connection 生成器可以将 React 网站 连接到由使用 protocol: http 生成的 AgentCore Gateway 前置的代理。

浏览器仅与 Gateway 通信——对 <gatewayUrl>/<targetName>/invocations 的请求会被代理到其后的代理运行时。由于网站永远不需要直接访问运行时，因此代理可以部署在 VPC 内部，Gateway 作为单一的受管理入口点，提供身份验证和可观测性。

前提条件

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

1. 一个 React 网站 项目
2. 一个使用 protocol: http 生成的 agentcore-gateway 项目
3. 至少一个通过 Gateway 到代理连接生成器 附加到 Gateway 的 AG-UI 或 HTTP 代理

该生成器为附加到 Gateway 的每个 AG-UI 或 HTTP 代理创建一个网站客户端（A2A 目标会被跳过——它们使用代理到代理的 JSON-RPC，而不是浏览器协议）。它生成与直接将网站连接到每个代理相同的客户端（对于 AG-UI 代理使用 AG-UI/CopilotKit，对于 Python HTTP 代理使用 OpenAPI 客户端），路由通过 Gateway 而不是直接到运行时。

身份验证

浏览器与 Gateway 进行身份验证，而不是与代理：对于 IAM Gateway 使用 SigV4（通过网站的 Cognito 身份池），或对于 Cognito Gateway 使用 JWT 承载令牌。

使用方法

运行生成器

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 项目作为目标。

选项

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

生成器输出

对于每个前置的 AG-UI 代理，会生成与 React 到 AG-UI 代理连接 相同的文件（一个 AguiProvider、一个 useAgui<Agent> 钩子和一个主题化的 CopilotKit 组件模块），钩子从运行时配置中读取 Gateway 的 URL：

• 文件夹packages/<website>/src

  • 文件夹components

    • AguiProvider.tsx CopilotKit provider registering each agent
    • 文件夹copilot/ Themed chat components

      • …
  • 文件夹hooks

    • useAgui<Agent>.tsx Connects to the agent via the Gateway’s /<targetName>/invocations route

对于每个前置的 Python HTTP 代理，会生成与 React 到 Python 代理连接 相同的文件（一个类型安全的 OpenAPI 客户端、钩子和一个提供者），客户端的基础 URL 通过 Gateway 路由。

Gateway 的 URL 注册在 运行时配置 的 connection.gateways.<GatewayClassName> 命名空间中，因此它会发布到网站的 runtime-config.json。

授予网站用户访问权限

对于 IAM Gateway，授予网站的已认证用户调用它的权限（Cognito Gateway 不需要授权——浏览器使用其 JWT 承载令牌进行身份验证）：

CDK

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

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

const myGateway = new MyGateway(this, 'MyGateway');
myGateway.addAgent(myAgent);
myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);

Terraform

packages/infra/src/main.tf

resource "aws_iam_policy" "gateway_invoke_policy" {
  name = "GatewayInvokePolicy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["bedrock-agentcore:InvokeGateway"]
        Resource = [module.my_gateway.gateway_arn]
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
}

本地开发

网站的 dev 目标获得对 Gateway 项目的 dev 目标的依赖，该目标会启动本地网关以及每个附加的代理。网站的运行时配置在 local-dev 模式下被覆盖，将 Gateway 的 URL 指向本地网关，因此浏览器在本地使用相同的 /<targetName>/invocations 路由：

pnpm

pnpm nx dev <website-name>

yarn

yarn nx dev <website-name>

npm

npx nx dev <website-name>

bun

bunx nx dev <website-name>

连接新代理

生成器将网站连接到运行时附加到 Gateway 的代理。在将另一个代理附加到 Gateway 后，重新运行连接生成器以生成其网站客户端——现有客户端保持不变。