React đến Python Agent

Nx Plugin for AWS cung cấp một generator để nhanh chóng tích hợp Python Agent của bạn với một website React. Nó thiết lập tất cả cá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.

AG-UI agents

Nếu Python Agent của bạn được tạo với protocol=ag-ui, connection generator sẽ thay vào đó thiết lập CopilotKit và một HttpAgent từ @ag-ui/client trên website React. Xem hướng dẫn React to AG-UI Agent để biết chi tiết.

Đ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 Python Agent với protocol=http (được tạo bằng py#agent generator)
3. Cognito Auth được thêm vào thông 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 mình làm source project và project chứa Python Agent của bạn làm target project. Nếu target project của bạn chứa nhiều component (chẳng hạn 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 những thứ sau trong project Python Agent của bạn:

• Thư mụcscripts

  • <agent_name>_openapi.py Script để tạo một OpenAPI specification từ FastAPI app 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ề TanStack Query options proxy 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 Pydantic model của agent
      • client.gen.ts Client type-safe để gọi API của agent
      • options-proxy.gen.ts TanStack Query hooks options để tương tác với agent
• project.json Các target được thêm vào để tạo client và theo dõi các thay đổi
• .gitignore Các file client được tạo ra mặc định bị bỏ qua

Cách hoạt động

Tạo OpenAPI Client

Tại thời điểm build, FastAPI app của Python Agent được introspect để tạo một OpenAPI specification. Spec này sau đó được sử dụng để tạo một TypeScript client type-safe với TanStack Query hooks, theo cùng một pattern như React to FastAPI connection.

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

Cấu hình Runtime

Chạy connection generator này cũng vá lại CDK/Terraform construct được tạo của agent để xuất bản AgentCore runtime 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 một cách rõ ràng mới được expose ra frontend. Xem Runtime Configuration để biết chi tiết.

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:

• 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 website
• Cognito: Nhúng JWT access token vào Authorization header
• None: Không có xác thực

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

Sử dụng API Hook

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

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 = (prompt: string) => {
    invoke.mutate({ prompt });
  };

  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 (prompt: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({ prompt })) {
      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ộ

Connection generator tự động cấu hình tích hợp dev:

1. Chạy nx dev <website> cũng sẽ khởi động local FastAPI server của agent
2. Runtime config được ghi đè để trỏ đến local HTTP URL (ví dụ: http://localhost:8081/)
3. TypeScript client được tự động tạo lại khi API của agent thay đổi

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

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.

Thông tin thêm

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

• Python Agent Guide
• React to FastAPI Connection Guide
• TanStack Query Documentation