React a Python Agent

Nx Plugin for AWS fornisce un generatore per integrare rapidamente il tuo Python Agent con un sito web React. Configura tutte le impostazioni necessarie per connettersi al tuo agent tramite un client generato da OpenAPI type-safe, incluso il supporto per l’autenticazione AWS IAM e Cognito.

Agent AG-UI

Se il tuo Python Agent è stato generato con protocol=ag-ui, il generatore di connessione configura invece CopilotKit e un HttpAgent @ag-ui/client sul sito web React. Consulta la guida React a AG-UI Agent per i dettagli.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un sito web React (generato utilizzando il generatore ts#website)
2. Un Python Agent con protocol=http (generato utilizzando il generatore py#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 Python 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 quanto segue nel tuo progetto Python Agent:

• Directoryscripts

  • <agent_name>_openapi.py Script per generare una specifica OpenAPI dall’app FastAPI dell’agent
• project.json Viene aggiunto un nuovo target <agent-name>-openapi

Il generatore crea la seguente struttura nella tua applicazione React:

• Directorysrc

  • Directorycomponents

    • <AgentName>Provider.tsx Provider per il client OpenAPI
    • QueryClientProvider.tsx Provider del client TanStack React Query
  • Directoryhooks

    • useSigV4.tsx Hook per firmare le richieste con SigV4 (solo IAM)
    • use<AgentName>.tsx Hook che restituisce il proxy delle opzioni TanStack Query per l’API del tuo agent
    • use<AgentName>Client.tsx Hook che restituisce il client API vanilla
  • Directorygenerated

    • Directory<agent-name>

      • types.gen.ts Tipi generati dai modelli Pydantic dell’agent
      • client.gen.ts Client type-safe per chiamare l’API del tuo agent
      • options-proxy.gen.ts Opzioni degli hook TanStack Query per interagire con il tuo agent
• project.json Target aggiunti per la generazione del client e il monitoraggio delle modifiche
• .gitignore I file del client generati sono ignorati per impostazione predefinita

Come Funziona

Generazione del Client OpenAPI

Al momento della build, l’app FastAPI del Python Agent viene ispezionata per generare una specifica OpenAPI. Questa specifica viene quindi utilizzata per generare un client TypeScript type-safe con hook TanStack Query, seguendo lo stesso pattern della connessione React a FastAPI.

Ogni agent ottiene il proprio script OpenAPI con scope (ad esempio, scripts/agent_openapi.py) in modo che i progetti con più agent possano generare specifiche individuali.

Configurazione Runtime

L’esecuzione di questo generatore di connessione modifica anche il costrutto CDK/Terraform generato dell’agent per pubblicare il suo ARN runtime AgentCore nel runtime-config.json del sito web (sotto il namespace connection), quindi solo gli agent che connetti esplicitamente sono esposti al frontend. Consulta Configurazione Runtime per i dettagli.

Autenticazione

Il codice generato gestisce l’autenticazione in base alla configurazione del tuo agent:

• IAM (predefinito): Utilizza AWS SigV4 per firmare le richieste HTTP. Le credenziali vengono ottenute dal Cognito Identity Pool configurato con l’autenticazione del tuo sito web
• Cognito: Incorpora il token di accesso JWT in un header Authorization
• None: Nessuna autenticazione

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 dell’Hook API

L’hook use<AgentName> fornisce opzioni TanStack Query per chiamare gli endpoint API del tuo agent:

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

Utilizzo del Client Vanilla

L’hook use<AgentName>Client fornisce accesso diretto al client 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>
  );
}

Sviluppo Locale

Il generatore di connessione configura automaticamente l’integrazione dev:

1. L’esecuzione di nx dev <website> avvierà anche il server FastAPI locale dell’agent
2. La configurazione runtime viene sovrascritta per puntare all’URL HTTP locale (ad esempio, http://localhost:8081/)
3. Il client TypeScript viene rigenerato automaticamente quando l’API dell’agent cambia

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

Hot Reloading

Il sito web e l’agent connesso si ricaricheranno automaticamente, consentendoti di iterare rapidamente su entrambi insieme senza distribuire su AWS.

Ulteriori Informazioni

Per ulteriori informazioni, consulta:

• Guida Python Agent
• Guida alla Connessione React a FastAPI
• Documentazione TanStack Query