Site Web React vers AgentCore Gateway

Le générateur connection peut connecter un site Web React aux agents exposés par une AgentCore Gateway générée avec protocol: http.

Le navigateur communique uniquement avec la Gateway — les requêtes vers <gatewayUrl>/<targetName>/invocations sont transmises par proxy au runtime de l’agent derrière elle. Comme le site Web n’a jamais besoin d’atteindre directement les runtimes, les agents peuvent être déployés à l’intérieur d’un VPC, avec la Gateway comme point d’entrée unique et gouverné fournissant l’authentification et l’observabilité.

Prérequis

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

Un projet de site Web React
Un projet agentcore-gateway généré avec protocol: http
Au moins un agent AG-UI ou HTTP attaché à la Gateway via le générateur de connexion Gateway vers agent

Le générateur crée un client de site Web pour chaque agent AG-UI ou HTTP attaché à la Gateway (les cibles A2A sont ignorées — elles utilisent le protocole JSON-RPC agent-à-agent, pas un protocole de navigateur). Il génère les mêmes clients que lors de la connexion du site Web à chaque agent directement (AG-UI/CopilotKit pour les agents AG-UI, un client OpenAPI pour les agents Python HTTP), routés via la Gateway plutôt que vers le runtime.

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

Sélectionnez le projet de site Web comme source et le projet Gateway comme cible.

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

Pour chaque agent AG-UI exposé, les mêmes fichiers que la connexion React vers agent AG-UI sont générés (un AguiProvider, un hook useAgui<Agent> et un module de composant CopilotKit thématisé), avec le hook lisant l’URL de la Gateway depuis la configuration d’exécution :

Répertoirepackages/<website>/src
- Répertoirecomponents
  - AguiProvider.tsx Fournisseur CopilotKit enregistrant chaque agent
  - Répertoirecopilot/ Composants de chat thématisés
    …
- Répertoirehooks
  - useAgui<Agent>.tsx Se connecte à l’agent via la route /<targetName>/invocations de la Gateway

Pour chaque agent Python HTTP exposé, les mêmes fichiers que la connexion React vers agent Python sont générés (un client OpenAPI type-safe, des hooks et un provider), avec l’URL de base du client routée via la Gateway.

L’URL de la Gateway est enregistrée dans l’espace de noms connection.gateways.<GatewayClassName> de la Configuration d’exécution, elle est donc publiée dans le runtime-config.json du site Web.

Accorder l’accès aux utilisateurs du site Web

Pour une Gateway IAM, accordez aux utilisateurs authentifiés du site Web la permission de l’invoquer (une Gateway Cognito ne nécessite aucune autorisation — le navigateur s’authentifie avec son jeton bearer JWT à la place) :

CDK
Terraform

const identity = new UserIdentity(this, 'UserIdentity');
new Website(this, 'Website');

const myGateway = new MyGateway(this, 'MyGateway');
myGateway.addAgent(myAgent);
myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);

resource "aws_iam_policy" "gateway_invoke_policy" {
  name = "GatewayInvokePolicy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["bedrock-agentcore:InvokeGateway"]
        Resource = [module.my_gateway.gateway_arn]
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
}

Développement local

La cible dev du site Web gagne une dépendance sur la cible dev du projet Gateway, qui démarre la gateway locale plus chaque agent attaché. La configuration d’exécution du site Web est remplacée en mode local-dev pour pointer l’URL de la Gateway vers la gateway locale, de sorte que le navigateur exerce les mêmes routes /<targetName>/invocations localement :

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

Connexion de nouveaux agents

Le générateur connecte le site Web aux agents attachés à la Gateway au moment où il s’exécute. Après avoir attaché un autre agent à la Gateway, réexécutez le générateur de connexion pour générer son client de site Web — les clients existants restent intacts.