agent-browser

스트리밍

웹 소켓을 통해 브라우저 뷰포트를 스트리밍하여 실시간 미리보기 또는 "짝 맞춤 탐색"(pair browsing) 기능을 사용합니다.
이 기능을 통해 인간이 인공지능 에이전트와 함께 작업하면서 시각적으로 관찰하고 상호작용할 수 있습니다.

스트리밍 활성화

AGENT_BROWSER_STREAM_PORT 환경 변수를 설정하여 웹소켓 서버를 시작하세요:

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

서버는 뷰포트 프레임을 스트리밍하고 마우스, 키보드, 터치 입력 이벤트를 수신합니다.

웹소켓 프로토콜

ws://localhost:9223에 연결하여 프레임을 수신하고 입력을 전송합니다.

프레임 메시지

서버는 기본적으로 이미지를 베이스64 인코딩한 형태로 프레임 메시지를 전송합니다:

{
  "type": "frame",
  "data": "<베이스64-인코딩된-jpeg>",
  "metadata": {
    "deviceWidth": 1280,
    "deviceHeight": 720,
    "pageScaleFactor": 1,
    "offsetTop": 0,
    "scrollOffsetX": 0,
    "scrollOffsetY": 0
  }
}

상태 메시지

연결 상태 및 화면 공유 상태 정보:

{
  "type": "status",
  "connected": true,
  "screencasting": true,
  "viewportWidth": 1280,
  "viewportHeight": 720
}

입력 주입

원격으로 브라우저를 제어하기 위해 입력 이벤트를 전송합니다.

마우스 이벤트

// 클릭
{
  "type": "input_mouse",
  "eventType": "mousePressed",
  "x": 100,
  "y": 200,
  "button": "left",
  "clickCount": 1
}

// 해제
{
  "type": "input_mouse",
  "eventType": "mouseReleased",
  "x": 100,
  "y": 200,
  "button": "left"
}

// 이동
{
  "type": "input_mouse",
  "eventType": "mouseMoved",
  "x": 150,
  "y": 250
}

// 스크롤
{
  "type": "input_mouse",
  "eventType": "mouseWheel",
  "x": 100,
  "y": 200,
  "deltaX": 0,
  "deltaY": 100
}

키보드 이벤트

// 키 다운
{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "Enter",
  "code": "Enter"
}

// 키 업
{
  "type": "input_keyboard",
  "eventType": "keyUp",
  "key": "Enter",
  "code": "Enter"
}

// 문자 입력
{
  "type": "input_keyboard",
  "eventType": "char",
  "text": "a"
}

// 수정자 키 포함 (1=Alt, 2=Ctrl, 4=Meta, 8=Shift)
{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "c",
  "code": "KeyC",
  "modifiers": 2
}

터치 이벤트

// 터치 시작
{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{ "x": 100, "y": 200 }]
}

// 터치 이동
{
  "type": "input_touch",
  "eventType": "touchMove",
  "touchPoints": [{ "x": 150, "y": 250 }]
}

// 터치 종료
{
  "type": "input_touch",
  "eventType": "touchEnd",
  "touchPoints": []
}

// 멀티터치 (줌 인/아웃)
{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [
    { "x": 100, "y": 200, "id": 0 },
    { "x": 200, "y": 200, "id": 1 }
  ]
}

프로그래밍 인터페이스

고급 사용을 위해 타입스크립트 API를 직접 사용하여 스트리밍을 제어할 수 있습니다:

import { BrowserManager } from 'agent-browser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// 캡처 콜백과 함께 시작
await browser.startScreencast((frame) => {
  console.log('프레임:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
  // frame.data는 베이스64 인코딩된 이미지입니다
}, {
  format: 'jpeg',  // 또는 'png'
  quality: 80,     // 0-100, jpeg 전용
  maxWidth: 1280,
  maxHeight: 720,
  everyNthFrame: 1
});

// 마우스 이벤트 주입
await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1
});

// 키보드 이벤트 주입
await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter'
});

// 터치 이벤트 주입
await browser.injectTouchEvent({
  type: 'touchStart',
  touchPoints: [{ x: 100, y: 200 }]
});

// 화면 공유 중인지 확인
console.log('활성:', browser.isScreencasting());

// 화면 공유 중지
await browser.stopScreencast();

활용 사례

  • 짝 맞춤 탐색(Pair browsing) - 인간이 실시간으로 인공지능 에이전트의 작업을 감시하고 지원
  • 원격 미리보기 - 별도의 사용자 인터페이스에서 브라우저 출력을 확인
  • 기록 - 비디오 생성을 위한 프레임 캡처
  • 모바일 테스트 - 모바일 시뮬레이션을 위한 터치 이벤트 주입
  • 접근성 테스트 - 자동화 테스트 중 수동 상호작용 수행