Kuri 정리: Zig 기반 AI 에이전트용 브라우저 자동화 도구

핵심 요약

Kuri는 AI 에이전트가 웹페이지를 읽고 상호작용하는 일을 더 가볍고 싸게 만들기 위해 만든 Zig 기반 브라우저 자동화 도구다.

핵심 강점은 작은 바이너리, 낮은 토큰 비용, Chrome 자동화와 비Chrome 수집 도구를 함께 제공한다는 점이다.

단순히 "기능이 많은 도구"가 아니라, "에이전트 루프에 유리한 출력과 운영 방식"에 초점을 둔 프로젝트다.

Kuri가 무엇인지

Kuri는 웹 자동화와 크롤링을 AI 에이전트 관점에서 다시 설계한 도구 모음이다.

보통 브라우저 자동화 도구는 QA나 테스트 엔지니어를 위한 경우가 많아서, 기능은 많지만 무겁고 출력도 장황하다.

Kuri는 반대로 에이전트가 실제로 자주 하는 일, 즉 페이지를 읽고, 필요한 요소를 찾고, 클릭하고, 결과를 다시 읽는 흐름에 맞춰 설계되었다.

구성도 명확하다.

kuri         # Chrome CDP 서버
kuri-fetch   # Chrome 없이 가져오기
kuri-browse  # 터미널 브라우저
kuri-agent   # 명령형 자동화 CLI

쉽게 말해, "브라우저를 조종하는 엔진", "가볍게 긁어오는 수집기", "터미널 브라우저", "자동화용 리모컨"을 한 프로젝트 안에 묶어 둔 셈이다.

왜 AI 에이전트에 유리한가

Kuri의 핵심 메시지는 출력이 작기만 해서는 안 된다는 점이다.

토큰이 적어도 페이지가 제대로 렌더링되지 않으면, 그 결과는 싼 것이 아니라 실패한 것이다.

예를 들어 JS 중심 SPA에서 어떤 도구는 토큰 수가 매우 적게 나오지만, 실제로는 빈 껍데기만 읽은 경우가 있다.

Kuri는 이런 함정을 피하려고, 실제 렌더링된 페이지에서 상호작용 가능한 정보만 뽑는 방식에 힘을 준다.

특히 접근성 트리 기반 스냅샷과 @eN 참조 구조는 에이전트가 "이 버튼을 클릭하라" 같은 명령을 안정적으로 수행하도록 돕는다.

즉, Kuri의 목표는 "많이 보여주기"보다 "행동 가능한 상태를 저렴하게 제공하기"에 가깝다.

성능과 토큰 비용의 의미

문서에서 가장 강조하는 수치는 전체 에이전트 작업 루프의 비용이다.

예시 기준으로 go → snap → click → snap → eval 한 사이클에서 kuri-agent는 4,110토큰, agent-browser는 4,880토큰을 사용했다.

이 차이는 한 번만 보면 작아 보이지만, 여러 페이지를 오가며 반복 작업하는 에이전트에서는 누적 비용 차이가 커진다.

또한 Kuri는 액션 결과를 평평한 JSON으로 돌려준다.

예를 들어 클릭 결과가 복잡한 브라우저 내부 응답이 아니라 {"ok":true} 같은 단순 형태라서, 모델이 읽어야 할 토큰이 줄어든다.

바이너리 크기도 작다.

CLI 바이너리는 약 464KB 수준으로 소개되며, 설치 크기 역시 비교적 작다.

이 점은 서버리스, CI, 로컬 배포처럼 "빨리 내려받고 바로 실행해야 하는 환경"에서 특히 유리하다.

네 가지 실행 모드의 역할

kuri는 HTTP API 서버다.

Chrome DevTools Protocol(CDP)을 통해 탭을 찾고, 이동하고, 스냅샷을 만들고, 스크린샷을 찍고, 스크립트를 실행한다.

kuri-fetch는 Chrome 없이 동작하는 독립 수집기다.

QuickJS를 내장해 간단한 스크립트 실행도 가능하므로, 가벼운 SSR 스타일 처리에 적합하다.

kuri-browse는 터미널 안에서 웹을 훑는 도구다.

링크에 번호를 붙여 이동하고, 검색하고, 기록을 보는 흐름이 텍스트 기반 브라우징에 맞게 구성되어 있다.

kuri-agent는 반복 가능한 자동화를 위한 CLI다.

한 번 탭에 연결하면 세션을 저장하고, 이후 go, snap, click, eval 같은 명령을 이어서 실행할 수 있다.

이 네 가지는 경쟁 관계가 아니라 역할 분담 관계다.

무거운 상호작용은 kuri/kuri-agent, 빠른 수집은 kuri-fetch, 사람 눈으로 빠르게 훑는 작업은 kuri-browse가 맡는다.

HTTP API가 제공하는 핵심 기능

Kuri 서버는 JSON 기반 HTTP API를 제공한다.

핵심 흐름은 /discover로 탭을 찾고, /tabs로 목록을 보고, /navigate로 이동한 뒤, /snapshot이나 /text로 내용을 읽는 것이다.

그 위에 실전 기능이 많이 얹혀 있다.

예를 들어 /action으로 클릭·타이핑·스크롤을 하고, /evaluate로 자바스크립트를 실행하고, /screenshot과 /pdf로 결과를 남길 수 있다.

또한 /markdown, /links, /dom/query, /dom/html 같은 추출 기능도 있다.

여기서 중요한 점은 Kuri가 단지 "브라우저 조작기"가 아니라, "읽기와 추출"을 함께 고려한 API라는 것이다.

에이전트 입장에서는 브라우저를 움직이는 것만큼, 읽기 쉬운 형태로 결과를 받는 것이 중요하기 때문이다.

HAR 기록과 API 재생의 실전성

Kuri는 HAR 기록 기능을 내장한다.

/har/start, /har/stop, /har/status로 네트워크 트래픽을 기록하고 상태를 확인할 수 있다.

더 흥미로운 점은 /har/replay다.

이 기능은 수집된 요청을 바탕으로 API 맵과 함께 curl, fetch, Python 코드 스니펫까지 만들어 준다.

즉, 사용자는 브라우저에서 실제로 발생한 네트워크 호출을 확인한 뒤, 그 흐름을 코드로 옮기는 실마리를 얻을 수 있다.

브라우저 자동화에서 종종 중요한 순간은 "클릭 자체"가 아니라 "클릭 뒤에 어떤 API가 호출됐는가"를 파악하는 것이다.

이 점에서 Kuri는 UI 자동화와 API 분석 사이를 잇는 도구로도 볼 수 있다.

보안, 스텔스, 차단 우회

Kuri는 자동화 탐지 회피를 중요한 기능으로 다룬다.

시작할 때 스텔스 패치를 자동 적용하고, navigator.webdriver 노출을 줄이며, WebGL·Canvas·AudioContext 같은 지문 요소도 조정한다.

또한 차단 감지도 한다.

/navigate 호출 시 Akamai, Cloudflare, PerimeterX, DataDome, 일반 캡차를 감지해 구조화된 응답과 우회 힌트를 준다.

프록시 설정도 KURI_PROXY 환경변수로 지원한다.

한편 보안 면에서는 SSRF 방어, JSON 주입 방지, URL 검증 같은 서버 안전장치가 강조되어 있다.

즉, Kuri는 "남의 차단을 피하는 기능"만 넣은 것이 아니라, "내 서버가 위험해지지 않도록 막는 기능"도 함께 챙긴 셈이다.

kuri-fetch와 kuri-browse의 쓰임새

kuri-fetch는 Chrome이 필요 없다는 점이 가장 큰 장점이다.

간단한 페이지 수집, 링크 추출, 텍스트 변환, 마크다운 생성 같은 작업에 적합하다.

