React para TypeScript Agent

Nx Plugin for AWS fornece um gerador para integrar rapidamente seu TypeScript Agent com um site React. Ele configura toda a configuração necessária para conectar ao seu agente via tRPC sobre WebSocket, incluindo suporte para autenticação AWS IAM e Cognito. A integração fornece segurança de tipo completa de ponta a ponta entre seu frontend e o roteador tRPC do agente.

Pré-requisitos

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

1. Um site React (gerado usando o gerador ts#website)
2. Um TypeScript Agent (gerado usando o gerador ts#agent)
3. Cognito Auth adicionado via o gerador ts#website#auth

Uso

Execute o Gerador

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

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

Você será solicitado a selecionar seu site React como o projeto de origem e o projeto contendo seu Agent como o projeto de destino. Se o seu projeto de destino contiver múltiplos componentes (como múltiplos agentes ou outros tipos de componentes), você será solicitado a especificar um targetComponent para desambiguar.

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

O gerador cria a seguinte estrutura em sua aplicação React:

• Directorysrc

  • Directorycomponents

    • <AgentName>AgentClientProvider.tsx Sets up the tRPC WebSocket client and bindings to your agent’s tRPC router
    • QueryClientProvider.tsx TanStack React Query client provider
  • Directoryhooks

    • useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
    • use<AgentName>Agent.tsx Hooks returning the tRPC options proxy and vanilla tRPC client

Além disso, ele instala as dependências necessárias:

• @trpc/client
• @trpc/tanstack-react-query
• @tanstack/react-query
• aws4fetch (se estiver usando autenticação IAM)

Como Funciona

Conexão WebSocket

O cliente gerado se conecta ao seu Agent via tRPC sobre WebSocket. O agente expõe um roteador tRPC (incluindo a assinatura invoke para streaming de respostas do agente) sobre um endpoint WebSocket.

• Implantado: O ARN do runtime do agente é carregado da Configuração de Runtime. Executar este gerador de conexão também corrige o construto CDK/Terraform gerado do agente para publicar seu ARN no runtime-config.json do site (sob o namespace connection), então apenas os agentes que você conecta explicitamente são expostos ao frontend. O ARN é convertido para uma URL WebSocket seguindo o protocolo WebSocket do Bedrock AgentCore Runtime: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
• Desenvolvimento local: Ao executar com dev, a substituição de configuração de runtime define o valor para uma URL ws:// local (por exemplo, ws://localhost:8081/ws), e o cliente se conecta diretamente

Autenticação

O código gerado lida com a autenticação dependendo da configuração do seu agente:

• IAM (padrão): Usa URLs pré-assinadas AWS SigV4 para autenticar a conexão WebSocket. As credenciais são obtidas do Cognito Identity Pool configurado com a autenticação do seu site. No modo dev, a assinatura é automaticamente ignorada quando runtime-config.json não está presente
• Cognito: Incorpora o token de acesso JWT no cabeçalho Sec-WebSocket-Protocol como um token bearer codificado em base64url, seguindo o protocolo de autenticação WebSocket do AgentCore

Infraestrutura

Se o seu agent usa autenticação IAM, a função autenticada do Cognito Identity Pool deve receber permissão para invocar o 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 conecta todas as ações de invocação do AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) no ARN de runtime do 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 o seu agent usa autenticação Cognito, você não precisa definir nenhuma infraestrutura adicional para conectar seu website ao seu agent.

Usando o Código Gerado

Usando TanStack Query

O caso de uso mais comum é fazer streaming da resposta do agente usando a assinatura invoke com o hook use<AgentName>Agent, que retorna um proxy de opções tRPC para uso com TanStack Query:

import { useSubscription } from '@trpc/tanstack-react-query';
import { useMyAgentAgent } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const trpc = useMyAgentAgent();

  const subscription = useSubscription(
    trpc.invoke.subscriptionOptions(
      { prompt: 'What can you help me with?' },
      {
        enabled: true,
        onStarted: () => {
          console.log('Agent started responding');
        },
        onData: (token) => {
          console.log('Received token:', token);
        },
        onError: (error) => {
          console.error('Agent error:', error);
        },
      },
    ),
  );

  return (
    <div>
      <p>Status: {subscription.status}</p>
      {subscription.data && <p>Latest token: {subscription.data}</p>}
      {subscription.error && <p>Error: {subscription.error.message}</p>}
    </div>
  );
}

Proxy de Opções tRPC

Para mais detalhes sobre o proxy de opções tRPC e integração com TanStack Query, consulte a documentação tRPC TanStack React Query.

Usando o Cliente tRPC Vanilla

O hook use<AgentName>AgentClient fornece acesso ao cliente tRPC vanilla para mais controle sobre o ciclo de vida da assinatura:

import { useState } from 'react';
import { useMyAgentAgentClient } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const client = useMyAgentAgentClient();
  const [messages, setMessages] = useState<string[]>([]);

  const sendMessage = (prompt: string) => {
    const subscription = client.invoke.subscribe(
      { prompt },
      {
        onData: (token) => {
          setMessages((prev) => [...prev, token]);
        },
        onComplete: () => {
          console.log('Agent finished');
        },
        onError: (error) => {
          console.error('Error:', error);
        },
      },
    );

    // Clean up when done
    return () => subscription.unsubscribe();
  };

  return (
    <div>
      <button onClick={() => sendMessage('Hello!')}>Send</button>
      <div>
        {messages.map((msg, i) => (
          <span key={i}>{msg}</span>
        ))}
      </div>
    </div>
  );
}

Cliente tRPC Vanilla

Para mais detalhes sobre o cliente tRPC vanilla, consulte a documentação do Cliente Vanilla tRPC.

Desenvolvimento Local

O gerador de conexão configura automaticamente a integração dev para o seu site react:

1. Executar nx dev <website> também iniciará o servidor local do agente
2. A configuração de runtime é substituída para apontar para a URL WebSocket local (por exemplo, ws://localhost:8081/ws)
3. Como com APIs conectadas, a autenticação é ignorada no modo dev quando runtime-config.json não está presente

Hot Reloading

O site e o agente conectado farão hot-reload, permitindo que você itere rapidamente em ambos juntos sem implantar na AWS.

Segurança de Tipo

A integração fornece segurança de tipo completa de ponta a ponta. Seu IDE fornecerá autocompletar completo e verificação de tipo para todas as chamadas de procedimento do agente. Os tipos são automaticamente inferidos da definição do roteador tRPC do seu agente, garantindo que quaisquer alterações na API do seu agente sejam imediatamente refletidas no código do seu frontend.

Mais Informações

Para mais informações, consulte:

• Guia do TypeScript Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket