React vers Python Agent

Nx Plugin for AWS fournit un générateur pour intégrer rapidement votre Python 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 avec typage sécurisé, incluant la prise en charge de l’authentification AWS IAM et Cognito.

Agents AG-UI

Si votre Python Agent a été généré avec protocol=ag-ui, le générateur de connexion configure à la place CopilotKit et un HttpAgent @ag-ui/client sur le site web React. Consultez le guide React vers AG-UI Agent pour plus de détails.

Prérequis

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

1. Un site web React (généré avec le générateur ts#website)
2. Un Python Agent avec protocol=http (généré avec le générateur py#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 Python 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 les éléments suivants dans votre projet Python 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 avec typage sécurisé pour appeler l’API de votre agent
      • options-proxy.gen.ts Options de 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 du client généré sont ignorés par défaut

Fonctionnement

Génération du client OpenAPI

Au moment de la compilation, l’application FastAPI du Python 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 avec typage sécurisé et des hooks TanStack Query, suivant le même modèle que la connexion React vers FastAPI.

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

Configuration d’exécution

L’exécution de ce générateur de connexion modifie également le construct CDK/Terraform généré de l’agent pour publier son ARN d’exécution AgentCore 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. Consultez Configuration d’exécution pour plus de détails.

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 pool d’identités Cognito 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

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 du hook API

Le hook use<AgentName> fournit des 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 = (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>
  );
}

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

Développement local

Le générateur de connexion configure automatiquement l’intégration dev :

1. L’exécution de nx dev <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 dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

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.

Plus d’informations

Pour plus d’informations, veuillez consulter :

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