React para TypeScript Strands Agent

O Nx Plugin for AWS fornece um gerador para integrar rapidamente seu TypeScript Strands Agent com um site React. Ele configura toda a configuração necessária para conectar ao seu agente via tRPC sobre WebSocket, incluindo suporte de 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#react-website)
2. Um TypeScript Strands Agent (gerado usando o gerador ts#strands-agent)
3. Cognito Auth adicionado via o gerador ts#react-website-auth

Uso

Executar 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

Você será solicitado a selecionar seu site React como o projeto de origem e o projeto contendo seu Strands Agent como o projeto de destino. Se seu projeto de destino contém 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.

Saída do Gerador

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

• Directorysrc

  • Directorycomponents

    • <AgentName>AgentClientProvider.tsx Configura o cliente tRPC WebSocket e vinculações ao roteador tRPC do seu agente
    • QueryClientProvider.tsx Provedor do cliente TanStack React Query
  • Directoryhooks

    • useSigV4.tsx Hook para assinar requisições com SigV4 (apenas IAM)
    • use<AgentName>Agent.tsx Hooks retornando o proxy de opções tRPC e cliente tRPC vanilla

Adicionalmente, 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 Strands Agent via tRPC sobre WebSocket. O agente expõe um roteador tRPC (incluindo a assinatura invoke para transmitir respostas do agente em streaming) sobre um endpoint WebSocket.

• Implantado: O ARN do runtime do agente é carregado da Configuração de Runtime. 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 serve-local, a substituição da 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 serve-local, 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 seu agente usa autenticação IAM, a função autenticada do Cognito Identity Pool deve ter a permissão bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream para invocar agentes via WebSocket:

const identity = new UserIdentity(this, 'Identity');
const myAgent = new MyAgent(this, 'MyAgent');

identity.identityPool.authenticatedRole.addToPrincipalPolicy(
  new PolicyStatement({
    actions: ['bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream'],
    resources: [myAgent.agentCoreRuntime.agentRuntimeArn],
  }),
);

Protocolo WebSocket

No momento da escrita, o método grantInvoke do agent core runtime ainda não inclui esta permissão automaticamente (veja aws-cdk#37495).

Se seu agente usa autenticação Cognito, você não precisa definir nenhuma infraestrutura adicional para conectar seu site ao seu agente.

Usando o Código Gerado

Usando TanStack Query

O caso de uso mais comum é transmitir a resposta do agente em streaming 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(
      { message: '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 = (message: string) => {
    const subscription = client.invoke.subscribe(
      { message },
      {
        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 serve-local para seu site react:

1. Executar nx serve-local <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 serve-local quando runtime-config.json não está presente

Recarregamento a quente

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 mudanças 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 Strands Agent
• tRPC WebSocket Client
• tRPC TanStack React Query Integration
• Bedrock AgentCore Runtime WebSocket