React a Agente Python Strands

Nx Plugin for AWS proporciona un generador para integrar rápidamente tu Python Strands Agent con un sitio web React. Configura toda la configuración necesaria para conectarse a tu agente a través de un cliente generado por OpenAPI con seguridad de tipos, incluyendo soporte para autenticación AWS IAM y Cognito.

Requisitos Previos

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

Un sitio web React (generado usando el generador ts#react-website)
Un Python Strands Agent (generado usando el generador py#strands-agent)
Cognito Auth agregado a través del generador ts#react-website-auth

Uso

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

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

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

Se te pedirá que selecciones tu sitio web React como el proyecto fuente y el proyecto que contiene tu Python Strands Agent como el proyecto objetivo. Si tu proyecto objetivo 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 lo siguiente en tu proyecto Python Strands Agent:

Directorioscripts
- <agent_name>_openapi.py Script para generar una especificación OpenAPI desde la aplicación FastAPI del agente
project.json Se agrega un nuevo target <agent-name>-openapi

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

Directoriosrc
- Directoriocomponents
  - <AgentName>Provider.tsx Proveedor para el cliente OpenAPI
  - QueryClientProvider.tsx Proveedor del cliente TanStack React Query
- Directoriohooks
  - useSigV4.tsx Hook para firmar solicitudes con SigV4 (solo IAM)
  - use<AgentName>.tsx Hook que devuelve el proxy de opciones de TanStack Query para la API de tu agente
  - use<AgentName>Client.tsx Hook que devuelve el cliente de API vanilla
- Directoriogenerated
  - Directorio<agent-name>
    types.gen.ts Tipos generados desde los modelos Pydantic del agente
    client.gen.ts Cliente con seguridad de tipos para llamar a la API de tu agente
    options-proxy.gen.ts Opciones de hooks de TanStack Query para interactuar con tu agente
project.json Targets agregados para la generación del cliente y vigilancia de cambios
.gitignore Los archivos del cliente generado son ignorados por defecto

Cómo Funciona

Generación del Cliente OpenAPI

En tiempo de compilación, la aplicación FastAPI del Python Strands Agent se introspecciona para generar una especificación OpenAPI. Esta especificación se utiliza luego para generar un cliente TypeScript con seguridad de tipos con hooks de TanStack Query, siguiendo el mismo patrón que la conexión React a FastAPI.

Cada agente obtiene su propio script OpenAPI con ámbito (por ejemplo, scripts/agent_openapi.py) para que los proyectos con múltiples agentes puedan generar especificaciones individuales.

Autenticación

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

IAM (por defecto): Usa AWS SigV4 para firmar solicitudes HTTP. Las credenciales se obtienen del Cognito Identity Pool configurado con la autenticación de tu sitio web
Cognito: Incrusta el token de acceso JWT en un encabezado Authorization
None: Sin autenticación

Usando el Código Generado

Usando el Hook de API

El hook use<AgentName> proporciona opciones de TanStack Query para llamar a los endpoints de la API de tu 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>
  );
}

Usando el Cliente Vanilla

El hook use<AgentName>Client proporciona acceso directo al cliente de 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>
  );
}

Desarrollo Local

El generador de conexión configura automáticamente la integración serve-local:

Ejecutar nx serve-local <website> también iniciará el servidor FastAPI local del agente
La configuración de tiempo de ejecución se sobrescribe para apuntar a la URL HTTP local (por ejemplo, http://localhost:8081/)
El cliente TypeScript se regenera automáticamente cuando la API del agente cambia

pnpm nx serve-local <WebsiteProject>

yarn nx serve-local <WebsiteProject>

npx nx serve-local <WebsiteProject>

bunx nx serve-local <WebsiteProject>

Infraestructura

Si tu agente usa autenticación IAM, el rol autenticado del Cognito Identity Pool debe recibir permiso para invocar al agente. Consulta el constructo de infraestructura de tu agente para el método grantInvokeAccess apropiado.

Más Información

Para más información, consulta: