React para Python Agent

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

Agentes AG-UI

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

Pré-requisitos

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

1. Um site React (gerado usando o gerador ts#website)
2. Um Python Agent com protocol=http (gerado usando o gerador py#agent)
3. Cognito Auth adicionado através do 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 Python 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 o seguinte no seu projeto Python Agent:

• Directoryscripts

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

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

• Directorysrc

  • Directorycomponents

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

    • useSigV4.tsx Hook para assinar requisições com SigV4 (apenas IAM)
    • use<AgentName>.tsx Hook que retorna o proxy de opções TanStack Query para a API do seu agente
    • use<AgentName>Client.tsx Hook que retorna 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 tipos para chamar a API do seu agente
      • options-proxy.gen.ts Opções de hooks TanStack Query para interagir com seu agente
• project.json Targets 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 Agent é inspecionado para gerar uma especificação OpenAPI. Esta especificação é então usada para gerar um cliente TypeScript com segurança de tipos com hooks TanStack Query, seguindo o mesmo padrão da conexão React para FastAPI.

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

Configuração em Tempo de Execução

Executar este gerador de conexão também corrige o construto CDK/Terraform gerado do agente para publicar seu ARN de tempo de execução AgentCore no runtime-config.json do site (sob o namespace connection), então apenas os agentes que você conecta explicitamente são expostos ao frontend. Consulte Configuração em Tempo de Execução para detalhes.

Autenticação

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

• IAM (padrão): Usa AWS SigV4 para assinar requisiçõ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 Authorization
• None: Sem autenticação

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 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 = (prompt: string) => {
    invoke.mutate({ prompt });
  };

  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 (prompt: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({ prompt })) {
      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 dev:

1. Executar nx dev <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 dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <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 Agent
• Guia de Conexão React para FastAPI
• Documentação do TanStack Query