Sito Web React ad AgentCore Gateway

Il generatore connection può connettere un sito web React agli agenti esposti da un AgentCore Gateway generato con protocol: http.

Il browser comunica solo con il Gateway — le richieste a <gatewayUrl>/<targetName>/invocations vengono inoltrate al runtime dell’agente dietro di esso. Poiché il sito web non ha mai bisogno di raggiungere direttamente i runtime, gli agenti possono essere distribuiti all’interno di un VPC, con il Gateway come unico punto di ingresso governato che fornisce autenticazione e osservabilità.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

Un progetto sito web React
Un progetto agentcore-gateway generato con protocol: http
Almeno un agente AG-UI o HTTP collegato al Gateway tramite il generatore di connessione Gateway ad agente

Il generatore crea un client del sito web per ogni agente AG-UI o HTTP collegato al Gateway (i target A2A vengono saltati — parlano JSON-RPC agente-ad-agente, non un protocollo browser). Genera gli stessi client della connessione diretta del sito web a ciascun agente (AG-UI/CopilotKit per gli agenti AG-UI, un client OpenAPI per gli agenti Python HTTP), instradati attraverso il Gateway anziché al runtime.

Utilizzo

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il progetto del sito web come sorgente e il progetto Gateway come destinazione.

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

Per ogni agente AG-UI esposto, vengono generati gli stessi file della connessione React ad agente AG-UI (un AguiProvider, un hook useAgui<Agent> e un modulo di componenti CopilotKit tematizzato), con l’hook che legge l’URL del Gateway dalla configurazione di runtime:

Directorypackages/<website>/src
- Directorycomponents
  - AguiProvider.tsx Provider CopilotKit che registra ogni agente
  - Directorycopilot/ Componenti chat tematizzati
    …
- Directoryhooks
  - useAgui<Agent>.tsx Si connette all’agente tramite la route /<targetName>/invocations del Gateway

Per ogni agente Python HTTP esposto, vengono generati gli stessi file della connessione React ad agente Python (un client OpenAPI type-safe, hook e un provider), con l’URL base del client instradato attraverso il Gateway.

L’URL del Gateway è registrato nello spazio dei nomi connection.gateways.<GatewayClassName> della Configurazione di Runtime, quindi viene pubblicato nel runtime-config.json del sito web.

Concedere l’accesso agli utenti del sito web

Per un Gateway IAM, concedi agli utenti autenticati del sito web il permesso di invocarlo (un Gateway Cognito non necessita di concessione — il browser si autentica invece con il suo token bearer JWT):

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
}

Sviluppo Locale

Il target dev del sito web acquisisce una dipendenza dal target dev del progetto Gateway, che avvia il gateway locale più ogni agente collegato. La configurazione di runtime del sito web viene sovrascritta in modalità local-dev per puntare l’URL del Gateway al gateway locale, in modo che il browser eserciti le stesse route /<targetName>/invocations localmente:

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

Connettere nuovi agenti

Il generatore connette il sito web agli agenti collegati al Gateway al momento dell’esecuzione. Dopo aver collegato un altro agente al Gateway, riesegui il generatore di connessione per generare il suo client del sito web — i client esistenti rimangono intatti.