React vers Agent Python Strands

Nx Plugin for AWS fournit un générateur pour intégrer rapidement votre Python Strands Agent avec un site web React. Il configure tous les éléments nécessaires pour se connecter à votre agent via un client généré par OpenAPI et type-safe, incluant la prise en charge de l’authentification AWS IAM et Cognito.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

1. Un site web React (généré en utilisant le générateur ts#react-website)
2. Un Python Strands Agent (généré en utilisant le générateur py#strands-agent)
3. Cognito Auth ajouté via le générateur ts#react-website-auth

Utilisation

Exécuter le générateur

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - connection
5. Remplissez les paramètres requis
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Vous serez invité à sélectionner votre site web React comme projet source et le projet contenant votre Python Strands Agent comme projet cible. Si votre projet cible contient plusieurs composants (tels que plusieurs agents ou d’autres types de composants), vous serez invité à spécifier un targetComponent pour lever l’ambiguïté.

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.

Sortie du générateur

Le générateur crée les éléments suivants dans votre projet Python Strands Agent :

• Répertoirescripts

  • <agent_name>_openapi.py Script pour générer une spécification OpenAPI à partir de l’application FastAPI de l’agent
• project.json Une nouvelle cible <agent-name>-openapi est ajoutée

Le générateur crée la structure suivante dans votre application React :

• Répertoiresrc

  • Répertoirecomponents

    • <AgentName>Provider.tsx Provider pour le client OpenAPI
    • QueryClientProvider.tsx Provider du client TanStack React Query
  • Répertoirehooks

    • useSigV4.tsx Hook pour signer les requêtes avec SigV4 (IAM uniquement)
    • use<AgentName>.tsx Hook retournant le proxy d’options TanStack Query pour l’API de votre agent
    • use<AgentName>Client.tsx Hook retournant le client API vanilla
  • Répertoiregenerated

    • Répertoire<agent-name>

      • types.gen.ts Types générés à partir des modèles Pydantic de l’agent
      • client.gen.ts Client type-safe pour appeler l’API de votre agent
      • options-proxy.gen.ts Options des hooks TanStack Query pour interagir avec votre agent
• project.json Cibles ajoutées pour la génération du client et la surveillance des changements
• .gitignore Les fichiers client générés sont ignorés par défaut

Fonctionnement

Génération du client OpenAPI

Au moment de la compilation, l’application FastAPI du Python Strands Agent est introspectée pour générer une spécification OpenAPI. Cette spécification est ensuite utilisée pour générer un client TypeScript type-safe avec des hooks TanStack Query, suivant le même modèle que la connexion React vers FastAPI.

Chaque agent obtient son propre script OpenAPI isolé (par exemple, scripts/agent_openapi.py) afin que les projets avec plusieurs agents puissent générer des spécifications individuelles.

Authentification

Le code généré gère l’authentification en fonction de la configuration de votre agent :

• IAM (par défaut) : Utilise AWS SigV4 pour signer les requêtes HTTP. Les identifiants sont obtenus à partir du Cognito Identity Pool configuré avec l’authentification de votre site web
• Cognito : Intègre le jeton d’accès JWT dans un en-tête Authorization
• None : Aucune authentification

Utilisation du code généré

Utilisation du hook API

Le hook use<AgentName> fournit les options TanStack Query pour appeler les endpoints de l’API de votre 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 = (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>
  );
}

Utilisation du client vanilla

Le hook use<AgentName>Client fournit un accès direct au 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 (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>
  );
}

Développement local

Le générateur de connexion configure automatiquement l’intégration serve-local :

1. L’exécution de nx serve-local <website> démarrera également le serveur FastAPI local de l’agent
2. La configuration d’exécution est remplacée pour pointer vers l’URL HTTP locale (par exemple, http://localhost:8081/)
3. Le client TypeScript est automatiquement régénéré lorsque l’API de l’agent change

pnpm

pnpm nx serve-local <WebsiteProject>

yarn

yarn nx serve-local <WebsiteProject>

npm

npx nx serve-local <WebsiteProject>

bun

bunx nx serve-local <WebsiteProject>

Hot Reloading

Le site web et l’agent connecté se rechargeront à chaud, vous permettant d’itérer rapidement sur les deux ensemble sans déployer sur AWS.

Infrastructure

Si votre agent utilise l’authentification IAM, le rôle authentifié du Cognito Identity Pool doit obtenir la permission d’invoquer l’agent. Consultez la construction d’infrastructure de votre agent pour la méthode grantInvokeAccess appropriée.

Plus d’informations

Pour plus d’informations, veuillez consulter :

• Guide Python Strands Agent
• Guide de connexion React vers FastAPI
• TanStack Query Documentation