AI 튜토리얼

로컬 우선 웹 조사와 브라우저 자동화를 위한 qz-browser-agent 사용법

브라우저 자동화, 웹 조사, 구조화된 추출, 병렬 작업, Skills 및 TypeScript 기능을 지원하는 로컬 우선 Chrome 확장 프로그램 qz-browser-agent의 설치 및 사용법을 알아보세요. 이 가이드에서는 모델 설정, 실용적인 프롬프트, 소스 빌드, 개발 워크플로와 확장 프로그램 옵션을 다룹니다.

2026년 10월 12일약 9분 소요

로컬 우선 웹 조사와 브라우저 자동화를 위한 qz-browser-agent 사용법

qz-browser-agent란?

qz-browser-agent는 轻舟 또는 “가벼운 배”라고도 하며, 웹 리서치, 브라우저 자동화, 구조화된 데이터 추출을 위한 로컬 우선 Chrome 확장 프로그램입니다. 원하는 모델 제공업체를 연결하고, 브라우저 사이드 패널을 통해 웹사이트와 상호작용하며, 재사용 가능한 Skills 또는 TypeScript 기능으로 에이전트를 확장할 수 있습니다.

세션, Skills, 수집된 데이터는 브라우저에 저장됩니다. 모델 요청에는 프롬프트와 작업 컨텍스트에 추가한 페이지 또는 파일 콘텐츠가 포함될 수 있습니다. Skills 및 MCP 연결은 사용자가 구성한 서비스와 데이터를 주고받을 수 있으므로, 외부 서비스를 사용하기 전에 프로젝트의 권한 및 데이터 흐름 문서를 검토하세요.

주요 기능

브라우저 자동화: DOM 요소 또는 스크린샷과 상호작용하고, 양식을 작성하며, 데스크톱 또는 모바일 뷰포트에서 여러 탭을 오가며 작업할 수 있습니다.
병렬 하위 작업: 작업을 동시에 실행하고, 진행 중인 작업을 중단하거나 방향을 바꾸거나 컨텍스트를 추가할 수 있습니다.
구조화된 데이터: 표, 미디어, 페이지 콘텐츠를 로컬 컬렉션으로 추출한 다음 사이드 패널에서 결과를 미리 보고 편집하고 내보낼 수 있습니다.
Skills: 지침, 스크립트, 도구, 사용자 지정 사이드 패널 UI를 재사용 가능한 워크플로로 패키징하며, 일치하는 웹사이트에서 선택적으로 활성화할 수 있습니다.
모델 선택: 로컬 모델 서버를 포함하여 호환되는 API 프로토콜과 도구 호출을 지원하는 제공업체에 연결할 수 있습니다.
TypeScript 기능: 에이전트 도구, 패널 뷰, 설정 페이지 또는 모델 제공업체를 추가할 수 있습니다.
MCP 브리지: 선택적으로 로컬 MCP 브리지를 통해 외부 에이전트에 브라우저 도구와 작업 제어 기능을 제공할 수 있습니다.

Chrome 확장 프로그램 설치

소스에서 빌드

로컬에서 qz를 빌드하려면 Node.js 24 LTS와 npm을 설치한 다음 저장소를 클론하거나 다운로드합니다. 프로젝트 디렉터리에서 종속 항목을 설치하고 확장 프로그램을 빌드합니다.

npm ci
npm run build

빌드가 완료되면 chrome://extensions로 돌아가 압축해제된 확장 프로그램을 로드를 선택하고 생성된 dist/extension/ 디렉터리를 지정합니다.

모델 제공업체 구성

확장 프로그램 툴바에서 qz 사이드 패널을 엽니다.
설정을 엽니다.
모델 제공업체를 선택하고 인증 정보를 입력합니다.
사용자 지정 엔드포인트를 사용하는 경우 URL과 지원되는 프로토콜을 모두 입력합니다.
모델을 선택하고 구성을 저장합니다.

qz는 지원되는 API 프로토콜과 도구 호출을 제공하는 모델 제공업체에서 작동하도록 설계되었습니다. 설정에 따라 호환되는 호스팅 제공업체 또는 로컬 모델 서버를 사용할 수 있습니다.

첫 번째 브라우저 작업 실행

제공업체를 구성한 후 간단한 리서치 및 추출 요청으로 시작해 보세요.

example.com을 열고 기본 제목을 표로 추출합니다.

에이전트는 요청한 페이지로 이동해 콘텐츠를 검사하고 추출한 결과를 로컬 컬렉션에 저장할 수 있습니다. 사이드 패널에서 수집된 데이터를 미리 보거나 편집하고, 컬렉션이 준비되면 내보내세요.

Wikipedia에서 항저우 사진을 수집하는 qz

더 복잡한 리서치에서는 여러 페이지 또는 탭에 걸쳐 작업하도록 qz에 요청하세요. 작업에 서로 독립적인 부분이 포함되어 있다면 병렬 하위 작업을 통해 동시에 처리할 수 있습니다. 실행 중인 작업을 중단하거나 방향을 바꾸거나 추가 컨텍스트를 제공할 수도 있습니다.

Skills로 qz 확장

