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 bearer token。

使用方法

运行生成器

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

选项

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

生成器输出

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

• 文件夹packages/<website>/src

  • 文件夹components

    • AguiProvider.tsx 注册每个代理的 CopilotKit provider
    • 文件夹copilot/ 主题化的聊天组件

      • …
  • 文件夹hooks

    • useAgui<Agent>.tsx 通过 Gateway 的 /<targetName>/invocations 路由连接到代理

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

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

授予网站用户访问权限

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

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 目标的依赖，该目标会启动本地 gateway 以及每个附加的代理。网站的运行时配置在 local-dev 模式下被覆盖，将 Gateway 的 URL 指向本地 gateway，因此浏览器在本地执行相同的 /<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 后，重新运行连接生成器以生成其网站客户端——现有客户端保持不变。