React 웹사이트를 AgentCore Gateway에 연결

connection 생성기는 React 웹사이트를 protocol: http로 생성된 AgentCore Gateway가 제공하는 에이전트에 연결할 수 있습니다.

브라우저는 Gateway와만 통신합니다 — <gatewayUrl>/<targetName>/invocations에 대한 요청은 그 뒤에 있는 에이전트 런타임으로 프록시됩니다. 웹사이트가 런타임에 직접 접근할 필요가 없기 때문에, 에이전트는 VPC 내부에 배포될 수 있으며, Gateway가 인증 및 관찰성을 제공하는 단일 관리 진입점 역할을 합니다.

사전 요구 사항

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

React 웹사이트 프로젝트
protocol: http로 생성된 agentcore-gateway 프로젝트
Gateway와 에이전트 연결 생성기를 통해 Gateway에 연결된 하나 이상의 AG-UI 또는 HTTP 에이전트

생성기는 Gateway에 연결된 각 AG-UI 또는 HTTP 에이전트에 대한 웹사이트 클라이언트를 생성합니다(A2A 대상은 건너뜁니다 — 이들은 브라우저 프로토콜이 아닌 에이전트 간 JSON-RPC를 사용합니다). 웹사이트를 각 에이전트에 직접 연결하는 것과 동일한 클라이언트를 생성하지만(AG-UI/CopilotKit는 AG-UI 에이전트용, OpenAPI 클라이언트는 Python HTTP 에이전트용), 런타임이 아닌 Gateway를 통해 라우팅됩니다.

사용법

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

웹사이트 프로젝트를 소스로, Gateway 프로젝트를 대상으로 선택합니다.

옵션

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

생성기 출력

각 프론트엔드 AG-UI 에이전트에 대해 React와 AG-UI 에이전트 연결과 동일한 파일이 생성되며(AguiProvider, useAgui<Agent> 훅 및 테마가 적용된 CopilotKit 컴포넌트 모듈), 훅은 런타임 구성에서 Gateway의 URL을 읽습니다:

디렉터리packages/<website>/src
- 디렉터리components
  - AguiProvider.tsx 각 에이전트를 등록하는 CopilotKit 프로바이더
  - 디렉터리copilot/ 테마가 적용된 채팅 컴포넌트
    …
- 디렉터리hooks
  - useAgui<Agent>.tsx Gateway의 /<targetName>/invocations 경로를 통해 에이전트에 연결

각 프론트엔드 Python HTTP 에이전트에 대해 React와 Python 에이전트 연결과 동일한 파일이 생성되며(타입 안전 OpenAPI 클라이언트, 훅 및 프로바이더), 클라이언트의 기본 URL은 Gateway를 통해 라우팅됩니다.

Gateway의 URL은 런타임 구성의 connection.gateways.<GatewayClassName> 네임스페이스에 등록되므로 웹사이트의 runtime-config.json에 게시됩니다.

웹사이트 사용자에게 액세스 권한 부여

IAM Gateway의 경우, 웹사이트의 인증된 사용자에게 호출 권한을 부여합니다(Cognito Gateway는 권한 부여가 필요 없습니다 — 브라우저가 JWT bearer 토큰으로 인증하기 때문입니다):

CDK
Terraform

const identity = new UserIdentity(this, 'UserIdentity');
new Website(this, 'Website');

const myGateway = new MyGateway(this, 'MyGateway');
myGateway.addAgent(myAgent);
myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);

resource "aws_iam_policy" "gateway_invoke_policy" {
  name = "GatewayInvokePolicy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["bedrock-agentcore:InvokeGateway"]
        Resource = [module.my_gateway.gateway_arn]
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
}

로컬 개발

웹사이트의 dev 대상은 Gateway 프로젝트의 dev 대상에 대한 종속성을 갖게 되며, 이는 로컬 게이트웨이와 연결된 모든 에이전트를 시작합니다. 웹사이트의 런타임 구성은 local-dev 모드에서 Gateway의 URL이 로컬 게이트웨이를 가리키도록 재정의되므로, 브라우저는 로컬에서 동일한 /<targetName>/invocations 경로를 실행합니다:

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

새 에이전트 연결

생성기는 실행 시점에 Gateway에 연결된 에이전트에 웹사이트를 연결합니다. Gateway에 다른 에이전트를 연결한 후, 연결 생성기를 다시 실행하여 해당 웹사이트 클라이언트를 생성하세요 — 기존 클라이언트는 그대로 유지됩니다.