React에서 Python Agent로

Nx Plugin for AWS는 Python Agent를 React 웹사이트와 빠르게 통합할 수 있는 생성기를 제공합니다. AWS IAM 및 Cognito 인증 지원을 포함하여 타입 안전한 OpenAPI 생성 클라이언트를 통해 에이전트에 연결하는 데 필요한 모든 구성을 설정합니다.

AG-UI 에이전트

Python Agent가 protocol=ag-ui로 생성된 경우, 연결 생성기는 대신 CopilotKit과 React 웹사이트의 @ag-ui/client HttpAgent를 연결합니다. 자세한 내용은 React에서 AG-UI Agent로 가이드를 참조하세요.

전제 조건

이 생성기를 사용하기 전에 다음이 필요합니다:

1. React 웹사이트 (ts#website 생성기를 사용하여 생성)
2. protocol=http인 Python Agent (py#agent 생성기를 사용하여 생성)
3. ts#website#auth 생성기를 통해 추가된 Cognito Auth

사용법

생성기 실행

이 제너레이터 실행@aws/nx-plugin:connection

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

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - connection
5. 필수 매개변수 입력
6. 클릭 Generate

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-run어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

소스 프로젝트로 React 웹사이트를, 타겟 프로젝트로 Python Agent가 포함된 프로젝트를 선택하라는 메시지가 표시됩니다. 타겟 프로젝트에 여러 컴포넌트(예: 여러 에이전트 또는 다른 컴포넌트 유형)가 포함된 경우 명확히 하기 위해 targetComponent를 지정하라는 메시지가 표시됩니다.

targetComponent는 에이전트 생성기에 제공한 --name을 모든 케이싱으로(ResearchAgent, research-agent), 타겟 프로젝트 루트에 상대적인 컴포넌트의 경로, 또는 생성기 ID로 받습니다.

옵션

제너레이터 옵션5 옵션

sourceProject필수string

소스 프로젝트

targetProject필수string

연결할 대상 프로젝트

sourceComponentstring

연결할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.

targetComponentstring

연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.

preferInstallDependenciesboolean기본값: true

생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

생성기는 Python Agent 프로젝트에 다음을 생성합니다:

• 디렉터리scripts

  • <agent_name>_openapi.py 에이전트의 FastAPI 앱에서 OpenAPI 사양을 생성하는 스크립트
• project.json 새로운 <agent-name>-openapi 타겟이 추가됨

생성기는 React 애플리케이션에 다음 구조를 생성합니다:

• 디렉터리src

  • 디렉터리components

    • <AgentName>Provider.tsx OpenAPI 클라이언트용 Provider
    • QueryClientProvider.tsx TanStack React Query 클라이언트 provider
  • 디렉터리hooks

    • useSigV4.tsx SigV4로 요청에 서명하기 위한 Hook (IAM만 해당)
    • use<AgentName>.tsx 에이전트 API용 TanStack Query 옵션 프록시를 반환하는 Hook
    • use<AgentName>Client.tsx 바닐라 API 클라이언트를 반환하는 Hook
  • 디렉터리generated

    • 디렉터리<agent-name>

      • types.gen.ts 에이전트의 Pydantic 모델에서 생성된 타입
      • client.gen.ts 에이전트 API 호출을 위한 타입 안전 클라이언트
      • options-proxy.gen.ts 에이전트와 상호작용하기 위한 TanStack Query 훅 옵션
• project.json 클라이언트 생성 및 변경 사항 감시를 위한 타겟이 추가됨
• .gitignore 생성된 클라이언트 파일은 기본적으로 무시됨

작동 방식

OpenAPI 클라이언트 생성

빌드 시 Python Agent의 FastAPI 앱을 검사하여 OpenAPI 사양을 생성합니다. 이 사양은 React에서 FastAPI로 연결과 동일한 패턴을 따라 TanStack Query 훅과 함께 타입 안전한 TypeScript 클라이언트를 생성하는 데 사용됩니다.

각 에이전트는 자체 범위의 OpenAPI 스크립트(예: scripts/agent_openapi.py)를 가지므로 여러 에이전트가 있는 프로젝트에서 개별 사양을 생성할 수 있습니다.

런타임 구성

이 연결 생성기를 실행하면 에이전트의 생성된 CDK/Terraform 구성도 패치하여 AgentCore 런타임 ARN을 웹사이트의 runtime-config.json(connection 네임스페이스 아래)에 게시하므로 명시적으로 연결한 에이전트만 프론트엔드에 노출됩니다. 자세한 내용은 런타임 구성을 참조하세요.

인증

생성된 코드는 에이전트의 구성에 따라 인증을 처리합니다:

• IAM (기본값): AWS SigV4를 사용하여 HTTP 요청에 서명합니다. 자격 증명은 웹사이트의 인증과 함께 구성된 Cognito Identity Pool에서 가져옵니다
• Cognito: Authorization 헤더에 JWT 액세스 토큰을 포함합니다
• None: 인증 없음

인프라

에이전트가 IAM 인증을 사용하는 경우, Cognito Identity Pool의 인증된 역할에 에이전트를 호출할 수 있는 권한이 부여되어야 합니다.

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는 에이전트의 런타임 ARN에 대한 모든 AgentCore 호출 작업(InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream)을 연결합니다.

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
}

에이전트가 Cognito 인증을 사용하는 경우, 웹사이트를 에이전트에 연결하기 위해 추가 인프라를 정의할 필요가 없습니다.

생성된 코드 사용

API Hook 사용

use<AgentName> 훅은 에이전트의 API 엔드포인트를 호출하기 위한 TanStack Query 옵션을 제공합니다:

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>
  );
}

바닐라 클라이언트 사용

use<AgentName>Client 훅은 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>
  );
}

로컬 개발

연결 생성기는 자동으로 dev 통합을 구성합니다:

1. nx dev <website>를 실행하면 에이전트의 로컬 FastAPI 서버도 시작됩니다
2. 런타임 구성이 로컬 HTTP URL(예: http://localhost:8081/)을 가리키도록 재정의됩니다
3. 에이전트의 API가 변경되면 TypeScript 클라이언트가 자동으로 재생성됩니다

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

핫 리로딩

웹사이트와 연결된 에이전트가 핫 리로드되므로 AWS에 배포하지 않고도 두 가지를 함께 빠르게 반복할 수 있습니다.

dev 타겟은 Nx Daemon이 필요합니다

dev 타겟은 로컬 개발 서버를 핫 리로드합니다. 이들 중 다수는 이를 달성하기 위해 nx watch에 의존하며, 이는 Nx Daemon이 활성화되어 있어야 합니다.

추가 정보

자세한 내용은 다음을 참조하세요:

• Python Agent 가이드
• React에서 FastAPI로 연결 가이드
• TanStack Query Documentation