React vers TypeScript Agent

Nx Plugin for AWS fournit un générateur pour intégrer rapidement votre TypeScript 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 complète de bout en bout entre votre frontend et le routeur tRPC de l’agent.

Prérequis

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

1. Un site web React (généré à l’aide du générateur ts#website)
2. Un TypeScript Agent (généré à l’aide du générateur ts#agent)
3. Cognito Auth ajouté via le générateur ts#website#auth

Utilisation

Exécuter le générateur

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

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

Vous serez invité à sélectionner votre site web React comme projet source et le projet contenant votre 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.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

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 Sets up the tRPC WebSocket client and bindings to your agent’s tRPC router
    • QueryClientProvider.tsx TanStack React Query client provider
  • Répertoirehooks

    • useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
    • use<AgentName>Agent.tsx Hooks returning the tRPC options proxy and vanilla tRPC client

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 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 Runtime. L’exécution de ce générateur de connexion corrige également le construct CDK/Terraform généré de l’agent pour publier son ARN dans le runtime-config.json du site web (sous l’espace de noms connection), de sorte que seuls les agents que vous connectez explicitement sont exposés au frontend. L’ARN est converti en une 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 dev, le remplacement de la configuration 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 des URL présignées AWS SigV4 pour authentifier la connexion WebSocket. Les informations d’identification sont obtenues à partir du pool d’identités Cognito configuré avec l’authentification de votre site web. En mode dev, 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 sous forme de 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 recevoir l’autorisation d’invoquer 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 configure toutes les actions d’invocation AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) sur l’ARN d’exécution de l’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
}

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 renvoie 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(
      { prompt: '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>
  );
}

Proxy d’options tRPC

Pour plus de détails sur le proxy d’options tRPC et l’intégration TanStack Query, consultez la documentation tRPC TanStack React Query.

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

Client tRPC vanilla

Pour plus de détails sur le client tRPC vanilla, consultez la documentation du client vanilla tRPC.

Développement local

Le générateur de connexion configure automatiquement l’intégration dev pour votre site web React :

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

Rechargement à chaud

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.

Sécurité des types

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

Plus d’informations

Pour plus d’informations, veuillez consulter :

• Guide TypeScript Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket