React a TypeScript Strands Agent

Nx Plugin for AWS fornisce un generatore per integrare rapidamente il tuo TypeScript Strands Agent con un sito web React. Configura tutta la configurazione necessaria per connettersi al tuo agente tramite tRPC su WebSocket, incluso il supporto per l’autenticazione AWS IAM e Cognito. L’integrazione fornisce una completa type safety end-to-end tra il tuo frontend e il router tRPC dell’agente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un sito web React (generato utilizzando il generatore ts#react-website)
2. Un TypeScript Strands Agent (generato utilizzando il generatore ts#strands-agent)
3. Cognito Auth aggiunto tramite il generatore ts#react-website-auth

Utilizzo

Eseguire il Generatore

VSCode

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Ti verrà richiesto di selezionare il tuo sito web React come progetto di origine e il progetto contenente il tuo 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 la seguente struttura nella tua applicazione React:

• Directorysrc

  • Directorycomponents

    • <AgentName>AgentClientProvider.tsx Configura il client tRPC WebSocket e i binding al router tRPC del tuo agente
    • QueryClientProvider.tsx Provider del client TanStack React Query
  • Directoryhooks

    • useSigV4.tsx Hook per firmare le richieste con SigV4 (solo IAM)
    • use<AgentName>Agent.tsx Hooks che restituiscono il proxy delle opzioni tRPC e il client tRPC vanilla

Inoltre, installa le dipendenze richieste:

• @trpc/client
• @trpc/tanstack-react-query
• @tanstack/react-query
• aws4fetch (se si utilizza l’autenticazione IAM)

Come Funziona

Connessione WebSocket

Il client generato si connette al tuo Strands Agent tramite tRPC su WebSocket. L’agente espone un router tRPC (inclusa la subscription invoke per lo streaming delle risposte dell’agente) su un endpoint WebSocket.

• Deployed: L’ARN del runtime dell’agente viene caricato dalla Configurazione Runtime. L’ARN viene convertito in un URL WebSocket seguendo il protocollo WebSocket di Bedrock AgentCore Runtime: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• Sviluppo locale: Quando si esegue con serve-local, l’override della configurazione runtime imposta il valore su un URL locale ws:// (ad es., ws://localhost:8081/ws), e il client si connette direttamente

Autenticazione

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

• IAM (predefinito): Utilizza URL pre-firmati AWS SigV4 per autenticare la connessione WebSocket. Le credenziali vengono ottenute dal Cognito Identity Pool configurato con l’autenticazione del tuo sito web. In modalità serve-local, la firma viene automaticamente saltata quando runtime-config.json non è presente
• Cognito: Incorpora il token di accesso JWT nell’header Sec-WebSocket-Protocol come token bearer codificato in base64url, seguendo il protocollo di autenticazione WebSocket di AgentCore

Infrastruttura

Se il tuo agente utilizza l’autenticazione IAM, il ruolo autenticato del Cognito Identity Pool deve avere il permesso bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream per invocare gli agenti tramite 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],
  }),
);

Protocollo WebSocket

Al momento della stesura, il metodo grantInvoke del runtime dell’agent core non include ancora questo permesso automaticamente (vedi aws-cdk#37495).

Se il tuo agente utilizza l’autenticazione Cognito, non è necessario definire alcuna infrastruttura aggiuntiva per connettere il tuo sito web al tuo agente.

Utilizzare il Codice Generato

Utilizzare TanStack Query

Il caso d’uso più comune è lo streaming della risposta dell’agente utilizzando la subscription invoke con l’hook use<AgentName>Agent, che restituisce un proxy delle opzioni tRPC per l’uso con 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 opzioni tRPC

Per maggiori dettagli sul proxy delle opzioni tRPC e sull’integrazione con TanStack Query, consulta la documentazione di tRPC TanStack React Query.

Utilizzare il Client tRPC Vanilla

L’hook use<AgentName>AgentClient fornisce accesso al client tRPC vanilla per un maggiore controllo sul ciclo di vita della 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

Per maggiori dettagli sul client tRPC vanilla, consulta la documentazione del Client Vanilla tRPC.

Sviluppo Locale

Il generatore di connessione configura automaticamente l’integrazione con serve-local per il tuo sito web react:

1. L’esecuzione di nx serve-local <website> avvierà anche il server locale dell’agente
2. La configurazione runtime viene sovrascritta per puntare all’URL WebSocket locale (ad es., ws://localhost:8081/ws)
3. Come con le API connesse, l’autenticazione viene saltata in modalità serve-local quando runtime-config.json non è presente

Ricaricamento a caldo

Il sito web e l’agente connesso effettueranno l’hot-reload, permettendoti di iterare rapidamente su entrambi insieme senza distribuire su AWS.

Type Safety

L’integrazione fornisce una completa type safety end-to-end. Il tuo IDE fornirà autocompletamento completo e controllo dei tipi per tutte le chiamate alle procedure dell’agente. I tipi vengono automaticamente inferiti dalla definizione del router tRPC del tuo agente, garantendo che qualsiasi modifica all’API del tuo agente si rifletta immediatamente nel codice del frontend.

Maggiori Informazioni

Per maggiori informazioni, consulta:

• Guida TypeScript Strands Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket