React vers Agent TypeScript Strands

Nx Plugin for AWS fournit un générateur pour intégrer rapidement votre TypeScript Strands Agent avec un site web React. Il configure tous les paramètres nécessaires pour se connecter à votre agent via tRPC sur WebSocket, y compris la prise en charge de l’authentification AWS IAM et Cognito. L’intégration fournit une sécurité de type de bout en bout complète entre votre frontend et le routeur tRPC de l’agent.

Prérequis

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

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

Utilisation

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

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

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

Vous serez invité à sélectionner votre site web React comme projet source et le projet contenant votre 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 la structure suivante dans votre application React :

Répertoiresrc
- Répertoirecomponents
  - <AgentName>AgentClientProvider.tsx Configure le client tRPC WebSocket et les liaisons vers le routeur tRPC de votre agent
  - QueryClientProvider.tsx Fournisseur de client TanStack React Query
- Répertoirehooks
  - useSigV4.tsx Hook pour signer les requêtes avec SigV4 (IAM uniquement)
  - use<AgentName>Agent.tsx Hooks retournant le proxy d’options tRPC et le client tRPC vanilla

De plus, il installe les dépendances requises :

@trpc/client
@trpc/tanstack-react-query
@tanstack/react-query
aws4fetch (si vous utilisez l’authentification IAM)

Comment ça fonctionne

Connexion WebSocket

Le client généré se connecte à votre Strands Agent via tRPC sur WebSocket. L’agent expose un routeur tRPC (incluant la souscription invoke pour le streaming des réponses de l’agent) sur un point de terminaison WebSocket.

Déployé : L’ARN du runtime de l’agent est chargé depuis la Configuration du Runtime. L’ARN est converti en URL WebSocket suivant le protocole WebSocket Bedrock AgentCore Runtime : wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
Développement local : Lors de l’exécution avec serve-local, le remplacement de la configuration du runtime définit la valeur sur une URL ws:// locale (par exemple, ws://localhost:8081/ws), et le client se connecte directement

Authentification

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

IAM (par défaut) : Utilise les URL présignées AWS SigV4 pour authentifier la connexion WebSocket. Les identifiants sont obtenus à partir du pool d’identités Cognito configuré avec l’authentification de votre site web. En mode serve-local, la signature est automatiquement ignorée lorsque runtime-config.json n’est pas présent
Cognito : Intègre le jeton d’accès JWT dans l’en-tête Sec-WebSocket-Protocol en tant que jeton bearer encodé en base64url, suivant le protocole d’authentification WebSocket AgentCore

Infrastructure

Si votre agent utilise l’authentification IAM, le rôle authentifié du pool d’identités Cognito doit avoir la permission bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream pour invoquer les agents via WebSocket :

const identity = new UserIdentity(this, 'Identity');
const myAgent = new MyAgent(this, 'MyAgent');

identity.identityPool.authenticatedRole.addToPrincipalPolicy(
  new PolicyStatement({
    actions: ['bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream'],
    resources: [myAgent.agentCoreRuntime.agentRuntimeArn],
  }),
);

Si votre agent utilise l’authentification Cognito, vous n’avez pas besoin de définir d’infrastructure supplémentaire pour connecter votre site web à votre agent.

Utilisation du code généré

Utilisation de TanStack Query

Le cas d’utilisation le plus courant est le streaming de la réponse de l’agent en utilisant la souscription invoke avec le hook use<AgentName>Agent, qui retourne un proxy d’options tRPC pour une utilisation avec 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(
      { message: '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>
  );
}

Utilisation du client tRPC vanilla

Le hook use<AgentName>AgentClient fournit un accès au client tRPC vanilla pour plus de contrôle sur le cycle de vie de la souscription :

import { useState } from 'react';
import { useMyAgentAgentClient } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const client = useMyAgentAgentClient();
  const [messages, setMessages] = useState<string[]>([]);

  const sendMessage = (message: string) => {
    const subscription = client.invoke.subscribe(
      { message },
      {
        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>
  );
}

Développement local

Le générateur de connexion configure automatiquement l’intégration serve-local pour votre site web react :

L’exécution de nx serve-local <website> démarrera également le serveur local de l’agent
La configuration du runtime est remplacée pour pointer vers l’URL WebSocket locale (par exemple, ws://localhost:8081/ws)
Comme avec les API connectées, l’authentification est ignorée en mode serve-local lorsque runtime-config.json n’est pas présent

Sécurité des types

L’intégration fournit une sécurité de type complète de bout en bout. Votre IDE fournira une autocomplétion complète et une vérification de type pour tous les appels de procédure de l’agent. Les types sont automatiquement inférés à partir de la définition du routeur tRPC de votre agent, garantissant que tout changement dans l’API de votre agent est immédiatement reflété dans votre code frontend.

Plus d’informations

Pour plus d’informations, veuillez vous référer à :