React에서 Python Strands Agent로 연결

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

사전 요구사항

이 생성기를 사용하기 전에 다음을 준비해야 합니다:

React 웹사이트 (ts#react-website 생성기를 사용하여 생성)
Python Strands Agent (py#strands-agent 생성기를 사용하여 생성)
ts#react-website-auth 생성기를 통해 추가된 Cognito Auth

사용법

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

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

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

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.

생성기 출력

생성기는 Python Strands 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 hooks 옵션
project.json 클라이언트 생성 및 변경 감시를 위한 타겟이 추가됨
.gitignore 생성된 클라이언트 파일은 기본적으로 무시됨

작동 원리

OpenAPI 클라이언트 생성

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

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

인증

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

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

생성된 코드 사용하기

API Hook 사용

use<AgentName> hook은 에이전트의 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 = (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>
  );
}

바닐라 클라이언트 사용

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

로컬 개발

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

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

pnpm nx serve-local <WebsiteProject>

yarn nx serve-local <WebsiteProject>

npx nx serve-local <WebsiteProject>

bunx nx serve-local <WebsiteProject>

인프라

에이전트가 IAM 인증을 사용하는 경우 Cognito Identity Pool의 인증된 역할에 에이전트를 호출할 수 있는 권한이 부여되어야 합니다. 적절한 grantInvokeAccess 메서드는 에이전트의 인프라 구성을 참조하세요.

추가 정보

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