React a TypeScript Agent

Nx Plugin for AWS fornisce un generatore per integrare rapidamente il tuo TypeScript Agent con un sito web React. Configura tutte le impostazioni necessarie per connettersi al tuo agent 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’agent.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

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

Utilizzo

Esegui il Generatore

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

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

Ti verrà richiesto di selezionare il tuo sito web React come progetto sorgente e il progetto contenente il tuo Agent come progetto di destinazione. Se il tuo progetto di destinazione contiene più componenti (come più agent 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.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

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 agent
    • QueryClientProvider.tsx Provider del client TanStack React Query
  • Directoryhooks

    • useSigV4.tsx Hook per firmare le richieste con SigV4 (solo IAM)
    • use<AgentName>Agent.tsx Hook 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 Agent tramite tRPC su WebSocket. L’agent espone un router tRPC (inclusa la subscription invoke per lo streaming delle risposte dell’agent) su un endpoint WebSocket.

• Deployed: L’ARN del runtime dell’agent viene caricato dalla Configurazione Runtime. L’esecuzione di questo generatore di connessione modifica anche il costrutto CDK/Terraform generato dall’agent per pubblicare il suo ARN nel runtime-config.json del sito web (sotto il namespace connection), quindi solo gli agent che connetti esplicitamente sono esposti al frontend. 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 dev, l’override della configurazione runtime imposta il valore su un URL ws:// locale (ad es., ws://localhost:8081/ws), e il client si connette direttamente

Autenticazione

Il codice generato gestisce l’autenticazione a seconda della configurazione del tuo agent:

• 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à dev, 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 agent utilizza l’autenticazione IAM, il ruolo autenticato del Cognito Identity Pool deve avere il permesso di invocare l’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 collega tutte le azioni di invocazione di AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) sull’ARN di runtime dell’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
}

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

Utilizzo del Codice Generato

Utilizzo di TanStack Query

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

Proxy delle Opzioni tRPC

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

Utilizzo del 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 = (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>
  );
}

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 dev per il tuo sito web react:

1. L’esecuzione di nx dev <website> avvierà anche il server locale dell’agent
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à dev quando runtime-config.json non è presente

Hot Reloading

Il sito web e l’agent connesso si ricaricheranno automaticamente, consentendoti 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’agent. I tipi vengono automaticamente dedotti dalla definizione del router tRPC del tuo agent, garantendo che qualsiasi modifica all’API del tuo agent si rifletta immediatamente nel codice del tuo frontend.

Ulteriori Informazioni

Per ulteriori informazioni, consulta:

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