Site React para AgentCore Gateway

O gerador connection pode conectar um site React aos agentes expostos por um AgentCore Gateway gerado com protocol: http.

O navegador se comunica apenas com o Gateway — requisições para <gatewayUrl>/<targetName>/invocations são encaminhadas por proxy para o runtime do agente por trás dele. Como o site nunca precisa alcançar os runtimes diretamente, os agentes podem ser implantados dentro de uma VPC, com o Gateway como o único ponto de entrada governado fornecendo autenticação e observabilidade.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto de site React
2. Um projeto agentcore-gateway gerado com protocol: http
3. Pelo menos um agente AG-UI ou HTTP anexado ao Gateway através do gerador de conexão Gateway para agente

O gerador cria um cliente de site para cada agente AG-UI ou HTTP anexado ao Gateway (alvos A2A são ignorados — eles falam JSON-RPC de agente para agente, não um protocolo de navegador). Ele gera os mesmos clientes que conectar o site a cada agente diretamente (AG-UI/CopilotKit para agentes AG-UI, um cliente OpenAPI para agentes HTTP Python), roteados através do Gateway em vez de no runtime.

Autenticação

O navegador autentica com o Gateway, não com os agentes: SigV4 para um Gateway IAM (através do pool de identidade Cognito do site), ou um token bearer JWT para um Gateway Cognito.

Uso

Execute o Gerador

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Selecione o projeto do site como origem e o projeto do Gateway como destino.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

Para cada agente AG-UI exposto, os mesmos arquivos da conexão React para agente AG-UI são gerados (um AguiProvider, um hook useAgui<Agent> e um módulo de componente CopilotKit com tema), com o hook lendo a URL do Gateway da configuração de runtime:

• Directorypackages/<website>/src

  • Directorycomponents

    • AguiProvider.tsx Provedor CopilotKit registrando cada agente
    • Directorycopilot/ Componentes de chat com tema

      • …
  • Directoryhooks

    • useAgui<Agent>.tsx Conecta ao agente através da rota /<targetName>/invocations do Gateway

Para cada agente HTTP Python exposto, os mesmos arquivos da conexão React para agente Python são gerados (um cliente OpenAPI type-safe, hooks e um provedor), com a URL base do cliente roteada através do Gateway.

A URL do Gateway é registrada no namespace connection.gateways.<GatewayClassName> da Configuração de Runtime, então ela é publicada no runtime-config.json do site.

Concedendo acesso aos usuários do site

Para um Gateway IAM, conceda aos usuários autenticados do site permissão para invocá-lo (um Gateway Cognito não precisa de concessão — o navegador autentica com seu token bearer JWT em vez disso):

CDK

packages/infra/src/stacks/application-stack.ts

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

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

Terraform

packages/infra/src/main.tf

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
}

Desenvolvimento Local

O target dev do site ganha uma dependência no target dev do projeto Gateway, que inicia o gateway local mais todos os agentes anexados. A configuração de runtime do site é sobrescrita no modo local-dev para apontar a URL do Gateway para o gateway local, então o navegador exercita as mesmas rotas /<targetName>/invocations localmente:

pnpm

pnpm nx dev <website-name>

yarn

yarn nx dev <website-name>

npm

npx nx dev <website-name>

bun

bunx nx dev <website-name>

Conectando novos agentes

O gerador conecta o site aos agentes anexados ao Gateway no momento em que é executado. Após anexar outro agente ao Gateway, execute novamente o gerador de conexão para gerar seu cliente de site — clientes existentes permanecem intocados.