React đến Python Strands Agent

Nx Plugin for AWS cung cấp một generator để nhanh chóng tích hợp Python 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 một client được tạo từ OpenAPI với type-safe, bao gồm hỗ trợ xác thực AWS IAM và Cognito.

Đ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ó:

Một trang web React (được tạo bằng generator ts#react-website)
Một Python Strands Agent (được tạo bằng generator py#strands-agent)
Cognito Auth được thêm vào thông qua generator ts#react-website-auth

Cách Sử Dụng

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - connection
Điền các tham số bắt buộc
Nhấp Generate

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Bạn sẽ được nhắc chọn trang web React của mình làm dự án nguồn và dự án chứa Python Strands Agent của bạn làm dự án đích. Nếu dự án đích 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 targetComponent để làm rõ.

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 ra những thứ sau trong dự án Python Strands Agent của bạn:

Thư mụcscripts
- <agent_name>_openapi.py Script để tạo đặc tả OpenAPI từ ứng dụng FastAPI của agent
project.json Một target <agent-name>-openapi mới được thêm vào

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>Provider.tsx Provider cho OpenAPI client
  - QueryClientProvider.tsx TanStack React Query client provider
- Thư mụchooks
  - useSigV4.tsx Hook để ký các request với SigV4 (chỉ IAM)
  - use<AgentName>.tsx Hook trả về proxy options TanStack Query cho API của agent
  - use<AgentName>Client.tsx Hook trả về vanilla API client
- Thư mụcgenerated
  - Thư mục<agent-name>
    types.gen.ts Các type được tạo từ các model Pydantic của agent
    client.gen.ts Client type-safe để gọi API của agent
    options-proxy.gen.ts Các options hooks TanStack Query để tương tác với agent của bạn
project.json Các target được thêm vào để tạo client và theo dõi thay đổi
.gitignore Các file client được tạo ra mặc định bị bỏ qua

Cách Thức Hoạt Động

Tạo OpenAPI Client

Tại thời điểm build, ứng dụng FastAPI của Python Strands Agent được kiểm tra để tạo ra đặc tả OpenAPI. Đặc tả này sau đó được sử dụng để tạo một TypeScript client type-safe với các hook TanStack Query, tuân theo cùng một pattern như kết nối React to FastAPI.

Mỗi agent có script OpenAPI riêng của nó (ví dụ: scripts/agent_openapi.py) để các dự án có nhiều agent có thể tạo các đặc tả riêng lẻ.

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 của bạn:

IAM (mặc định): Sử dụng AWS SigV4 để ký các HTTP request. Thông tin xác thực được lấy từ Cognito Identity Pool được cấu hình với auth của trang web của bạn
Cognito: Nhúng JWT access token vào header Authorization
None: Không có xác thực

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

Sử Dụng API Hook

Hook use<AgentName> cung cấp các option TanStack Query để gọi các endpoint API của agent của bạn:

import { useState } from 'react';
import { useMutation } from '@tanstack/react-query';
import { useMyAgent } from '../hooks/useMyAgent';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const api = useMyAgent();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const invoke = useMutation(api.invoke.mutationOptions({
    onSuccess: async (stream) => {
      setChunks([]);
      for await (const chunk of stream) {
        setChunks((prev) => [...prev, chunk]);
      }
    },
  }));

  const handleSend = (message: string) => {
    invoke.mutate({
      prompt: message,
      sessionId: 'my-session',
    });
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {invoke.isPending && <p>Agent is thinking...</p>}
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

Sử Dụng Vanilla Client

Hook use<AgentName>Client cung cấp quyền truy cập trực tiếp vào API client:

import { useState } from 'react';
import { useMyAgentClient } from '../hooks/useMyAgentClient';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const client = useMyAgentClient();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const handleSend = async (message: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({
      prompt: message,
      sessionId: 'my-session',
    })) {
      setChunks((prev) => [...prev, chunk]);
    }
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

Phát Triển Cục Bộ

Generator kết nối tự động cấu hình tích hợp serve-local:

Chạy nx serve-local <website> cũng sẽ khởi động server FastAPI cục bộ của agent
Cấu hình runtime được ghi đè để trỏ đến URL HTTP cục bộ (ví dụ: http://localhost:8081/)
TypeScript client được tự động tạo lại khi API của agent thay đổi

pnpm nx serve-local <WebsiteProject>

yarn nx serve-local <WebsiteProject>

npx nx serve-local <WebsiteProject>

bunx nx serve-local <WebsiteProject>

Hạ Tầng

Nếu agent của bạn sử dụng IAM auth, vai trò đã xác thực của Cognito Identity Pool phải được cấp quyền để gọi agent. Tham khảo infrastructure construct của agent của bạn để biết phương thức grantInvokeAccess phù hợp.

Thông Tin Thêm

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