React 连接到 TypeScript Strands Agent

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

前置条件

在使用此生成器之前,请确保您具备:

1. 一个 React 网站(使用 ts#react-website 生成器生成)
2. 一个 TypeScript Strands Agent(使用 ts#strands-agent 生成器生成)
3. 通过 ts#react-website-auth 生成器添加 Cognito Auth

使用方法

运行生成器

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

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

选项

参数	类型	默认值	描述
sourceProject 必需	string	-	源项目
targetProject 必需	string	-	要连接到的目标项目
sourceComponent	string	-	要从其连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。
targetComponent	string	-	要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。

生成器输出

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

• 文件夹src

  • 文件夹components

    • <AgentName>AgentClientProvider.tsx 设置 tRPC WebSocket 客户端和到代理的 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 连接到您的 Strands Agent。代理通过 WebSocket 端点公开一个 tRPC 路由器(包括用于流式传输代理响应的 invoke 订阅)。

• 已部署: 代理运行时 ARN 从运行时配置加载。ARN 遵循 Bedrock AgentCore Runtime WebSocket 协议转换为 WebSocket URL: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• 本地开发: 使用 serve-local 运行时,运行时配置覆盖将值设置为本地 ws:// URL(例如 ws://localhost:8081/ws),客户端直接连接

身份验证

生成的代码根据代理的配置处理身份验证:

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

基础设施

如果您的代理使用 IAM 身份验证,Cognito Identity Pool 的已认证角色必须具有 bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream 权限才能通过 WebSocket 调用代理:

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

identity.identityPool.authenticatedRole.addToPrincipalPolicy(
  new PolicyStatement({
    actions: ['bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream'],
    resources: [myAgent.agentCoreRuntime.agentRuntimeArn],
  }),
);

WebSocket协议

在撰写本文时,代理核心运行时的 grantInvoke 方法尚未自动包含此权限(请参阅 aws-cdk#37495)。

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

使用生成的代码

使用 TanStack Query

最常见的用例是使用 invoke 订阅和 use<AgentName>Agent hook 流式传输代理的响应,该 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(
      { message: '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 = (message: string) => {
    const subscription = client.invoke.subscribe(
      { message },
      {
        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 网站配置 serve-local 集成:

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

热重载

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

类型安全

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

更多信息

有关更多信息,请参阅:

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