React a TypeScript Agent

Nx Plugin for AWS proporciona un generador para integrar rápidamente tu TypeScript Agent con un sitio web React. Configura toda la configuración necesaria para conectarse a tu agente a través de tRPC sobre WebSocket, incluyendo soporte para autenticación con 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 React (generado usando el generador ts#website)
2. Un TypeScript Agent (generado usando el generador ts#agent)
3. Cognito Auth agregado a través del generador ts#website#auth

Uso

Ejecutar el generador

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

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

Se te pedirá que selecciones tu sitio web React como el proyecto de origen y el proyecto que contiene tu 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.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

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 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 la Configuración de Runtime. Ejecutar este generador de conexión también parchea el constructo CDK/Terraform generado del agente para publicar su ARN en el runtime-config.json del sitio web (bajo el namespace connection), por lo que solo los agentes que conectes explícitamente se exponen al frontend. 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 dev, la anulación de configuración de runtime establece el valor a una URL local ws:// (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 de AWS SigV4 para autenticar la conexión WebSocket. Las credenciales se obtienen del Identity Pool de Cognito configurado con la autenticación de tu sitio web. En modo dev, 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 utiliza autenticación IAM, el rol autenticado del Cognito Identity Pool debe tener permiso para invocar el agente.

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 conecta todas las acciones de invocación de AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) en el ARN de runtime del agente.

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
}

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

Uso del código generado

Uso de 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(
      { 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 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.

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

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 dev para tu sitio web react:

1. Ejecutar nx dev <website> también iniciará el servidor local del agente
2. La configuración de 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 dev cuando runtime-config.json no está presente

Hot Reloading

El sitio web y el agente conectado se recargarán en caliente, 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 a 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 Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket