React 到 TypeScript Agent

Nx Plugin for AWS 提供了一个生成器，可以快速将您的 TypeScript Agent 与 React 网站集成。它设置了通过 WebSocket 上的 tRPC 连接到您的 agent 所需的所有配置，包括 AWS IAM 和 Cognito 身份验证支持。该集成在您的前端和 agent 的 tRPC 路由器之间提供完整的端到端类型安全。

前置条件

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

1. 一个 React 网站（使用 ts#website 生成器生成）
2. 一个 TypeScript Agent（使用 ts#agent 生成器生成）
3. 通过 ts#website#auth 生成器添加的 Cognito Auth

用法

运行生成器

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

系统将提示您选择 React 网站作为源项目，并选择包含您的 Agent 的项目作为目标项目。如果您的目标项目包含多个组件（例如多个 agent 或其他组件类型），系统将提示您指定 targetComponent 以消除歧义。

选项

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

生成器输出

生成器在您的 React 应用程序中创建以下结构：

• 文件夹src

  • 文件夹components

    • <AgentName>AgentClientProvider.tsx 设置 tRPC WebSocket 客户端并绑定到您的 agent 的 tRPC 路由器
    • QueryClientProvider.tsx TanStack React Query 客户端提供程序
  • 文件夹hooks

    • useSigV4.tsx 用于使用 SigV4 签名请求的 Hook（仅限 IAM）
    • use<AgentName>Agent.tsx 返回 tRPC 选项代理和原生 tRPC 客户端的 Hooks

此外，它还会安装所需的依赖项：

• @trpc/client
• @trpc/tanstack-react-query
• @tanstack/react-query
• aws4fetch（如果使用 IAM 身份验证）

工作原理

WebSocket 连接

生成的客户端通过 WebSocket 上的 tRPC 连接到您的 Agent。agent 通过 WebSocket 端点公开 tRPC 路由器（包括用于流式传输 agent 响应的 invoke 订阅）。

• 已部署：agent 运行时 ARN 从运行时配置加载。运行此连接生成器还会修补 agent 生成的 CDK/Terraform 构造，以将其 ARN 发布到网站的 runtime-config.json（在 connection 命名空间下），因此只有您明确连接的 agent 才会暴露给前端。ARN 会按照 Bedrock AgentCore Runtime WebSocket 协议转换为 WebSocket URL：wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• 本地开发：使用 dev 运行时，运行时配置覆盖将值设置为本地 ws:// URL（例如 ws://localhost:8081/ws），客户端直接连接

身份验证

生成的代码根据您的 agent 配置处理身份验证：

• IAM（默认）：使用 AWS SigV4 预签名 URL 对 WebSocket 连接进行身份验证。凭证从配置了您网站身份验证的 Cognito Identity Pool 获取。在 dev 模式下，当runtime-config.json不存在时，会自动跳过签名
• Cognito：将 JWT 访问令牌作为 base64url 编码的 bearer 令牌嵌入 Sec-WebSocket-Protocol 标头中，遵循 AgentCore WebSocket 身份验证协议

基础设施

如果您的 agent 使用 IAM 身份验证，则必须授予 Cognito Identity Pool 的已认证角色调用该 agent 的权限。

CDK

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

const identity = new UserIdentity(this, 'Identity');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the authenticated Cognito role permission to invoke the agent
myAgent.grantInvokeAccess(identity.identityPool.authenticatedRole);

grantInvokeAccess 会在 agent 的运行时 ARN 上连接所有 AgentCore 调用操作（InvokeAgentRuntime、InvokeAgentRuntimeWithWebSocketStream）。

Terraform

packages/infra/src/main.tf

module "identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

# Grant the authenticated Cognito role permission to invoke the agent
resource "aws_iam_policy" "invoke_my_agent" {
  name = "InvokeMyAgentPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "invoke_my_agent" {
  role       = module.identity.authenticated_role_name
  policy_arn = aws_iam_policy.invoke_my_agent.arn
}

如果您的 agent 使用 Cognito 身份验证，则无需定义任何额外的基础设施即可将您的网站连接到您的 agent。

使用生成的代码

使用 TanStack Query

最常见的用例是使用 use<AgentName>Agent hook 通过 invoke 订阅流式传输 agent 的响应，该 hook 返回一个 tRPC 选项代理，用于与 TanStack Query 一起使用：

import { useSubscription } from '@trpc/tanstack-react-query';
import { useMyAgentAgent } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const trpc = useMyAgentAgent();

  const subscription = useSubscription(
    trpc.invoke.subscriptionOptions(
      { prompt: 'What can you help me with?' },
      {
        enabled: true,
        onStarted: () => {
          console.log('Agent started responding');
        },
        onData: (token) => {
          console.log('Received token:', token);
        },
        onError: (error) => {
          console.error('Agent error:', error);
        },
      },
    ),
  );

  return (
    <div>
      <p>Status: {subscription.status}</p>
      {subscription.data && <p>Latest token: {subscription.data}</p>}
      {subscription.error && <p>Error: {subscription.error.message}</p>}
    </div>
  );
}

tRPC 选项代理

有关 tRPC 选项代理和 TanStack Query 集成的更多详细信息，请参阅 tRPC TanStack React Query 文档。

使用原生 tRPC 客户端

use<AgentName>AgentClient hook 提供对原生 tRPC 客户端的访问，以便更好地控制订阅生命周期：

import { useState } from 'react';
import { useMyAgentAgentClient } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const client = useMyAgentAgentClient();
  const [messages, setMessages] = useState<string[]>([]);

  const sendMessage = (prompt: string) => {
    const subscription = client.invoke.subscribe(
      { prompt },
      {
        onData: (token) => {
          setMessages((prev) => [...prev, token]);
        },
        onComplete: () => {
          console.log('Agent finished');
        },
        onError: (error) => {
          console.error('Error:', error);
        },
      },
    );

    // Clean up when done
    return () => subscription.unsubscribe();
  };

  return (
    <div>
      <button onClick={() => sendMessage('Hello!')}>Send</button>
      <div>
        {messages.map((msg, i) => (
          <span key={i}>{msg}</span>
        ))}
      </div>
    </div>
  );
}

原生 tRPC 客户端

有关原生 tRPC 客户端的更多详细信息，请参阅 tRPC Vanilla Client 文档。

本地开发

连接生成器会自动为您的 react 网站配置 dev 集成：

1. 运行 nx dev <website> 也会启动 agent 的本地服务器
2. 运行时配置被覆盖以指向本地 WebSocket URL（例如 ws://localhost:8081/ws）
3. 与连接的 API 类似，当runtime-config.json不存在时，在 dev 模式下会跳过身份验证

热重载

网站和连接的 agent 将热重载，使您能够快速迭代两者，而无需部署到 AWS。

类型安全

该集成提供完整的端到端类型安全。您的 IDE 将为所有 agent 过程调用提供完整的自动完成和类型检查。类型会自动从您的 agent 的 tRPC 路由器定义中推断，确保对 agent API 的任何更改都会立即反映在您的前端代码中。

更多信息

有关更多信息，请参阅：

• TypeScript Agent 指南
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket