React vers Agent AG-UI

Nx Plugin for AWS fournit un générateur pour connecter un site web React à un Agent qui expose le protocole AG-UI. Il configure CopilotKit avec un HttpAgent @ag-ui/client sur votre site web, avec prise en charge de l’authentification AWS IAM et Cognito.

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#website)
Un Agent TypeScript ou Python avec protocol=ag-ui (généré en utilisant le générateur ts#agent ou py#agent)
Pour les agents déployés, l’authentification Cognito ajoutée via le générateur ts#website#auth

Utilisation

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

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

Vous serez invité à sélectionner votre site web React comme projet source et le projet contenant votre Agent AG-UI 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 un composant AguiProvider unique partagé, un hook par agent connecté, et un wrapper thématisé pour les composants de chat CopilotKit :

Répertoiresrc
- Répertoirecomponents
  - AguiProvider.tsx CopilotKitProvider unique pour chaque agent AG-UI. Créé lors de la première exécution de connection et mis à jour lors des exécutions suivantes pour enregistrer chaque nouvel agent.
  - Répertoirecopilot
    index.tsx Ré-exporte CopilotChat, CopilotSidebar et CopilotPopup avec des valeurs par défaut de slot qui correspondent à l’ux de votre site web (Cloudscape, Shadcn, ou aucun thème).
    ThemeComponents .tsx Composants de thème par slot (par ex. CloudscapeAssistantMessage.tsx, ShadcnChatInput.tsx). Fournis uniquement lorsque ux est cloudscape ou shadcn.
- Répertoirehooks
  - useAgui<AgentName>.tsx Enregistre un agent AG-UI. Un fichier par exécution de connection.
  - useSigV4.tsx Signature SigV4 (IAM uniquement)

Exécuter connection une deuxième fois pour un agent différent ajoute un nouveau hook useAgui<AgentName>.tsx et met à jour AguiProvider.tsx pour enregistrer les deux hooks — toutes les modifications personnalisées que vous avez apportées au provider sont préservées. main.tsx conserve son unique wrapper <AguiProvider> — vous ne vous retrouvez jamais avec des providers imbriqués.

Les dépendances suivantes sont ajoutées au package.json racine :

@copilotkit/react-core — fournit CopilotKitProvider et les composants de chat (CopilotChat, CopilotSidebar, CopilotPopup)
@ag-ui/client — HttpAgent utilisé par les hooks générés
aws4fetch, oidc-client-ts, react-oidc-context, @aws-sdk/credential-providers — authentification IAM uniquement
react-oidc-context — authentification Cognito

Comment ça fonctionne

Connexion AG-UI

Chaque hook useAgui<AgentName> lit la valeur d’exécution de son agent depuis la Configuration d’exécution et instancie un HttpAgent @ag-ui/client :

Déployé : la valeur d’exécution est un ARN Bedrock AgentCore Runtime, qui est converti en point de terminaison HTTPS AgentCore : https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT
Développement local : dev remplace la valeur par l’URL locale de l’agent (par ex. http://localhost:8081)

Le AguiProvider partagé appelle chaque hook généré et les étend tous dans selfManagedAgents sur un seul CopilotKitProvider, qui les expose tous aux composants CopilotKit.

Intégration CopilotKit

CopilotKit est le client React de référence officiel pour le protocole AG-UI et fournit des composants de chat prêts à l’emploi :

<CopilotChat /> — interface de chat complète
<CopilotSidebar /> — chat en panneau latéral fixe
<CopilotPopup /> — popup de chat flottant

Placez n’importe lequel de ces composants n’importe où à l’intérieur du wrapper <AguiProvider> (déjà câblé dans main.tsx pour vous).

Authentification

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

IAM (par défaut) : utilise des requêtes HTTP signées AWS SigV4. 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 l’en-tête Authorization en tant que jeton Bearer.

Sessions et Threads

AG-UI et AgentCore Runtime identifient chacun une conversation différemment, et le hook généré les relie ensemble :

threadId — l’identifiant de conversation AG-UI, envoyé dans le corps de la requête. CopilotKit génère un UUID aléatoire par chat sauf si vous passez un threadId explicite.
Session ID — la session AgentCore Runtime, envoyée dans l’en-tête X-Amzn-Bedrock-AgentCore-Runtime-Session-Id. Elle sélectionne la microVM qui traite la requête, et c’est ce sur quoi le session.ts / session.py de votre agent indexe l’état de la conversation.

Le hook dérive l’ID de session à partir de l’ID de thread, en le complétant à droite jusqu’aux 33 caractères requis par AgentCore Runtime :

function agentCoreSessionId(input: RunAgentInput): string {
  return (input.threadId ?? '').padEnd(33, '0');
}

Laisser threadId non défini est le plus simple — l’UUID généré par CopilotKit fait déjà 36 caractères. Si vous en passez un explicitement, assurez-vous qu’il fasse au moins 33 caractères, car le remplissage mappe les ID de thread qui ne diffèrent que par les caractères de fin sur la même session.

L’ID de session et l’ID de thread sont tous deux fournis par le navigateur. Pour restreindre chaque utilisateur à ses propres conversations, consultez le guide py#agent ou ts#agent.

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
Terraform

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.

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é

Ajout d’une interface de chat

Instanciez les composants CopilotKit avec agentId pour sélectionner l’agent à utiliser. L’id est le nom de l’agent — le même que celui que vous avez choisi lorsque vous avez exécuté le générateur ts#agent ou py#agent — et vous pouvez également le trouver dans le fichier de hook généré (par ex. la clé retournée par packages/web/src/hooks/useAgui<AgentName>.tsx).

Importez les composants de chat depuis le module ./components/copilot généré afin que le thème correspondant à l’ux de votre site web soit appliqué automatiquement :

import { CopilotChat } from './components/copilot';

function ChatPage() {
  return (
    <CopilotChat
      agentId="agent"
      labels={{
        welcomeMessageText: 'How can I help you today?',
        chatInputPlaceholder: 'Ask me anything...',
      }}
    />
  );
}

Connexion de plusieurs agents AG-UI

Exécutez le générateur connection une fois par agent. Chaque agent enregistré via le AguiProvider partagé est visible depuis n’importe où dans l’application — instanciez un composant CopilotKit avec un agentId différent pour router chaque chat vers l’agent souhaité :

import { CopilotChat } from './components/copilot';

<CopilotChat agentId="story" />    {/* talks to StoryAgent */}
<CopilotChat agentId="research" /> {/* talks to ResearchAgent */}

Personnalisation de l’apparence

<CopilotChat /> (et <CopilotSidebar />, <CopilotPopup />) utilisent un système de slots récursif — vous pouvez remplacer n’importe quel sous-composant par une chaîne de classe Tailwind, un objet de props, ou un composant React personnalisé. Consultez le guide des slots CopilotKit pour l’arborescence complète des slots.

Thèmes intégrés

Le générateur lit metadata.ux depuis votre projet de site web React et fournit un module wrapper thématisé à src/components/copilot/index.tsx afin que les composants de chat correspondent au reste de votre interface utilisateur sans aucune configuration supplémentaire :

`ux`	Style appliqué à `CopilotChat` / `CopilotSidebar` / `CopilotPopup`
`cloudscape`	Les messages s’affichent dans des `ChatBubble` Cloudscape avec des `Avatar` gen-AI (correspondant au modèle de chat IA générative Cloudscape) ; l’indicateur de saisie devient une `LoadingBar` et l’entrée est un `PromptInput`. Construit à partir de `@cloudscape-design/components` et `@cloudscape-design/chat-components`.
`shadcn`	Les messages de l’assistant s’affichent dans une bulle `bg-muted` avec un avatar `Sparkles` ; les messages de l’utilisateur s’affichent alignés à droite dans une bulle `bg-primary` avec un avatar `User`. L’entrée est un `Textarea` arrondi + un `Button` d’envoi/arrêt en forme de pilule (Entrée soumet, Maj+Entrée nouvelle ligne). Utilise les primitives shadcn du package partagé `common-shadcn`.
`none` (ou autre)	Pas de thème — le module ré-exporte simplement les composants CopilotKit par défaut.

Importez les composants thématisés depuis le module de thème local (pas directement depuis @copilotkit/react-core/v2) afin que le thème soit appliqué automatiquement :

import { CopilotChat } from './components/copilot';

<CopilotChat agentId="agent" />

Le thème est appliqué en tant que valeurs par défaut de slot, donc tout slot que vous passez explicitement l’emporte toujours — vous gardez le contrôle total chaque fois que vous avez besoin d’un remplacement ponctuel.

Personnalisation du thème

Le thème généré réside entièrement dans votre projet :

src/components/copilot/index.tsx — exporte les CopilotChat / CopilotSidebar / CopilotPopup thématisés et les objets cloudscapeCopilotTheme / shadcnCopilotTheme. Modifiez ce fichier pour changer le câblage par défaut des slots pour chaque chat dans votre application.
src/components/copilot/<ThemeComponent>.tsx — composants de thème par slot (par ex. CloudscapeAssistantMessage, ShadcnChatInput). Modifiez-les pour ajuster l’apparence d’un seul slot sans recâbler le thème.

Par exemple, pour intégrer votre propre rendu de message utilisateur tout en conservant le reste du thème, modifiez le fichier pertinent dans src/components/copilot/ et ré-exportez-le depuis index.tsx.

Style Tailwind via les slots

Les remplacements par chat fonctionnent toujours avec le thème — tout ce que vous passez comme prop de slot remplace la valeur par défaut du thème :

<CopilotChat
  agentId="agent"
  // style the input and its children
  input={{
    textArea: 'text-blue-600',
    sendButton: 'bg-blue-600 hover:bg-blue-700',
  }}
  // style nested message slots
  messageView={{
    assistantMessage: 'bg-blue-50 rounded-xl p-2',
    userMessage: 'bg-blue-100 rounded-xl',
  }}
/>

Remplacement d’un slot par un composant personnalisé

N’importe quel slot peut prendre un composant React au lieu d’un className, vous pouvez donc remplacer complètement la valeur par défaut :

import { CopilotChat } from './components/copilot';

const MySendButton: React.FC<{ onClick: () => void }> = ({ onClick }) => (
  <button onClick={onClick} className="my-send-btn">
    Send
  </button>
);

<CopilotChat
  agentId="agent"
  input={{ sendButton: MySendButton }}
/>;

Les remplacements plus profonds suivent la même structure — par ex. remplacer uniquement le bouton de copie sur les messages de l’assistant :

<CopilotChat
  agentId="agent"
  messageView={{
    assistantMessage: {
      copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
    },
  }}
/>

Développement local

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

L’exécution de nx dev <website> démarrera également le serveur local de l’agent
La configuration d’exécution est remplacée pour pointer vers l’URL AG-UI locale (par ex. http://localhost:8081)
Le site web et l’agent se rechargent à chaud ensemble

pnpm nx dev <WebsiteProject>

yarn nx dev <WebsiteProject>

npx nx dev <WebsiteProject>

bunx nx dev <WebsiteProject>