React đến TypeScript Agent

Nx Plugin for AWS cung cấp một generator để nhanh chóng tích hợp TypeScript Agent của bạn với một website 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 qua tRPC trên 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 hoàn toàn từ đầu đến cuối 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 website React (được tạo bằng ts#website generator)
2. Một TypeScript Agent (được tạo bằng ts#agent generator)
3. Cognito Auth được thêm qua ts#website#auth generator

Cách sử dụng

Chạy Generator

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

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

Bạn sẽ được nhắc chọn website React của bạn làm source project và project chứa Agent của bạn làm target project. Nếu target project của bạn chứa nhiều component (như nhiều agent hoặc các loại component 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.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Generator

Generator tạo ra 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à bindings với tRPC router của agent
    • 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 IAM auth)

Cách hoạt động

Kết nối WebSocket

Client được tạo ra kết nối với Agent của bạn qua tRPC trên WebSocket. Agent expose một tRPC router (bao gồm subscription invoke để streaming các response của agent) qua một WebSocket endpoint.

• Deployed: ARN của agent runtime được tải từ Runtime Configuration. Chạy connection generator này cũng vá construct CDK/Terraform được tạo của agent để publish ARN của nó vào runtime-config.json của website (dưới namespace connection), vì vậy chỉ những agent mà bạn kết nối rõ ràng mới được expose cho frontend. 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 dev, runtime config override đặt giá trị thành một local ws:// URL (ví dụ: ws://localhost:8081/ws), và client kết nối trực tiếp

Xác thực

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

• 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 auth của website. Trong chế độ dev, việc ký tự động bị bỏ qua khi runtime-config.json không có mặt
• Cognito: Nhúng JWT access token vào header Sec-WebSocket-Protocol dưới dạng base64url-encoded bearer token, theo giao thức AgentCore WebSocket auth

Hạ tầng

Nếu agent của bạn sử dụng xác thực IAM, vai trò được xác thực của Cognito Identity Pool phải được cấp quyền để gọi 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 kết nối tất cả các hành động gọi AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) trên ARN runtime của agent.

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
}

Nếu agent của bạn sử dụng xác thực Cognito, bạn không cần định nghĩa thêm bất kỳ cơ sở hạ tầng nào để kết nối website của bạn với agent.

Sử dụng Code được tạo ra

Sử dụng TanStack Query

Trường hợp sử dụng phổ biến nhất là streaming response của agent bằ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(
      { 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 Options Proxy

Để 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 = (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>
  );
}

Vanilla tRPC Client

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

Phát triển Local

Connection generator tự động cấu hình tích hợp dev cho react website của bạn:

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

Hot Reloading

Website 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 deploy lên AWS.

Type Safety

Tích hợp này cung cấp type safety hoàn toàn từ đầu đến cuối. IDE của bạn sẽ cung cấp autocompletion và type checking đầy đủ cho tất cả các lời gọi procedure của agent. Các type được tự động suy ra từ định nghĩa tRPC router của agent, đảm bảo rằng bất kỳ thay đổi nào đối với API của agent đề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 Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket