React đến TypeScript Strands Agent

Nx Plugin for AWS cung cấp một generator để nhanh chóng tích hợp TypeScript Strands Agent của bạn với một trang web React. Nó thiết lập tất cả cấu hình cần thiết để kết nối với agent của bạn thông qua tRPC qua WebSocket, bao gồm hỗ trợ xác thực AWS IAM và Cognito. Tích hợp này cung cấp type safety đầu cuối đầy đủ giữa frontend của bạn và tRPC router của agent.

Điều Kiện Tiên Quyết

Trước khi sử dụng generator này, hãy đảm bảo bạn có:

1. Một trang web React (được tạo bằng ts#react-website generator)
2. Một TypeScript Strands Agent (được tạo bằng ts#strands-agent generator)
3. Cognito Auth được thêm thông qua ts#react-website-auth generator

Cách Sử Dụng

Chạy Generator

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Bạn sẽ được nhắc chọn trang web React của bạn làm dự án nguồn và dự án chứa Strands Agent của bạn làm dự án đích. Nếu dự án đích của bạn chứa nhiều thành phần (như nhiều agent hoặc các loại thành phần khác), bạn sẽ được nhắc chỉ định một targetComponent để phân biệt.

Tùy Chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.

Kết Quả Từ Generator

Generator tạo cấu trúc sau trong ứng dụng React của bạn:

• Thư mụcsrc

  • Thư mụccomponents

    • <AgentName>AgentClientProvider.tsx Thiết lập tRPC WebSocket client và các binding đến tRPC router của agent của bạn
    • QueryClientProvider.tsx TanStack React Query client provider
  • Thư mụchooks

    • useSigV4.tsx Hook để ký các request với SigV4 (chỉ IAM)
    • use<AgentName>Agent.tsx Hooks trả về tRPC options proxy và vanilla tRPC client

Ngoài ra, nó cài đặt các dependency cần thiết:

• @trpc/client
• @trpc/tanstack-react-query
• @tanstack/react-query
• aws4fetch (nếu sử dụng xác thực IAM)

Cách Hoạt Động

Kết Nối WebSocket

Client được tạo kết nối với Strands Agent của bạn thông qua tRPC qua WebSocket. Agent hiển thị một tRPC router (bao gồm subscription invoke để streaming phản hồi của agent) qua một WebSocket endpoint.

• Deployed: Agent runtime ARN được tải từ Runtime Configuration. ARN được chuyển đổi thành WebSocket URL theo giao thức Bedrock AgentCore Runtime WebSocket: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• Local development: Khi chạy với serve-local, runtime config override đặt giá trị thành một URL ws:// cục bộ (ví dụ: ws://localhost:8081/ws), và client kết nối trực tiếp

Xác Thực

Code được tạo xử lý xác thực tùy thuộc vào cấu hình của agent của bạn:

• IAM (mặc định): Sử dụng AWS SigV4 presigned URLs để xác thực kết nối WebSocket. Credentials được lấy từ Cognito Identity Pool được cấu hình với xác thực của trang web của bạn. Trong chế độ serve-local, việc ký được tự động bỏ qua khi runtime-config.json không có mặt
• Cognito: Nhúng JWT access token trong header Sec-WebSocket-Protocol dưới dạng bearer token được mã hóa base64url, tuân theo giao thức xác thực AgentCore WebSocket

Infrastructure

Nếu agent của bạn sử dụng xác thực IAM, authenticated role của Cognito Identity Pool phải có quyền bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream để gọi các agent qua 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],
  }),
);

Giao thức WebSocket

Tại thời điểm viết bài này, phương thức grantInvoke của agent core runtime chưa tự động bao gồm quyền này (xem aws-cdk#37495).

Nếu agent của bạn sử dụng xác thực Cognito, bạn không cần định nghĩa bất kỳ infrastructure bổ sung nào để kết nối trang web của bạn với agent của bạn.

Sử Dụng Code Được Tạo

Sử Dụng TanStack Query

Trường hợp sử dụng phổ biến nhất là streaming phản hồi của agent bằng cách sử dụng subscription invoke với hook use<AgentName>Agent, hook này trả về một tRPC options proxy để sử dụng với 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>
  );
}

Proxy tùy chọn tRPC

Để biết thêm chi tiết về tRPC options proxy và tích hợp TanStack Query, xem tài liệu tRPC TanStack React Query.

Sử Dụng Vanilla tRPC Client

Hook use<AgentName>AgentClient cung cấp quyền truy cập vào vanilla tRPC client để kiểm soát nhiều hơn vòng đời subscription:

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>
  );
}

Client tRPC vanilla

Để biết thêm chi tiết về vanilla tRPC client, xem tài liệu tRPC Vanilla Client.

Phát Triển Cục Bộ

Connection generator tự động cấu hình tích hợp serve-local cho trang web react của bạn:

1. Chạy nx serve-local <website> cũng sẽ khởi động local server của agent
2. Runtime config được ghi đè để trỏ đến WebSocket URL cục bộ (ví dụ: ws://localhost:8081/ws)
3. Giống như với các API được kết nối, xác thực được bỏ qua trong chế độ serve-local khi runtime-config.json không có mặt

Tải lại nóng

Trang web và agent được kết nối sẽ hot-reload, cho phép bạn nhanh chóng lặp lại trên cả hai cùng nhau mà không cần triển khai lên AWS.

Type Safety

Tích hợp này cung cấp type safety đầu cuối hoàn chỉnh. IDE của bạn sẽ cung cấp autocompletion đầy đủ và type checking cho tất cả các lời gọi procedure của agent. Các kiểu được tự động suy ra từ định nghĩa tRPC router của agent của bạn, đảm bảo rằng bất kỳ thay đổi nào đối với API của agent của bạn đều được phản ánh ngay lập tức trong code frontend của bạn.

Thông Tin Thêm

Để biết thêm thông tin, vui lòng tham khảo:

• Hướng Dẫn TypeScript Strands Agent
• tRPC WebSocket Client
• Tích Hợp tRPC TanStack React Query
• Bedrock AgentCore Runtime WebSocket