React에서 TypeScript Agent로

Nx Plugin for AWS는 TypeScript Agent를 React 웹사이트와 빠르게 통합할 수 있는 생성기를 제공합니다. WebSocket을 통한 tRPC를 사용하여 에이전트에 연결하는 데 필요한 모든 구성을 설정하며, AWS IAM 및 Cognito 인증 지원을 포함합니다. 이 통합은 프론트엔드와 에이전트의 tRPC 라우터 간에 완전한 엔드투엔드 타입 안전성을 제공합니다.

사전 요구 사항

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

React 웹사이트 (ts#website 생성기를 사용하여 생성)
TypeScript Agent (ts#agent 생성기를 사용하여 생성)
ts#website#auth 생성기를 통해 추가된 Cognito Auth

사용법

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

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

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

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

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

디렉터리src
- 디렉터리components
  - <AgentName>AgentClientProvider.tsx tRPC WebSocket 클라이언트와 에이전트의 tRPC 라우터에 대한 바인딩 설정
  - QueryClientProvider.tsx TanStack React Query 클라이언트 프로바이더
- 디렉터리hooks
  - useSigV4.tsx SigV4로 요청에 서명하기 위한 훅 (IAM 전용)
  - use<AgentName>Agent.tsx tRPC 옵션 프록시와 바닐라 tRPC 클라이언트를 반환하는 훅

또한 필요한 종속성을 설치합니다:

@trpc/client
@trpc/tanstack-react-query
@tanstack/react-query
aws4fetch (IAM 인증 사용 시)

작동 방식

WebSocket 연결

생성된 클라이언트는 WebSocket을 통한 tRPC를 사용하여 Agent에 연결합니다. 에이전트는 WebSocket 엔드포인트를 통해 tRPC 라우터(스트리밍 에이전트 응답을 위한 invoke 구독 포함)를 노출합니다.

배포됨: 에이전트 런타임 ARN은 런타임 구성에서 로드됩니다. 이 연결 생성기를 실행하면 에이전트의 생성된 CDK/Terraform 구성도 패치하여 웹사이트의 runtime-config.json(connection 네임스페이스 아래)에 ARN을 게시하므로 명시적으로 연결한 에이전트만 프론트엔드에 노출됩니다. ARN은 Bedrock AgentCore Runtime WebSocket 프로토콜에 따라 WebSocket URL로 변환됩니다: wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws
로컬 개발: dev로 실행할 때 런타임 구성 오버라이드는 값을 로컬 ws:// URL(예: ws://localhost:8081/ws)로 설정하고 클라이언트가 직접 연결합니다

인증

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

IAM (기본값): AWS SigV4 사전 서명된 URL을 사용하여 WebSocket 연결을 인증합니다. 자격 증명은 웹사이트의 인증과 함께 구성된 Cognito Identity Pool에서 가져옵니다. dev 모드에서는 runtime-config.json이 없을 때 서명이 자동으로 건너뛰어집니다
Cognito: AgentCore WebSocket 인증 프로토콜에 따라 JWT 액세스 토큰을 base64url로 인코딩된 베어러 토큰으로 Sec-WebSocket-Protocol 헤더에 포함합니다

인프라

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

CDK
Terraform

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)을 연결합니다.

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 인증을 사용하는 경우, 웹사이트를 에이전트에 연결하기 위해 추가 인프라를 정의할 필요가 없습니다.

생성된 코드 사용

TanStack Query 사용

가장 일반적인 사용 사례는 use<AgentName>Agent 훅과 함께 invoke 구독을 사용하여 에이전트의 응답을 스트리밍하는 것입니다. 이 훅은 TanStack Query와 함께 사용할 tRPC 옵션 프록시를 반환합니다:

import { useSubscription } from '@trpc/tanstack-react-query';
import { useMyAgentAgent } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const trpc = useMyAgentAgent();

  const subscription = useSubscription(
    trpc.invoke.subscriptionOptions(
      { prompt: 'What can you help me with?' },
      {
        enabled: true,
        onStarted: () => {
          console.log('Agent started responding');
        },
        onData: (token) => {
          console.log('Received token:', token);
        },
        onError: (error) => {
          console.error('Agent error:', error);
        },
      },
    ),
  );

  return (
    <div>
      <p>Status: {subscription.status}</p>
      {subscription.data && <p>Latest token: {subscription.data}</p>}
      {subscription.error && <p>Error: {subscription.error.message}</p>}
    </div>
  );
}

바닐라 tRPC 클라이언트 사용

use<AgentName>AgentClient 훅은 구독 수명 주기를 더 세밀하게 제어할 수 있는 바닐라 tRPC 클라이언트에 대한 액세스를 제공합니다:

import { useState } from 'react';
import { useMyAgentAgentClient } from './hooks/useMyAgentAgent';

function ChatComponent() {
  const client = useMyAgentAgentClient();
  const [messages, setMessages] = useState<string[]>([]);

  const sendMessage = (prompt: string) => {
    const subscription = client.invoke.subscribe(
      { prompt },
      {
        onData: (token) => {
          setMessages((prev) => [...prev, token]);
        },
        onComplete: () => {
          console.log('Agent finished');
        },
        onError: (error) => {
          console.error('Error:', error);
        },
      },
    );

    // Clean up when done
    return () => subscription.unsubscribe();
  };

  return (
    <div>
      <button onClick={() => sendMessage('Hello!')}>Send</button>
      <div>
        {messages.map((msg, i) => (
          <span key={i}>{msg}</span>
        ))}
      </div>
    </div>
  );
}

로컬 개발

연결 생성기는 React 웹사이트에 대한 dev 통합을 자동으로 구성합니다:

nx dev <website>를 실행하면 에이전트의 로컬 서버도 시작됩니다
런타임 구성이 로컬 WebSocket URL(예: ws://localhost:8081/ws)을 가리키도록 오버라이드됩니다
연결된 API와 마찬가지로 runtime-config.json이 없을 때 dev 모드에서는 인증이 건너뛰어집니다

타입 안전성

이 통합은 완전한 엔드투엔드 타입 안전성을 제공합니다. IDE는 모든 에이전트 프로시저 호출에 대해 완전한 자동 완성 및 타입 검사를 제공합니다. 타입은 에이전트의 tRPC 라우터 정의에서 자동으로 추론되므로 에이전트의 API에 대한 모든 변경 사항이 프론트엔드 코드에 즉시 반영됩니다.

추가 정보

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