--js 옵션을 쓰면 QuickJS로 인라인 스크립트도 실행할 수 있어, 완전한 브라우저는 아니어도 더 똑똑한 수집이 가능하다.

반대로 kuri-browse는 사람 친화적이다.

웹페이지를 터미널 안에서 읽고, 번호로 링크를 따라가고, /term 같은 방식으로 검색할 수 있다.

복잡한 자동화보다는 "문서 읽기", "빠른 조사", "저사양 환경에서의 웹 탐색"에 잘 맞는다.

둘 다 공통적으로 Chrome 의존성이 없어서, 무거운 환경 구성이 부담스러운 상황에서 가치가 크다.

kuri-agent와 보안 점검 흐름

kuri-agent는 브라우저 보안 점검에도 초점을 둔다.

로그인 후 쿠키를 확인하거나, 응답 헤더를 검사하거나, 종합 감사를 수행할 수 있다.

예를 들어 보안 플래그가 없는 쿠키, 누락된 x-frame-options, JS에 노출된 민감 쿠키 같은 문제를 빠르게 확인할 수 있다.

또 eval을 이용하면 현재 로그인 세션 상태로 API 호출을 재현해 볼 수 있어, IDOR 같은 접근 제어 문제를 탐색하는 데도 활용할 수 있다.

이 도구의 장점은 "로그인된 브라우저 상태"를 그대로 활용한다는 점이다.

따라서 별도로 토큰을 복사하거나 API 클라이언트를 다시 짜지 않고도, 실제 사용자 흐름에 가까운 점검이 가능하다.

구조와 구현 철학

Kuri는 Zig로 작성되었고, 메모리 관리와 실행 구조도 그 철학을 드러낸다.

문서에서는 요청 단위 arena 메모리, GC 없음, 명확한 정리 체인, errdefer 기반 롤백을 강조한다.

아키텍처는 크게 HTTP API 계층, 브라우저 브리지, 크롤러 엔진, 독립 CLI 계층으로 나뉜다.

Chrome 관리도 두 모드로 분리된다.

CDP_URL이 없으면 관리형으로 Chrome을 직접 띄우고 감시하며, 값이 있으면 외부 Chrome에 붙기만 한다.

즉, Kuri는 단순히 "기능을 많이 붙인 툴"이 아니라, 가벼운 배포와 예측 가능한 운영을 중시하는 시스템으로 설계되어 있다.

설치, 실행, 시작 흐름

설치는 크게 세 가지다.

가장 쉬운 방법은 설치 스크립트이고, npm/bun 패키지도 제공하며, 직접 빌드도 가능하다.

curl -fsSL https://raw.githubusercontent.com/justrach/kuri/main/install.sh | sh

소스에서 빌드하려면 Zig 0.15 계열이 필요하다.

git clone https://github.com/justrach/kuri.git
cd kuri
zig build -Doptimize=ReleaseFast

첫 실행 흐름은 매우 단순하다.

./zig-out/bin/kuri
curl -s http://127.0.0.1:8080/discover
curl -s http://127.0.0.1:8080/tabs

그다음 tab_id를 얻어 /navigate, /snapshot 순으로 진행하면 된다.

학습 관점에서는 이 흐름만 익혀도 Kuri의 절반 이상을 이해한 셈이다.

인사이트

Kuri의 본질은 "브라우저 자동화 도구"보다 "에이전트 루프 최적화 도구"에 가깝다.

기능 수 경쟁보다 토큰 절약, 출력 단순화, 작은 배포 단위, 실제 렌더링 기반 읽기에 집중한 점이 차별점이다.

실무에서는 이렇게 접근하면 좋다.

브라우저 상호작용이 필요하면 kuri 또는 kuri-agent를 쓰고, 단순 수집은 kuri-fetch, 빠른 탐색은 kuri-browse로 나누어 쓰면 된다.

특히 LLM 기반 자동화를 만든다면, "잘 렌더링된 적은 출력"이 "작지만 빈 출력"보다 훨씬 가치 있다는 점을 Kuri 사례가 잘 보여준다.