agent-browser가 하는 일: AI 에이전트용 브라우저 명령줄 도구
클로드 코드나 코덱스 같은 AI 코딩 도구를 쓰다 보면 웹 페이지를 직접 봐야 하는 일이 자주 생깁니다. 내가 만든 화면이 제대로 뜨는지, 로그인 버튼이 눌리는지, 문서 사이트에서 최신 설정값이 뭔지 같은 것들입니다. 에이전트는 터미널 명령은 잘 다루지만 브라우저 창을 직접 볼 수는 없어서, 이 사이를 이어 줄 도구가 따로 필요합니다. agent-browser는 버셀 랩스가 만든 이 연결용 도구입니다.
방식은 단순합니다. agent-browser open으로 페이지를 열고, snapshot으로 화면을 읽으면 링크와 버튼, 입력칸이 e1, e2 같은 번호와 함께 짧은 글자 목록으로 나옵니다. 에이전트는 이 번호를 골라 click @e1이나 fill @e3처럼 명령을 보내고, 다시 snapshot을 찍어 결과를 봅니다. 사람이 화면을 보고 손으로 누르는 과정을 명령 한 줄씩으로 쪼갠 셈입니다. 브라우저는 명령 사이에도 계속 열려 있어서 한 번에 한 단계씩 짧게 진행할 수 있습니다.
내부에서는 첫 명령 때 뒤에서 도는 데몬 프로그램이 하나 뜨고, 이 데몬이 크롬 개발자 도구 프로토콜로 브라우저를 조종합니다. 기본 브라우저는 구글이 자동화용으로 배포하는 크롬 테스트용 버전이고, 이미 켜 둔 크롬에 붙거나 Lightpanda 같은 가벼운 엔진으로 바꿀 수도 있습니다. 명령을 한 시간 동안 받지 않으면 데몬은 화면 없는 브라우저를 닫고 스스로 꺼집니다.
저장소는 2026년 1월에 공개됐고 라이선스는 Apache-2.0이라 무료로 쓸 수 있습니다. 11월 10일에는 GitHub 일간 트렌딩 목록에 올라 하루에만 별이 900개 넘게 붙었고, 누적 별은 4만 8천 개를 넘었습니다. 같은 날 아침 0.42.0 버전이 나왔습니다.
agent-browser 설치 방법: npm 한 줄과 크롬 내려받기
설치에는 Node.js가 필요합니다. 공식 설치 문서가 가장 먼저 권하는 방법은 npm 전역 설치이고, 그다음 agent-browser install을 한 번 실행해 크롬 테스트용 버전을 받습니다. npm 패키지 안에 맥, 리눅스, 윈도우용 실행 파일이 함께 들어 있어서 운영체제에 맞는 파일을 알아서 고릅니다. 맥은 Homebrew, 러스트 개발 환경이 있다면 cargo로도 설치할 수 있고, 설치 없이 npx agent-browser로 바로 써 보는 방법도 있습니다.
이번에는 그래픽 카드가 없는 윈도우 클라우드 서버의 파워셸에서 설치했습니다. npm 패키지를 받는 데 26초, agent-browser install로 크롬 157.0.8103.50을 받는 데 58초가 걸렸고 크롬 용량은 201MB였습니다. 크롬은 사용자 폴더 아래 .agent-browser\browsers에 따로 저장돼서 원래 쓰던 크롬과 섞이지 않습니다. 설치가 끝나면 agent-browser --version으로 버전이 나오는지 보면 되고, 이번에 받은 버전은 0.42.0이었습니다.
리눅스에서는 크롬이 쓰는 시스템 라이브러리가 빠져 있으면 브라우저가 뜨지 않습니다. 이때는 agent-browser install 뒤에 --with-deps를 붙이면 필요한 라이브러리까지 함께 설치합니다. 맥은 13 버전보다 낮으면 크롬 내려받기 단계에서 멈추고 운영체제 업데이트를 안내합니다.
# 공식 권장: npm 전역 설치 후 크롬 테스트용 버전 받기
npm install -g agent-browser
agent-browser install
# 리눅스에서 시스템 라이브러리까지 함께 설치
agent-browser install --with-deps
# 설치 없이 한 번 써 보기
npx agent-browser install
npx agent-browser open example.com
# 설치 확인
agent-browser --versionagent-browser 첫 실행: 열고, 읽고, 누르고, 닫기
README의 빠른 시작 예제를 그대로 돌려 봤습니다. open example.com으로 페이지를 열고 snapshot -i를 치면 누를 수 있는 요소만 추려서 보여 주는데, example.com에는 Learn more 링크 하나뿐이라 결과도 한 줄입니다. 여기서 click @e1을 보내면 링크가 눌리고, get url로 주소를 물으면 IANA 안내 페이지로 넘어간 것이 나옵니다. close로 브라우저를 닫으면 한 바퀴가 끝납니다.
걸린 시간은 브라우저를 처음 띄우는 open이 10.7초로 가장 길었고, snapshot은 0.2초, click은 5.7초였습니다. 한 가지 주의할 점은 설치 직후 맨 처음 실행입니다. 크롬을 처음 띄우는 데 시간이 걸려 open 명령이 응답 대기 시간 초과 오류를 냈는데, 바로 snapshot을 찍어 보니 페이지는 이미 열려 있었습니다. 오류 문구에도 명령이 실행됐을 수 있어서 다시 보내지 않았다고 적혀 있습니다. 첫 실행에서 이 오류가 나오면 같은 명령을 반복하기 전에 snapshot이나 get url로 상태부터 보는 편이 낫습니다.
윈도우에서 하나 더 걸린 부분은 셸을 나눠 쓸 때입니다. 셸 세션을 닫고 새로 연 뒤 앞에서 받은 번호로 fill을 보냈더니 Unknown ref 오류가 났습니다. 공식 문서에 따르면 윈도우는 데몬이 끝날 때 그 데몬이 띄운 크롬까지 통째로 종료합니다. 이번 환경에서는 셸이 닫힐 때 데몬도 함께 꺼지면서 브라우저와 번호 목록이 사라진 것이라, 한 셸 안에서 이어서 실행하니 같은 문제가 다시 나오지 않았습니다.
agent-browser로 위키백과 검색해 본 결과: 번호 붙은 화면과 출력 크기
실제 사이트에서는 어떤지 보려고 한국어 위키백과에서 같은 흐름을 돌렸습니다. 대문에서 snapshot -i를 찍으면 누를 수 있는 요소가 212줄 나오고, 그중 위키백과 검색 입력칸에 붙은 번호로 fill을 보내 헤드리스 브라우저라고 입력한 뒤 press Enter를 보냈습니다. get url과 get title로 보니 헤드리스 브라우저 문서로 정확히 넘어가 있었습니다. 사람이 하던 검색을 명령 네 줄로 끝낸 셈입니다.
에이전트에게 화면을 보여 줄 때는 출력 크기가 중요합니다. 출력이 길수록 AI 모델이 한 번에 읽어야 할 양이 늘고, 그만큼 사용량도 빨리 줄어듭니다. 헤드리스 브라우저 문서에서 누를 수 있는 요소만 보는 snapshot -i는 78줄, 약 2,300자였고, 보이는 글자까지 함께 담는 snapshot -c는 228줄, 약 7,000자로 세 배 정도 길었습니다. 내용이 긴 웹 브라우저 문서는 snapshot -i만으로도 694줄이 나왔습니다. 긴 페이지에서는 -s로 본문 영역만 고르거나 -d로 깊이를 줄여서 읽히는 편이 좋습니다.
글자 목록만으로 헷갈릴 때는 screenshot --annotate가 쓸 만합니다. 화면을 저장하면서 누를 수 있는 요소마다 빨간 상자와 번호를 붙여 주고, 그 번호가 snapshot의 e 번호와 같습니다. 아이콘만 있는 버튼이나 그림 위에 놓인 요소처럼 글자로 구분하기 어려운 곳을 고를 때 도움이 됩니다.
막힌 곳도 있었습니다. 화면 없이 도는 기본 모드에서 위키백과 페이지를 저장하려 하자 두 번 모두 응답 대기 시간 초과로 실패했고, --headed를 붙여 창이 보이는 모드로 띄우니 1초 남짓 만에 저장됐습니다. 원인을 정확히 가리지는 못했지만 저사양 서버에서 화면 저장이 자꾸 실패하면 --headed로 바꿔 보는 것이 빠른 해결책이었습니다. 또 국내 개발 뉴스 사이트 한 곳은 자동 접속을 막는다는 Forbidden 안내 화면만 돌려줬습니다. 자동화 브라우저는 사이트 입장에서 봇으로 보이기 쉬우니, 이런 곳은 반복해서 접속하지 말고 사이트 규칙을 따르는 것이 맞습니다.
agent-browser 기본값 주의점: 이동, 동작, 출력에 제한 없음
설치 전에 꼭 알아 둘 부분은 보안 기본값입니다. 공식 보안 문서 첫머리에 이동, 동작, 출력 제어는 직접 켜야 하는 선택 기능이고, 기본값에서는 아무 제한도 두지 않는다고 적혀 있습니다. 에이전트가 어떤 사이트로든 이동할 수 있고, 페이지 안에서 자바스크립트를 실행하거나 파일을 내려받고 올리는 것도 막히지 않는다는 뜻입니다.
이게 문제가 되는 이유는 에이전트가 읽는 웹 페이지 안에 사람 눈에는 안 보이는 지시문이 숨어 있을 수 있어서입니다. 페이지가 도구 출력이나 시스템 지시처럼 보이는 글자를 넣어 두면 AI 모델이 그 말을 따를 위험이 있습니다. 공식 문서도 이런 프롬프트 인젝션과, 조작된 에이전트가 공격자 사이트로 데이터를 빼돌리는 경우를 막아야 할 위협으로 꼽습니다.
대응 방법도 문서에 같이 있습니다. --allowed-domains로 들어갈 수 있는 도메인을 정해 두면 그 밖의 주소로 이동하거나 이미지, 스크립트를 불러오는 요청이 막힙니다. 다만 대부분의 사이트가 CDN에서 글꼴과 스크립트를 가져오기 때문에 그 도메인까지 넣지 않으면 페이지가 깨집니다. --action-policy에는 허용과 금지 동작을 적은 JSON 파일을 주고, --confirm-actions로 고른 동작은 실행 전에 승인을 받게 할 수 있습니다. --content-boundaries를 켜면 페이지에서 온 글자를 무작위 표식으로 감싸 도구 출력과 구분하게 해 주고, --max-output은 페이지 내용이 너무 길게 들어오지 않도록 자릅니다.
로그인이 필요한 사이트라면 비밀번호를 명령에 직접 넣지 말고 auth save로 저장한 뒤 auth login으로 쓰라고 안내합니다. 저장된 정보는 사용자 폴더의 .agent-browser\auth에 AES-256-GCM으로 암호화돼 남고, AI 모델에게는 비밀번호가 전달되지 않습니다. 허용 도메인 기능도 운영체제 방화벽을 대신하지는 못한다고 문서가 직접 적고 있으니, 중요한 계정에는 처음부터 쓰지 않는 편이 마음 편합니다.
# 정한 도메인만 열기 (CDN 도메인도 함께 넣어야 페이지가 안 깨짐)
agent-browser --allowed-domains "example.com,*.example.com" open https://example.com
# 동작 정책 파일 적용
agent-browser --action-policy ./policy.json open https://example.com
# policy.json 예: 자바스크립트 실행, 내려받기, 올리기 금지
{ "default": "allow", "deny": ["eval", "download", "upload"] }
# 페이지에서 온 글자를 표식으로 감싸기
agent-browser --content-boundaries snapshot근거 [3]
클로드 코드, 코덱스에 agent-browser 붙이는 법: 스킬과 MCP
agent-browser는 설치된 버전에 맞는 사용 설명서를 스킬 형태로 함께 들고 있습니다. agent-browser skills get core를 치면 기본 흐름과 번호 쓰는 법, 기다리는 법이 나오고, 에이전트가 이걸 먼저 읽고 따라 하게 만드는 것이 공식 권장 방식입니다. 프로젝트의 AGENTS.md에 두 줄을 넣어 두거나, npx skills add vercel-labs/agent-browser로 스킬을 설치해 두면 에이전트가 브라우저가 필요할 때 이 설명서를 불러옵니다.
MCP 방식을 쓰는 도구라면 agent-browser mcp로 MCP 서버를 띄울 수도 있습니다. 다만 명령줄과 스킬 조합이 기본이고, MCP는 그걸 쓰는 클라이언트를 위한 추가 경로에 가깝습니다. 스킬 설명서는 설치된 명령과 버전이 같이 움직이기 때문에, 버전을 올렸는데 설명서가 옛날 그대로라 명령이 틀리는 일이 적습니다.
# 에이전트가 먼저 읽을 기본 사용 설명서
agent-browser skills get core
# 스킬 설치 (스킬을 지원하는 코딩 도구용)
npx skills add vercel-labs/agent-browser
# MCP 서버로 실행
agent-browser mcp근거 [1]
agent-browser 0.42.0 새 기능과 Playwright MCP, Lightpanda와 차이
11월 10일에 나온 0.42.0에는 저장된 흐름(saved flows)이라는 실험 기능이 들어왔습니다. 브라우저로 한 번 해 본 작업을 기록해 두면, 다음부터는 그 작업에서 오간 요청을 다시 보내는 방식으로 빠르게 반복합니다. 먼저 주소로 직접 요청을 보내 보고, 안 되면 페이지 안에서 같은 요청을 보내고, 그래도 안 되면 기록한 명령을 처음부터 다시 실행하는 순서이고, 성공한 방식을 저장해 둡니다. 요청은 공개 주소로만 보낸다고 릴리스 노트에 적혀 있습니다. 아직 실험 단계라 매일 돌리는 중요한 작업에 바로 맡기기보다는 반복 조회 같은 가벼운 일부터 시험해 보는 편이 맞습니다.
비슷한 도구로 가장 많이 비교되는 것은 마이크로소프트의 Playwright MCP입니다. 둘 다 화면 사진 대신 접근성 트리라는 글자 구조로 페이지를 읽게 한다는 점은 같습니다. 차이는 연결 방식인데, Playwright MCP는 이름 그대로 MCP 서버이고, agent-browser는 명령줄과 스킬이 기본입니다. 흥미로운 점은 Playwright MCP README도 코딩 에이전트라면 명령줄과 스킬 조합이 더 나을 수 있다고 직접 적고 있다는 것입니다. 큰 도구 설명과 긴 접근성 트리를 매번 모델에게 넘기지 않아서 사용량을 아낄 수 있다는 이유입니다.
예전에 소개한 Lightpanda는 크롬 대신 쓰는 가벼운 헤드리스 브라우저 엔진이라 역할이 다릅니다. agent-browser는 --engine lightpanda로 이 엔진을 골라 쓸 수 있어서, 둘은 경쟁 관계라기보다 위아래로 맞물리는 관계에 가깝습니다. 정리하면 클로드 코드나 코덱스에 브라우저를 하나 붙여 보고 싶은 사람에게 agent-browser는 설치가 가장 짧은 축에 드는 선택지이고, 처음 붙일 때는 허용 도메인부터 정해 두는 것이 이 도구를 오래 편하게 쓰는 방법입니다.