Skills는 반복 가능한 워크플로를 위한 재사용 가능한 패키지입니다. 하나의 Skill에 지침, JavaScript 자동화, 도구, 사이드 패널의 사용자 지정 대화형 위젯을 결합할 수 있습니다. Site Skills는 일치하는 웹사이트에서 활성화되도록 구성할 수도 있습니다.

qz 인터페이스에서 Skills를 관리하거나 Git 저장소에서 설치하세요. 특정 사이트에서 정보를 수집하거나 사용자 지정 패널 컴포넌트를 통해 결과를 표시하는 등 반복적인 리서치 작업에서 일관된 동작이 필요할 때 Skills를 사용하면 좋습니다.

TypeScript 기능 추가

TypeScript 기능을 사용하면 개발자가 확장 프로그램에 새로운 기능을 기여할 수 있습니다. 에이전트 도구, 도구 결과 렌더러, 설정 페이지, 패널 뷰 또는 모델 제공업체를 제공할 수 있습니다.

시작하려면 프로젝트의 기능 예제를 src/capabilities/로 복사하고 등록 이름을 변경한 다음 기능에 필요한 기여 항목만 남깁니다. 최소 엔트리 파일은 다음과 같이 도구와 렌더러를 내보낼 수 있습니다.

// src/capabilities/<your-feature>/index.ts
export { default as tools } from "./tools.js";
export { default as renderers } from "./renderers.js";

빌드 시스템은 이러한 선언을 자동으로 검색합니다. 도구 핸들러는 백그라운드 서비스 워커에서 실행되며 활성 탭에 작업이나 스크립트 실행을 위임할 수 있습니다. 렌더러는 사이드 패널에 대화형 결과 카드를 마운트합니다.

SDK 세부 정보와 현재 확장 프로그램 계약은 기능 가이드와 프로젝트의 기여자 문서를 참조하세요. 이러한 API는 실험적이므로 확장 프로그램을 개발할 때 변경 가능성을 고려하세요.

개발 워크플로

명령어 및 빌드 옵션 문서에 따라 프로젝트의 테스트 환경을 설정하세요. 주요 개발 명령어는 다음과 같습니다.

npm run dev       # 소스 변경 시 다시 빌드
npm test          # 기본 테스트 모음 실행
npm run verify    # 타입 검사 및 커버리지와 함께 자동화된 테스트 모음 실행

다시 빌드한 후 chrome://extensions에서 확장 프로그램을 새로고침하고 qz 사이드 패널을 다시 여세요. 이렇게 하면 Chrome이 최신으로 생성된 확장 프로그램 파일을 사용하게 됩니다.

고급 사용 팁

구조화된 프롬프트 사용: 대상 페이지, 수집할 필드, 원하는 출력 형식을 설명하면 추출한 데이터를 유용한 컬렉션으로 정리할 수 있습니다.
적절한 상호작용 모드 선택: DOM 기반 상호작용은 페이지 요소와 양식에 유용하며, 시각적 맥락이 중요할 때는 스크린샷 기반 상호작용이 도움이 될 수 있습니다.
반복 가능한 워크플로 분리: 반복되는 지침과 스크립트는 매번 프롬프트에 입력하는 대신 Skills로 구성하세요.
병렬 작업은 신중하게 사용: 서로 독립적인 조사 하위 작업을 동시에 위임한 다음 사이드 패널에서 통합 결과를 검토하세요.
적절한 경우 로컬 서비스 우선: qz는 로컬 모델 서버를 지원하므로 모델 트래픽을 직접 관리하는 인프라 내부에 유지하는 데 도움이 될 수 있습니다.
데이터 연결 검토: 페이지 콘텐츠, 파일, Skills, MCP 통합이 요청에 포함되거나 구성된 서비스와 교환될 수 있습니다. 민감한 정보를 다루기 전에 권한을 확인하세요.
소스 변경 후 새로고침: 빌드가 성공해도 확장 프로그램이 자동으로 새로고침되지는 않습니다. 테스트하기 전에 Chrome에서 새로고침하세요.

선택적 MCP 통합

선택 사항인 로컬 MCP 브리지는 브라우저 도구와 작업 제어 기능을 외부 에이전트에 제공합니다. 다른 MCP 호환 에이전트나 애플리케이션으로 qz를 제어해야 할 때 사용하세요. MCP 연결은 구성된 서비스와 데이터를 교환할 수 있으므로, 활성화하기 전에 브리지 문서와 데이터 흐름에 미치는 영향을 검토하세요.

결론

qz-browser-agent는 Chrome 사이드 패널, 모델 기반 브라우저 자동화, 구조화된 로컬 컬렉션, 병렬 하위 작업, Skills와 TypeScript를 통한 확장 기능을 결합합니다. 빠르게 시작하려면 릴리스를 설치하고, 호환되는 모델 제공자를 구성한 다음, 범위를 명확히 정한 추출 프롬프트를 사용해 보세요. 사용자 지정 워크플로나 통합이 필요하다면 소스에서 빌드하고 Skills, 기능 또는 선택적 MCP 브리지로 프로젝트를 확장하세요.