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

사용법

생성기 실행

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

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

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

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

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	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에 배포하지 않고도 두 가지를 함께 빠르게 반복할 수 있습니다.

추가 정보

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

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