React a Python Strands Agent

Nx Plugin for AWS fornisce un generatore per integrare rapidamente il tuo Python Strands Agent con un sito web React. Configura tutto il necessario per connettersi al tuo agente tramite un client generato da OpenAPI type-safe, incluso il supporto per l’autenticazione AWS IAM e Cognito.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

Un sito web React (generato utilizzando il generatore ts#react-website)
Un Python Strands Agent (generato utilizzando il generatore py#strands-agent)
Cognito Auth aggiunto tramite il generatore ts#react-website-auth

Utilizzo

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Ti verrà richiesto di selezionare il tuo sito web React come progetto di origine e il progetto contenente il tuo Python Strands Agent come progetto di destinazione. Se il tuo progetto di destinazione contiene più componenti (come più agenti o altri tipi di componenti), ti verrà richiesto di specificare un targetComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.

Output del Generatore

Il generatore crea quanto segue nel tuo progetto Python Strands Agent:

Directoryscripts
- <agent_name>_openapi.py Script per generare una specifica OpenAPI dall’app FastAPI dell’agente
project.json Viene aggiunto un nuovo target <agent-name>-openapi

Il generatore crea la seguente struttura nella tua applicazione React:

Directorysrc
- Directorycomponents
  - <AgentName>Provider.tsx Provider per il client OpenAPI
  - QueryClientProvider.tsx Provider del client TanStack React Query
- Directoryhooks
  - useSigV4.tsx Hook per firmare le richieste con SigV4 (solo IAM)
  - use<AgentName>.tsx Hook che restituisce il proxy delle opzioni TanStack Query per l’API del tuo agente
  - use<AgentName>Client.tsx Hook che restituisce il client API vanilla
- Directorygenerated
  - Directory<agent-name>
    types.gen.ts Tipi generati dai modelli Pydantic dell’agente
    client.gen.ts Client type-safe per chiamare l’API del tuo agente
    options-proxy.gen.ts Opzioni degli hook TanStack Query per interagire con il tuo agente
project.json Target aggiunti per la generazione del client e il monitoraggio delle modifiche
.gitignore I file del client generati sono ignorati per impostazione predefinita

Come Funziona

Generazione del Client OpenAPI

Al momento della build, l’app FastAPI del Python Strands Agent viene introspezionata per generare una specifica OpenAPI. Questa specifica viene quindi utilizzata per generare un client TypeScript type-safe con hook TanStack Query, seguendo lo stesso pattern della connessione React to FastAPI.

Ogni agente ottiene il proprio script OpenAPI con scope (ad es., scripts/agent_openapi.py) in modo che i progetti con più agenti possano generare specifiche individuali.

Autenticazione

Il codice generato gestisce l’autenticazione in base alla configurazione del tuo agente:

IAM (predefinito): Utilizza AWS SigV4 per firmare le richieste HTTP. Le credenziali vengono ottenute dal Cognito Identity Pool configurato con l’autenticazione del tuo sito web
Cognito: Incorpora il token di accesso JWT in un header Authorization
None: Nessuna autenticazione

Utilizzo del Codice Generato

Utilizzo dell’Hook API

L’hook use<AgentName> fornisce opzioni TanStack Query per chiamare gli endpoint API del tuo agente:

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

Utilizzo del Client Vanilla

L’hook use<AgentName>Client fornisce accesso diretto al client API:

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

Sviluppo Locale

Il generatore di connessione configura automaticamente l’integrazione serve-local:

L’esecuzione di nx serve-local <website> avvierà anche il server FastAPI locale dell’agente
La configurazione runtime viene sovrascritta per puntare all’URL HTTP locale (ad es., http://localhost:8081/)
Il client TypeScript viene rigenerato automaticamente quando l’API dell’agente cambia

pnpm nx serve-local <WebsiteProject>

yarn nx serve-local <WebsiteProject>

npx nx serve-local <WebsiteProject>

bunx nx serve-local <WebsiteProject>

Infrastruttura

Se il tuo agente utilizza l’autenticazione IAM, il ruolo autenticato del Cognito Identity Pool deve avere il permesso di invocare l’agente. Fai riferimento al costrutto dell’infrastruttura del tuo agente per il metodo grantInvokeAccess appropriato.

Ulteriori Informazioni

Per ulteriori informazioni, consulta: