Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore runtime의 Session endpoints를 이용하면 격리된 에이전트 세션에서 실행되는 웹 앱에 인증된 브라우저 접근을 제공하고, Vite의 변경 사항을 재배포나 새로고침 없이 미리 볼 수 있다.

📌 핵심 요약

• AgentCore runtime은 에이전트 세션마다 격리된 microVM을 제공하며, Session endpoints는 허용된 포트에서 실행되는 앱으로 HTTP 요청과 WebSocket 연결을 전달한다. 세션 안에서 앱 실행과 파일 편집을 함께 유지하면 변경마다 별도로 배포하는 데 따른 검토 지연을 줄일 수 있다.
• allowedPorts는 CreateAgentRuntime 호출 시 1~5개 항목으로 설정하며, 각 항목은 예약된 플랫폼 포트를 제외한 8000~12000 범위의 단일 포트 또는 포트 범위다. 앱은 0.0.0.0에 바인딩해 직접 실행해야 하고, 각 요청에는 IAM 기반 SigV4 서명 또는 인바운드 JWT authorizer용 bearer token이 필요하다.
• 샘플은 에이전트를 8080, Vite 웹사이트를 8090, 상태 조회 경로를 8081에서 실행한다. PreviewApp은 localhost:8087에서 채팅과 웹사이트를 함께 보여 주고, localhost:8088의 로컬 엔드포인트는 웹사이트 요청과 WebSocket handshake에 자격 증명을 추가한다. 에이전트는 Amazon Bedrock의 Claude Haiku 5.5를 호출하며, Vite가 저장된 파일의 변경을 WebSocket으로 전달해 화면을 갱신한다.
• 실습에는 지원 AWS 리전과 권한, Python 3.10 이상, bedrock-agentcore 1.25.2 이상, boto3 1.43.122 이상, Git, Jupyter 환경, Claude Haiku 5.5 접근 권한, Node.js 22 이상과 npm이 필요하다. 에이전트와 웹사이트는 Amazon S3의 zip 파일을 통한 Node.js 직접 코드 배포로 설치되므로 Docker나 Amazon ECR 저장소는 필요하지 않다.
• Session endpoints는 microVM runtime에서 지원되고 Instances 컴퓨팅 유형에서는 지원되지 않으며, 공개 HTTPS로 접근하고 인바운드 AWS PrivateLink는 지원하지 않는다. URL은 세션이 끝나면 작동을 멈추므로 빌드·테스트·검토에 사용하며, 사용자에게 앱을 제공할 때는 AWS Amplify Hosting 같은 호스팅 서비스에 배포한다. 제공된 본문은 변경 요청 절의 중간에서 끊겨 이후 실습 결과는 확인할 수 없다.

🧩 주요 포인트

1. 세션 안의 파일 편집과 Vite 실행을 연결하고 HTTP·WebSocket을 전달함 → 별도 배포를 기다리지 않고 에이전트의 작업 과정과 웹사이트 변화를 함께 검토할 수 있다.
2. Session endpoints는 요청별 인증과 allowedPorts로 접근을 제한하고 runtime endpoint는 에이전트 호출 버전을 선택함 → 미리보기 접근과 에이전트 호출의 역할이 분리되며, 샘플의 8080은 allowedPorts에 포함하지 않는다.
3. 세션 수명, 지원 리전·microVM, 공개 HTTPS 및 인바운드 AWS PrivateLink 미지원이라는 제약이 있음 → 실습 환경의 적합성을 먼저 확인하고, 지속적인 사용자 제공은 AWS Amplify Hosting 같은 별도 호스팅으로 이어져야 한다.

🧠 상세 정리

1. 웹 앱 검토를 늦추는 배포 대기

원문은 코딩 에이전트가 대시보드, 제품 페이지, 제품팀이 사용해 볼 프로토타입처럼 실제로 작동하는 웹 앱을 만드는 상황에서 출발한다. 이러한 작업을 빠르게 검토하려면 앱을 직접 열어 사용하고, 변경을 요청한 뒤 결과를 확인하는 반복 과정이 필요하다고 설명한다. 에이전트가 파일을 수정하는 환경에서 앱도 계속 실행되면 변경 사항이 수초 안에 브라우저에 나타날 수 있지만, 앱을 다른 곳으로 복사해 배포해야 한다면 검토 속도도 매번 배포를 기다리는 속도로 제한된다. Amazon Bedrock AgentCore는 에이전트 프레임워크와 기반 모델을 선택해 에이전트를 구축·연결·최적화하는 플랫폼으로 소개되며, runtime은 각 세션을 격리된 microVM에서 실행한다. 이 글은 Session endpoints를 통해 그 세션 안의 웹 앱을 브라우저에서 열고, 채팅으로 변경을 요청하면서 결과를 확인하는 구성을 제시한다.

2. Session endpoints의 포트와 프로토콜

Session endpoint는 세션마다 부여되는 인증된 URL이며, 요청의 HTTP 메서드, 경로, 쿼리 문자열, 본문과 WebSocket 연결을 허용된 포트로 전달한다. 접근 가능한 포트는 CreateAgentRuntime의 allowedPorts에서 1~5개 항목으로 지정하고, 각 항목에는 예약된 플랫폼 포트를 제외한 8000~12000 범위의 단일 포트나 포트 범위를 넣을 수 있다. 포트를 허용하는 것만으로 서버가 시작되지는 않으므로 앱이 해당 포트에서 직접 실행되어야 하며, 바인딩 주소는 0.0.0.0이어야 한다. 클라이언트는 대상 포트와 관계없이 443으로 연결하고, 호스트 이름 앞의 8090-- 또는 8081-- 같은 접두사가 세션 내부의 목적지 포트를 선택한다. 지원되는 통신에는 HTTP/1.1, HTTP/2, server-sent events, gRPC와 WebSocket이 포함되며, 본문의 실습은 HTTP/1.1과 WebSocket을 사용한다.

3. 요청별 인증과 로컬 브라우저 연결

IAM을 사용하는 runtime에서는 각 HTTP 요청, HTTP/2 스트림, WebSocket handshake에 Signature Version 4인 SigV4 서명이 필요하며, 호출자는 runtime과 해당 runtime endpoint에 대한 bedrock-agentcore:InvokeAgentRuntimeProxy 권한도 가져야 한다. 인바운드 JWT authorizer를 사용하는 runtime에서는 요청마다 bearer token을 전달하므로, 어느 방식이든 URL을 아는 것만으로 접근 권한이 생기지는 않는다. 원문은 브라우저가 페이지에서 발생하는 요청에 이러한 서명이나 토큰을 스스로 추가할 수 없다는 점을 설명하고, bedrock-agentcore SDK의 Session endpoint 클라이언트로 로컬 엔드포인트를 여는 방식을 제시한다. 브라우저가 localhost:8088로 요청하면 로컬 엔드포인트가 각 요청과 WebSocket handshake에 자격 증명을 추가해 Session endpoint로 전달한다. 세션 URL은 InvokeAgentRuntime 응답의 X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url 헤더에서 얻으며, 이를 모델링하는 SDK에서는 sessionEndpointUrl로 노출된다.

4. runtime endpoint와 세션 미리보기의 구분

원문은 기존 runtime endpoint와 Session endpoint가 서로 다른 역할을 맡는다고 구분한다. DEFAULT 같은 runtime endpoint는 InvokeAgentRuntime 호출이 어떤 에이전트 버전에 도달할지 결정하므로, 호출자를 바꾸지 않고 개발·운영 버전을 분리하거나 버전을 승격·롤백할 수 있다. Session endpoint는 해당 세션에서 실행되는 웹 미리보기 같은 앱에 접근하는 통로로, 세션이 사용하는 버전에 맞춰 동작하면서 allowedPorts에 지정된 포트만 연결한다. 이 URL은 모든 요청에서 자격 증명을 요구하고 세션이 종료되면 작동을 멈추므로, 에이전트가 만든 결과를 빌드하고 테스트하고 검토하는 용도로 설명된다. 따라서 실제 사용자에게 앱을 제공하려면 AWS Amplify Hosting 같은 호스팅 서비스에 배포해야 하며, 세션 미리보기와 사용자 대상 서비스 배포는 수명과 목적이 다르다.

5. 에이전트·Vite·PreviewApp의 요청 흐름

샘플의 네 구성 요소는 8080에서 실행되는 코딩 에이전트, 8090의 Vite 개발 서버, 사용자 컴퓨터의 PreviewApp, 브라우저의 미리보기 페이지이며, 에이전트는 list·read·write·edit 도구로 사이트 파일을 다룬다. PreviewApp은 먼저 InvokeAgentRuntime을 호출해 세션과 웹사이트를 시작하고, 응답에서 Session endpoint URL을 읽어 8090에 연결되는 로컬 엔드포인트를 연다. 사이트 영역의 요청은 localhost:8088, 자격 증명을 추가하는 로컬 엔드포인트, 서명과 allowedPorts를 검사하는 Session endpoint를 거쳐 Vite에 도달하며, hot-reload용 WebSocket은 열린 상태로 유지된다. 채팅 프롬프트는 별도로 AWS 자격 증명으로 서명된 InvokeAgentRuntime 호출을 통해 8080의 에이전트에 전달되고, 작업 단계가 채팅 영역으로 스트리밍된다. 에이전트가 Amazon Bedrock의 Claude Haiku 5.5를 호출해 변경을 결정하고 파일을 저장하면 Vite가 같은 WebSocket 경로로 변경을 전달하며, 노트북에서는 동일한 Session endpoint의 대상 포트만 8081로 바꿔 /status도 조회한다.

6. 실습 요구사항과 지원 범위

실습에는 AgentCore runtime Session endpoints를 지원하는 AWS 리전의 계정과 설정된 자격 증명이 필요하며, IAM 역할 생성, Amazon S3 업로드, runtime 생성 권한이 요구된다. 또한 해당 runtime과 DEFAULT runtime endpoint에 대한 bedrock-agentcore:InvokeAgentRuntime 및 bedrock-agentcore:InvokeAgentRuntimeProxy 권한, Amazon Bedrock의 Claude Haiku 5.5 접근 권한이 필요하고 모델의 리전별 가용성도 확인 대상으로 제시된다. 로컬 환경은 Python 3.10 이상, bedrock-agentcore 1.25.2 이상, boto3 1.43.122 이상, Git과 Jupyter 실행 환경을 갖춰야 하며, 패키징에는 Node.js 22 이상과 npm을 사용한다. 샘플은 Node.js 직접 코드 배포를 통해 Amazon S3에 저장된 zip 파일을 사용하므로 Docker나 Amazon ECR 저장소를 요구하지 않는다. Session endpoints는 microVM runtime에서 작동하고 Instances 컴퓨팅 유형에서는 작동하지 않으며, URL은 공개 HTTPS로 접근하고 인바운드 연결에 AWS PrivateLink는 지원하지 않는다.

7. 배포 설정과 샘플 경로의 불일치

deploy.py는 에이전트를 하나의 파일로 묶고 runtime의 Linux on Arm64 환경에 맞는 웹사이트와 의존성을 추가한 뒤, zip 파일을 Amazon S3에 올리고 runtime을 생성한다. 배포 예시는 NODE_22와 app.js를 사용하며, protocolConfiguration에는 HTTP·8080·/invocations를 지정하고 allowedPorts에는 웹사이트용 8090과 상태 조회용 8081만 넣는다. 에이전트 호출은 InvokeAgentRuntime으로 도달하므로 8080을 allowedPorts에 넣지 않으며, Vite는 0.0.0.0:8090에서 수신하고 runtime이 할당한 호스트 이름을 받도록 server.allowedHosts를 true로 설정한다. 원문은 서버에 도달하기 전에 Session endpoint가 모든 요청을 인증하므로 이 구성에서 Vite 자체의 호스트 검사가 필요하지 않다고 설명하고, 저장소 복제 후 session_endpoints_preview.ipynb의 의존성 설치 셀과 deploy.py 실행 셀을 실행해 READY 상태를 기다리도록 안내한다. 다만 도입부는 전체 샘플 위치를 agentcore-samples의 14-remote-access 폴더라고 소개하는 반면, 실제 이동 명령은 01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints를 가리켜 제공된 본문 안에서 경로 표기가 일치하지 않는다.

8. 미리보기 실행과 제공된 본문의 한계

runtime이 준비되면 PreviewApp().start() 호출 한 번으로 세션과 웹사이트를 시작하고, 8090용 로컬 엔드포인트를 열며, localhost:8087에서 미리보기 페이지를 제공한다. 내부에서는 빈 프롬프트를 담은 최초 InvokeAgentRuntime 호출의 응답에서 session_endpoint_url로 URL을 읽고, session_endpoint_client를 생성한 뒤 open_local_endpoint(port=8090, local_port=8088).start()로 웹사이트 연결을 연다. 사용자는 출력된 http://localhost:8087 링크를 브라우저에서 열며, 오른쪽에는 세션의 8090에서 제공되는 웹사이트가, 왼쪽에는 제안 요청을 담은 짧은 안내가 표시된다. 도입부는 사이트를 어두운 색상 테마로 바꾸도록 요청하고 스트리밍되는 작업 단계와 새로고침 없는 화면 변화를 살펴본 뒤, 두 번째 포트와 거부되는 요청까지 확인할 예정이라고 설명한다. 그러나 실제 제공된 source_body는 변경 요청 절에서 에이전트가 파일을 읽고 수정하는 설명 도중 끊기므로, 테마 변경의 구체적인 실행 결과나 요청 거부 실험의 세부 결과는 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 검토 속도를 높이는 핵심은 에이전트가 수정하는 파일과 실행 중인 웹사이트를 같은 세션에 두고, Vite의 변경 전달 경로를 브라우저까지 유지하는 데 있다.
• 앱 미리보기와 에이전트 호출은 서로 다른 경로를 사용한다. 따라서 샘플에서 8080을 Session endpoints에 허용하지 않아도 에이전트 호출과 웹사이트 검토가 함께 작동한다.
• 세션마다 인증된 접근을 제공하더라도 URL의 수명과 네트워크 지원 범위에는 제약이 있다. 이 구성의 효용은 개발 중 검토에 있으며, 사용자에게 지속적으로 앱을 제공하는 단계에는 별도 호스팅이 필요하다.

✅ 액션 아이템

• 샘플의 allowedPorts에 8090과 8081을 설정하고 8080은 제외하며, Vite 앱을 0.0.0.0에 바인딩해 실행한다.
• PreviewApp의 localhost:8088을 통해 인증된 요청과 WebSocket 연결을 전달하고, Vite 파일 저장 시 화면 갱신을 시험한다.
• Session endpoints의 URL이 세션 종료와 함께 작동을 멈추는 제약을 반영해, 사용자에게 제공할 앱은 AWS Amplify Hosting 같은 호스팅 서비스에 배포한다.

❓ 열린 질문

• Session endpoints의 요청별 인증에는 IAM 기반 SigV4와 인바운드 JWT authorizer용 bearer token 중 어떤 방식을 적용할 것인가?
• 공개 HTTPS 접근과 인바운드 AWS PrivateLink 미지원 조건이 웹 앱을 시험할 환경의 네트워크 요구에 부합하는가?
• Vite 파일 저장부터 WebSocket을 통한 화면 갱신까지 얼마나 걸리며, 변경마다 재배포하는 방식보다 검토 대기 시간이 얼마나 줄어드는가?