React ad AG-UI Agent

Nx Plugin for AWS fornisce un generatore per connettere un sito web React a un Agent che espone il protocollo AG-UI. Collega CopilotKit con un HttpAgent @ag-ui/client sul tuo sito web, con supporto per l’autenticazione AWS IAM e Cognito.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un sito web React (generato utilizzando il generatore ts#website)
2. Un Agent TypeScript o Python con protocol=ag-ui (generato utilizzando il generatore ts#agent o py#agent)
3. Per gli agent distribuiti, Cognito Auth aggiunto tramite il generatore ts#website#auth

Utilizzo

Eseguire il Generatore

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Ti verrà richiesto di selezionare il tuo sito web React come progetto sorgente e il progetto contenente il tuo AG-UI Agent come progetto di destinazione. Se il tuo progetto di destinazione contiene più componenti (come più agent o altri tipi di componenti), ti verrà richiesto di specificare un targetComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore crea un singolo componente condiviso AguiProvider, un hook per ogni agent connesso e un wrapper tematizzato per i componenti chat di CopilotKit:

• Directorysrc

  • Directorycomponents

    • AguiProvider.tsx Singolo CopilotKitProvider per ogni agent AG-UI. Creato alla prima esecuzione di connection e aggiornato nelle esecuzioni successive per registrare ogni nuovo agent.
    • Directorycopilot

      • index.tsx Ri-esporta CopilotChat, CopilotSidebar e CopilotPopup con valori predefiniti per gli slot che corrispondono al ux del tuo sito web (Cloudscape, Shadcn, o nessun tema).
      • ThemeComponents .tsx Componenti tema per slot (ad es. CloudscapeAssistantMessage.tsx, ShadcnChatInput.tsx). Forniti solo quando ux è cloudscape o shadcn.
  • Directoryhooks

    • useAgui<AgentName>.tsx Registra un agent AG-UI. Un file per esecuzione di connection.
    • useSigV4.tsx Firma SigV4 (solo IAM)

Eseguire connection una seconda volta per un agent diverso aggiunge un nuovo hook useAgui<AgentName>.tsx e aggiorna AguiProvider.tsx per registrare entrambi gli hook — eventuali modifiche personalizzate apportate al provider vengono preservate. main.tsx mantiene il suo singolo wrapper <AguiProvider> — non ti ritroverai mai con provider annidati.

Le seguenti dipendenze vengono aggiunte al package.json radice:

• @copilotkit/react-core — fornisce CopilotKitProvider e componenti chat (CopilotChat, CopilotSidebar, CopilotPopup)
• @ag-ui/client — HttpAgent utilizzato dagli hook generati
• aws4fetch, oidc-client-ts, react-oidc-context, @aws-sdk/credential-providers — solo autenticazione IAM
• react-oidc-context — autenticazione Cognito

Come Funziona

Connessione AG-UI

Ogni hook useAgui<AgentName> legge il valore runtime del suo agent dalla Configurazione Runtime e istanzia un HttpAgent @ag-ui/client:

• Distribuito: il valore runtime è un ARN Bedrock AgentCore Runtime, che viene convertito nell’endpoint HTTPS AgentCore: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT
• Sviluppo locale: dev sovrascrive il valore con l’URL locale dell’agent (ad es. http://localhost:8081)

L’AguiProvider condiviso chiama ogni hook generato e distribuisce ciascuno in selfManagedAgents su un singolo CopilotKitProvider, che li espone tutti ai componenti CopilotKit.

Integrazione CopilotKit

CopilotKit è il client React di riferimento di prima parte per il protocollo AG-UI e fornisce componenti chat pronti all’uso:

• <CopilotChat /> — interfaccia chat completa
• <CopilotSidebar /> — chat a pannello laterale fisso
• <CopilotPopup /> — popup chat flottante

Posiziona uno qualsiasi di questi ovunque all’interno del wrapper <AguiProvider> (già collegato in main.tsx per te).

Autenticazione

Il codice generato gestisce l’autenticazione in base alla configurazione del tuo agent:

• IAM (predefinito): utilizza richieste HTTP firmate con AWS SigV4. Le credenziali vengono ottenute dal Cognito Identity Pool configurato con l’autenticazione del tuo sito web.
• Cognito: incorpora il token di accesso JWT nell’header Authorization come Bearer token.

Sessioni e Thread

AG-UI e AgentCore Runtime identificano ciascuno una conversazione in modo diverso, e l’hook generato li collega insieme:

• threadId — l’identificatore di conversazione AG-UI, inviato nel corpo della richiesta. CopilotKit genera un UUID casuale per chat a meno che non passi un threadId esplicito.
• Session ID — la sessione AgentCore Runtime, inviata nell’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id. Seleziona la microVM che serve la richiesta, ed è ciò su cui il session.ts / session.py del tuo agent chiave lo stato della conversazione.

L’hook deriva il session ID dal thread ID, riempiendolo a destra fino ai 33 caratteri richiesti da AgentCore Runtime:

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

Lasciare threadId non impostato è il modo più semplice — l’UUID generato da CopilotKit è già di 36 caratteri. Se ne passi uno esplicitamente, rendilo di almeno 33 caratteri, poiché il riempimento mappa thread ID che differiscono solo nei caratteri finali sulla stessa sessione.

Sia il Session ID che il Thread ID sono forniti dal browser. Per limitare ogni utente alle proprie conversazioni, fai riferimento alla guida py#agent o ts#agent.

Infrastruttura

Se il tuo agent utilizza l’autenticazione IAM, il ruolo autenticato del Cognito Identity Pool deve avere il permesso di invocare 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 collega tutte le azioni di invocazione di AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) sull’ARN di runtime dell’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
}

Se il tuo agent utilizza l’autenticazione Cognito, non è necessario definire alcuna infrastruttura aggiuntiva per connettere il tuo sito web al tuo agent.

Utilizzo del Codice Generato

Aggiungere un’Interfaccia Chat

Istanzia i componenti CopilotKit con agentId per selezionare quale agent utilizzare. L’id è il nome dell’agent — lo stesso che hai scelto quando hai eseguito il generatore ts#agent o py#agent — e puoi anche trovarlo nel file hook generato (ad es. la chiave restituita da packages/web/src/hooks/useAgui<AgentName>.tsx).

Importa i componenti chat dal modulo generato ./components/copilot in modo che il tema corrispondente al ux del tuo sito web venga applicato automaticamente:

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

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

Connettere Più Agent AG-UI

Esegui il generatore connection una volta per agent. Ogni agent registrato tramite l’AguiProvider condiviso è visibile da qualsiasi punto dell’app — istanzia un componente CopilotKit con un agentId diverso per instradare ogni chat all’agent desiderato:

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

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

Personalizzare l’Aspetto

<CopilotChat /> (e <CopilotSidebar />, <CopilotPopup />) utilizzano un sistema di slot ricorsivo — puoi sovrascrivere qualsiasi sotto-componente con una stringa di classe Tailwind, un oggetto prop o un componente React personalizzato. Consulta la guida agli slot di CopilotKit per l’albero completo degli slot.

Temi Integrati

Il generatore legge metadata.ux dal tuo progetto sito web React e fornisce un modulo wrapper tematizzato in src/components/copilot/index.tsx in modo che i componenti chat corrispondano al resto della tua UI senza alcuna configurazione aggiuntiva:

ux	Stile applicato a CopilotChat / CopilotSidebar / CopilotPopup
cloudscape	I messaggi vengono renderizzati all’interno di ChatBubble Cloudscape con Avatar gen-AI (corrispondenti al pattern chat AI generativa Cloudscape); l’indicatore di digitazione diventa una LoadingBar e l’input è un PromptInput. Costruito da @cloudscape-design/components e @cloudscape-design/chat-components.
shadcn	I messaggi dell’assistente vengono renderizzati in una bolla bg-muted con un avatar Sparkles; i messaggi utente vengono renderizzati allineati a destra in una bolla bg-primary con un avatar User. L’input è una Textarea arrotondata + Button di invio/stop a forma di pillola (Invio invia, Shift+Invio nuova riga). Utilizza primitive shadcn dal package condiviso common-shadcn.
none (o qualsiasi altro)	Nessun tema — il modulo ri-esporta semplicemente i componenti CopilotKit predefiniti.

Importa i componenti tematizzati dal modulo tema locale (non direttamente da @copilotkit/react-core/v2) in modo che il tema venga applicato automaticamente:

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

<CopilotChat agentId="agent" />

Il tema viene applicato come valori predefiniti degli slot, quindi qualsiasi slot che passi esplicitamente ha comunque la precedenza — mantieni il pieno controllo ogni volta che hai bisogno di una sovrascrittura una tantum.

Personalizzare il Tema

Il tema generato risiede interamente all’interno del tuo progetto:

• src/components/copilot/index.tsx — esporta i CopilotChat / CopilotSidebar / CopilotPopup tematizzati e gli oggetti cloudscapeCopilotTheme / shadcnCopilotTheme. Modifica questo file per cambiare il collegamento predefinito degli slot per ogni chat nella tua app.
• src/components/copilot/<ThemeComponent>.tsx — componenti tema per slot (ad es. CloudscapeAssistantMessage, ShadcnChatInput). Modificali per regolare l’aspetto di un singolo slot senza ricablare il tema.

Ad esempio, per inserire il tuo renderer di messaggi utente personalizzato mantenendo il resto del tema, modifica il file pertinente in src/components/copilot/ e ri-esportalo da index.tsx.

Stile Tailwind tramite slot

Le sovrascritture per chat funzionano ancora insieme al tema — qualsiasi cosa passi come prop slot sovrascrive il valore predefinito del tema:

<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',
  }}
/>

Sostituire uno slot con un componente personalizzato

Qualsiasi slot può accettare un componente React invece di un className, quindi puoi sostituire completamente il valore predefinito:

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 }}
/>;

Le sovrascritture più profonde seguono la stessa forma — ad es. sostituisci solo il pulsante copia sui messaggi dell’assistente:

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

Sviluppo Locale

Il generatore di connessione configura automaticamente l’integrazione dev:

1. Eseguire nx dev <website> avvierà anche il server locale dell’agent
2. La configurazione runtime viene sovrascritta per puntare all’URL AG-UI locale (ad es. http://localhost:8081)
3. Sia il sito web che l’agent si ricaricano automaticamente insieme

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

Ricaricamento Automatico

Il sito web e l’agent connesso si ricaricano automaticamente insieme, consentendoti di iterare rapidamente su entrambi i lati senza distribuire su AWS.

Ulteriori Informazioni

• Guida Agent TypeScript
• Guida Agent Python
• Documentazione Protocollo AG-UI
• Documentazione CopilotKit + AWS Strands
• CopilotKit Custom Look & Feel
• Bedrock AgentCore Runtime