React a Python Agent

Nx Plugin for AWS proporciona un generador para integrar rápidamente tu Python 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.

Agentes AG-UI

Si tu Python Agent fue generado con protocol=ag-ui, el generador de conexión en su lugar configura CopilotKit y un HttpAgent de @ag-ui/client en el sitio web React. Consulta la guía React a AG-UI Agent para más detalles.

Requisitos previos

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

1. Un sitio web React (generado usando el generador ts#website)
2. Un Python Agent con protocol=http (generado usando el generador py#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 Python 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 lo siguiente en tu proyecto Python Agent:

• Directorioscripts

  • <agent_name>_openapi.py Script to generate an OpenAPI specification from the agent’s FastAPI app
• project.json A new <agent-name>-openapi target is added

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

• Directoriosrc

  • Directoriocomponents

    • <AgentName>Provider.tsx Provider for the OpenAPI client
    • QueryClientProvider.tsx TanStack React Query client provider
  • Directoriohooks

    • useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
    • use<AgentName>.tsx Hook returning the TanStack Query options proxy for your agent’s API
    • use<AgentName>Client.tsx Hook returning the vanilla API client
  • Directoriogenerated

    • Directorio<agent-name>

      • types.gen.ts Generated types from the agent’s Pydantic models
      • client.gen.ts Type-safe client for calling your agent’s API
      • options-proxy.gen.ts TanStack Query hooks options for interacting with your agent
• project.json Targets added for client generation and watching for changes
• .gitignore The generated client files are ignored by default

Cómo funciona

Generación del cliente OpenAPI

En tiempo de compilación, la aplicación FastAPI del Python Agent se inspecciona 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 alcance (por ejemplo, scripts/agent_openapi.py) para que los proyectos con múltiples agentes puedan generar especificaciones individuales.

Configuración en tiempo de ejecución

Ejecutar este generador de conexión también parchea el constructo CDK/Terraform generado del agente para publicar su ARN de tiempo de ejecución AgentCore en el runtime-config.json del sitio web (bajo el espacio de nombres connection), por lo que solo los agentes que conectes explícitamente están expuestos al frontend. Consulta Configuración en tiempo de ejecución para más detalles.

Autenticación

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

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

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 del 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 = (prompt: string) => {
    invoke.mutate({ prompt });
  };

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

Uso del 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 (prompt: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({ prompt })) {
      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 dev:

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

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

Hot Reloading

El sitio web y el agente conectado se recargarán en caliente, lo que te permite iterar rápidamente en ambos juntos sin implementar en AWS.

Más información

Para más información, consulta:

• Guía de Python Agent
• Guía de conexión React a FastAPI
• Documentación de TanStack Query