React a Agente TypeScript Strands

Nx Plugin for AWS proporciona un generador para integrar rápidamente tu TypeScript Strands Agent con un sitio web de React. Configura toda la configuración necesaria para conectarse a tu agente a través de tRPC sobre WebSocket, incluyendo soporte de autenticación de AWS IAM y Cognito. La integración proporciona seguridad de tipos completa de extremo a extremo entre tu frontend y el enrutador tRPC del agente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un sitio web de React (generado usando el generador ts#react-website)
2. Un TypeScript Strands Agent (generado usando el generador ts#strands-agent)
3. Cognito Auth agregado a través del generador ts#react-website-auth

Uso

Ejecutar el generador

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Se te pedirá que selecciones tu sitio web de React como el proyecto de origen y el proyecto que contiene tu Strands Agent como el proyecto de destino. Si tu proyecto de destino contiene múltiples componentes (como múltiples agentes u otros tipos de componentes), se te pedirá que especifiques un targetComponent para desambiguar.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.

Salida del generador

El generador crea la siguiente estructura en tu aplicación React:

• Directoriosrc

  • Directoriocomponents

    • <AgentName>AgentClientProvider.tsx Configura el cliente tRPC WebSocket y los enlaces al enrutador tRPC de tu agente
    • QueryClientProvider.tsx Proveedor del cliente TanStack React Query
  • Directoriohooks

    • useSigV4.tsx Hook para firmar solicitudes con SigV4 (solo IAM)
    • use<AgentName>Agent.tsx Hooks que devuelven el proxy de opciones tRPC y el cliente tRPC vanilla

Además, instala las dependencias requeridas:

• @trpc/client
• @trpc/tanstack-react-query
• @tanstack/react-query
• aws4fetch (si se usa autenticación IAM)

Cómo funciona

Conexión WebSocket

El cliente generado se conecta a tu Strands Agent a través de tRPC sobre WebSocket. El agente expone un enrutador tRPC (incluyendo la suscripción invoke para transmitir respuestas del agente) sobre un endpoint WebSocket.

• Desplegado: El ARN del runtime del agente se carga desde Runtime Configuration. El ARN se convierte a una URL WebSocket siguiendo el protocolo WebSocket de Bedrock AgentCore Runtime: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• Desarrollo local: Al ejecutar con serve-local, la anulación de configuración del runtime establece el valor a una URL ws:// local (por ejemplo, ws://localhost:8081/ws), y el cliente se conecta directamente

Autenticación

El código generado maneja la autenticación dependiendo de la configuración de tu agente:

• IAM (predeterminado): Usa URLs prefirmadas AWS SigV4 para autenticar la conexión WebSocket. Las credenciales se obtienen del Cognito Identity Pool configurado con la autenticación de tu sitio web. En modo serve-local, la firma se omite automáticamente cuando runtime-config.json no está presente
• Cognito: Incrusta el token de acceso JWT en el encabezado Sec-WebSocket-Protocol como un token bearer codificado en base64url, siguiendo el protocolo de autenticación WebSocket de AgentCore

Infraestructura

Si tu agente usa autenticación IAM, el rol autenticado del Cognito Identity Pool debe tener el permiso bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream para invocar agentes a través de 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],
  }),
);

Protocolo WebSocket

Al momento de escribir esto, el método grantInvoke del agent core runtime aún no incluye este permiso automáticamente (ver aws-cdk#37495).

Si tu agente usa autenticación Cognito, no necesitas definir ninguna infraestructura adicional para conectar tu sitio web a tu agente.

Usando el código generado

Usando TanStack Query

El caso de uso más común es transmitir la respuesta del agente usando la suscripción invoke con el hook use<AgentName>Agent, que devuelve un proxy de opciones tRPC para usar 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 de opciones tRPC

Para más detalles sobre el proxy de opciones tRPC y la integración con TanStack Query, consulta la documentación de tRPC TanStack React Query.

Usando el cliente tRPC Vanilla

El hook use<AgentName>AgentClient proporciona acceso al cliente tRPC vanilla para tener más control sobre el ciclo de vida de la suscripción:

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

Cliente tRPC vanilla

Para más detalles sobre el cliente tRPC vanilla, consulta la documentación del cliente Vanilla de tRPC.

Desarrollo local

El generador de conexión configura automáticamente la integración con serve-local para tu sitio web de React:

1. Ejecutar nx serve-local <website> también iniciará el servidor local del agente
2. La configuración del runtime se anula para apuntar a la URL WebSocket local (por ejemplo, ws://localhost:8081/ws)
3. Al igual que con las APIs conectadas, la autenticación se omite en modo serve-local cuando runtime-config.json no está presente

Recarga en caliente

El sitio web y el agente conectado se recargarán automáticamente, permitiéndote iterar rápidamente en ambos juntos sin desplegar a AWS.

Seguridad de tipos

La integración proporciona seguridad de tipos completa de extremo a extremo. Tu IDE proporcionará autocompletado completo y verificación de tipos para todas las llamadas de procedimientos del agente. Los tipos se infieren automáticamente de la definición del enrutador tRPC de tu agente, asegurando que cualquier cambio en la API de tu agente se refleje inmediatamente en tu código frontend.

Más información

Para más información, consulta:

• Guía de TypeScript Strands Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket