React para Agente Python Strands

O Nx Plugin for AWS fornece um gerador para integrar rapidamente seu Python Strands Agent com um site React. Ele configura toda a configuração necessária para conectar ao seu agente por meio de um cliente gerado pelo OpenAPI com segurança de tipo, incluindo suporte para autenticação AWS IAM e Cognito.

Agentes AG-UI

Se o seu Python Strands Agent foi gerado com protocol=AG-UI, o gerador de conexão configura o CopilotKit e um HttpAgent @ag-ui/client no site React. Consulte o guia React to AG-UI Agent para obter detalhes.

Pré-requisitos

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

1. Um site React (gerado usando o gerador ts#react-website)
2. Um Python Strands Agent com protocol=HTTP (gerado usando o gerador py#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 Python Strands Agent como o projeto de destino. Se o seu projeto de destino contiver vários componentes (como vários 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 o seguinte no seu projeto Python Strands Agent:

• Directoryscripts

  • <agent_name>_openapi.py Script para gerar uma especificação OpenAPI a partir do aplicativo FastAPI do agente
• project.json Um novo destino <agent-name>-openapi é adicionado

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

• Directorysrc

  • Directorycomponents

    • <AgentName>Provider.tsx Provedor para o cliente OpenAPI
    • QueryClientProvider.tsx Provedor de cliente TanStack React Query
  • Directoryhooks

    • useSigV4.tsx Hook para assinar solicitações com SigV4 (somente IAM)
    • use<AgentName>.tsx Hook retornando o proxy de opções TanStack Query para a API do seu agente
    • use<AgentName>Client.tsx Hook retornando o cliente de API vanilla
  • Directorygenerated

    • Directory<agent-name>

      • types.gen.ts Tipos gerados a partir dos modelos Pydantic do agente
      • client.gen.ts Cliente com segurança de tipo para chamar a API do seu agente
      • options-proxy.gen.ts Opções de hooks TanStack Query para interagir com seu agente
• project.json Destinos adicionados para geração de cliente e observação de mudanças
• .gitignore Os arquivos de cliente gerados são ignorados por padrão

Como Funciona

Geração de Cliente OpenAPI

No momento da compilação, o aplicativo FastAPI do Python Strands Agent é introspeccionado para gerar uma especificação OpenAPI. Esta especificação é então usada para gerar um cliente TypeScript com segurança de tipo com hooks TanStack Query, seguindo o mesmo padrão da conexão React to FastAPI.

Cada agente obtém seu próprio script OpenAPI com escopo definido (por exemplo, scripts/agent_openapi.py) para que projetos com vários agentes possam gerar especificações individuais.

Configuração de Tempo de Execução

A execução deste gerador de conexão também corrige a construção CDK/Terraform gerada do agente para publicar seu ARN de tempo de execução AgentCore no runtime-config.json do site (sob o namespace connection), de modo que apenas os agentes que você conecta explicitamente sejam expostos ao frontend. Consulte Configuração de Tempo de Execução para obter detalhes.

Autenticação

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

• IAM (padrão): Usa AWS SigV4 para assinar solicitações HTTP. As credenciais são obtidas do Cognito Identity Pool configurado com a autenticação do seu site
• Cognito: Incorpora o token de acesso JWT em um cabeçalho de Autorização
• None: Sem autenticação

Infraestrutura

Se o seu agente usa autenticação IAM, a função autenticada do Cognito Identity Pool deve receber permissão para invocar o agente.

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 agente.

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"
}

# 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 agente usa autenticação Cognito, você não precisa definir nenhuma infraestrutura adicional para conectar seu website ao seu agente.

Usando o Código Gerado

Usando o Hook da API

O hook use<AgentName> fornece opções TanStack Query para chamar os endpoints da API do seu agente:

import { useState } from 'react';
import { useMutation } from '@tanstack/react-query';
import { useMyAgent } from '../hooks/useMyAgent';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const api = useMyAgent();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const invoke = useMutation(api.invoke.mutationOptions({
    onSuccess: async (stream) => {
      setChunks([]);
      for await (const chunk of stream) {
        setChunks((prev) => [...prev, chunk]);
      }
    },
  }));

  const handleSend = (message: string) => {
    invoke.mutate({
      prompt: message,
      sessionId: 'my-session',
    });
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {invoke.isPending && <p>Agent is thinking...</p>}
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

Usando o Cliente Vanilla

O hook use<AgentName>Client fornece acesso direto ao cliente da API:

import { useState } from 'react';
import { useMyAgentClient } from '../hooks/useMyAgentClient';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const client = useMyAgentClient();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const handleSend = async (message: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({
      prompt: message,
      sessionId: 'my-session',
    })) {
      setChunks((prev) => [...prev, chunk]);
    }
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

Desenvolvimento Local

O gerador de conexão configura automaticamente a integração serve-local:

1. Executar nx serve-local <website> também iniciará o servidor FastAPI local do agente
2. A configuração de tempo de execução é substituída para apontar para a URL HTTP local (por exemplo, http://localhost:8081/)
3. O cliente TypeScript é regenerado automaticamente quando a API do agente muda

pnpm

pnpm nx serve-local <WebsiteProject>

yarn

yarn nx serve-local <WebsiteProject>

npm

npx nx serve-local <WebsiteProject>

bun

bunx nx serve-local <WebsiteProject>

Hot Reloading

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

Mais Informações

Para mais informações, consulte:

• Guia do Python Strands Agent
• Guia de Conexão React to FastAPI
• TanStack Query Documentation