Sitio Web React a AgentCore Gateway

El generador connection puede conectar un sitio web React a los agentes expuestos por un AgentCore Gateway generado con protocol: http.

El navegador solo se comunica con el Gateway — las solicitudes a <gatewayUrl>/<targetName>/invocations se envían por proxy al runtime del agente detrás de él. Debido a que el sitio web nunca necesita alcanzar los runtimes directamente, los agentes pueden desplegarse dentro de una VPC, con el Gateway como el único punto de entrada gobernado que proporciona autenticación y observabilidad.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

Un proyecto de sitio web React
Un proyecto agentcore-gateway generado con protocol: http
Al menos un agente AG-UI o HTTP adjunto al Gateway a través del generador de conexión Gateway a agente

El generador crea un cliente de sitio web para cada agente AG-UI o HTTP adjunto al Gateway (los destinos A2A se omiten — hablan JSON-RPC de agente a agente, no un protocolo de navegador). Genera los mismos clientes que al conectar el sitio web a cada agente directamente (AG-UI/CopilotKit para agentes AG-UI, un cliente OpenAPI para agentes HTTP de Python), enrutados a través del Gateway en lugar de al runtime.

Uso

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Selecciona el proyecto del sitio web como origen y el proyecto del Gateway como destino.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

Para cada agente AG-UI expuesto, se generan los mismos archivos que la conexión de React a agente AG-UI (un AguiProvider, un hook useAgui<Agent> y un módulo de componente CopilotKit con tema), con el hook leyendo la URL del Gateway desde la configuración de runtime:

Directoriopackages/<website>/src
- Directoriocomponents
  - AguiProvider.tsx Proveedor de CopilotKit que registra cada agente
  - Directoriocopilot/ Componentes de chat con tema
    …
- Directoriohooks
  - useAgui<Agent>.tsx Se conecta al agente a través de la ruta /<targetName>/invocations del Gateway

Para cada agente HTTP de Python expuesto, se generan los mismos archivos que la conexión de React a agente Python (un cliente OpenAPI con tipos seguros, hooks y un proveedor), con la URL base del cliente enrutada a través del Gateway.

La URL del Gateway se registra en el espacio de nombres connection.gateways.<GatewayClassName> de Runtime Configuration, por lo que se publica en el runtime-config.json del sitio web.

Otorgar acceso a los usuarios del sitio web

Para un Gateway IAM, otorga a los usuarios autenticados del sitio web permiso para invocarlo (un Gateway Cognito no necesita otorgamiento — el navegador se autentica con su token bearer JWT en su lugar):

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
}

Desarrollo local

El target dev del sitio web gana una dependencia en el target dev del proyecto Gateway, que inicia el gateway local más cada agente adjunto. La configuración de runtime del sitio web se sobrescribe en modo local-dev para apuntar la URL del Gateway al gateway local, por lo que el navegador ejercita las mismas rutas /<targetName>/invocations localmente:

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

Conectar nuevos agentes

El generador conecta el sitio web a los agentes adjuntos al Gateway en el momento en que se ejecuta. Después de adjuntar otro agente al Gateway, vuelve a ejecutar el generador de conexión para generar su cliente de sitio web — los clientes existentes se dejan intactos.