AWS AgentCore 세션 엔드포인트로 코딩 에이전트의 웹 앱 미리보기

코딩 에이전트가 웹 화면을 수정할 때 결과를 보려면 보통 실행 환경에 접속하거나 별도 배포를 거쳐야 한다. AWS가 10월 30일 공개한 AgentCore Runtime 실습은 다른 경로를 보여준다. 에이전트가 작업하는 세션 안에서 Vite 서버를 실행하고 개발자는 인증된 세션 엔드포인트를 거쳐 브라우저에서 변경 결과를 확인한다.

이 글은 AWS가 공개한 예제와 개발자 문서를 바탕으로 동작 방식과 적용 조건을 정리한 것이다. 예제에서 수정 사항이 자동 반영되는 흐름은 확인할 수 있지만 실제 개발 시간 단축이나 다른 환경 대비 성능은 별도로 측정된 결과가 아니다.

에이전트와 미리보기가 만나는 경로

AgentCore Runtime은 에이전트 세션을 격리된 microVM에서 실행한다. 세션 엔드포인트는 특정 세션에 연결되는 인증된 HTTPS 주소다. 허용한 포트로 HTTP 요청과 WebSocket 연결을 전달하므로 세션 안에 띄운 웹 서버에 접근할 수 있다. HTTP/2, 서버 전송 이벤트와 gRPC도 지원한다.

AWS 예제에서는 에이전트가 파일을 읽고 수정하는 동안 Vite 개발 서버가 8090번 포트에서 웹 페이지를 제공한다. 파일이 저장되면 Vite의 WebSocket이 변경 사항을 브라우저로 전달한다. 별도의 8081번 포트에서는 수정 내역을 확인하는 상태 경로도 제공한다. 에이전트 자체의 8080번 포트는 세션 엔드포인트에 허용하지 않고 일반 InvokeAgentRuntime 호출로 접근한다.

브라우저가 페이지의 모든 요청에 AWS 서명을 직접 붙이는 방식은 번거롭다. 예제는 bedrock-agentcore SDK의 로컬 엔드포인트를 사용한다. 브라우저는 로컬 주소에 접속하고 로컬 엔드포인트가 요청과 WebSocket 핸드셰이크에 자격 증명을 붙여 세션 엔드포인트로 전달한다.

포트와 인증을 먼저 정한다

런타임 생성 시 allowedPorts에 접근을 허용할 포트를 지정한다. AWS의 설명에 따르면 항목은 1~5개이며 각 항목은 8000~12000 범위의 단일 포트나 범위다. 플랫폼 예약 포트는 제외된다. 포트를 허용해도 서버가 자동으로 실행되지는 않는다. 애플리케이션은 해당 포트에서 0.0.0.0으로 수신해야 한다.

IAM 인증을 쓰는 런타임은 각 HTTP 요청과 WebSocket 핸드셰이크 등에 SigV4 서명이 필요하다. 호출자에게 런타임과 런타임 엔드포인트에 대한 bedrock-agentcore:InvokeAgentRuntimeProxy 권한도 있어야 한다. JWT 인바운드 인증을 구성한 경우에는 bearer 토큰을 사용한다. 주소를 아는 것만으로 접근할 수는 없다.

연결이 실패하면 응답을 구분해 살펴보자. AWS 예제에서 허용하지 않은 포트는 403, 허용한 포트에서 서버가 수신하지 않는 경우는 502, 종료된 세션은 404를 반환한다. 자격 증명이 없거나 유효하지 않으면 401 또는 403이 반환될 수 있다.

실서비스 주소로 쓰기 전에

세션 엔드포인트는 해당 세션이 살아 있는 동안에만 유효하다. AWS는 이를 개발과 테스트, 검토에 사용하고 사용자에게 제공할 앱은 별도 호스팅 서비스에 배포하도록 안내한다. 세션의 컴퓨팅이 교체되면 열린 연결이 끊기며 영구 스토리지를 사용하지 않은 수정 사항은 남지 않을 수 있다.

또 하나의 경계는 세션 내부다. AWS에 따르면 접근 제어가 웹사이트와 에이전트를 서로 분리하는 것은 아니다. 둘이 같은 세션에서 실행되므로 실행 역할에는 필요한 권한만 부여하고 에이전트가 바꾼 코드는 배포 전에 검토해야 한다. 로컬 엔드포인트 역시 개발자의 자격 증명으로 동작하므로 미리보기를 사용할 때만 실행하는 편이 좋다.

코딩 에이전트의 결과를 빠르게 검토해야 하는 팀이라면 이 구조를 실험해 볼 만하다. 다만 포트 허용 목록, 인증, 파일 보존과 배포 경로를 먼저 정해야 미리보기가 운영 환경의 보안 경계를 흐리지 않는다.