🔥 07. PageAgent: 웹페이지 안에서 움직이는 GUI 에이전트

PageAgent는 브라우저 확장이나 별도 헤드리스 환경 없이, 웹페이지 안에서 바로 자연어로 GUI를 제어하게 만드는 인페이지 에이전트다. 쉽게 말해 “웹앱 안에 AI 조작 레이어를 심는” 쪽에 가깝다.

이 레포는 7위 · ⭐ +6.2K로 회자된 프로젝트다. 별 숫자만 보면 유행처럼 보일 수 있지만, 실제로는 개발자들이 지금 어디에 시간을 쓰고 있는지를 꽤 솔직하게 드러낸다. 많은 자동화 도구가 브라우저 바깥에서 움직인다면, PageAgent는 페이지 안으로 들어간다. 백엔드 대수술 없이 제품 안에 AI 코파일럿을 얹고 싶어 하는 SaaS 팀에게 아주 매력적인 그림이다. 게다가 멀티모달 스크린샷 의존 대신 텍스트 기반 DOM 조작을 강조하는 것도 차별점이다.

flowchart LR
A[문제] --> B[page-agent]
B --> C[설치]
C --> D[최소 실험]
D --> E[업무 적용 판단]

칠판 판서형 치트시트

• 이 레포의 한 줄 키워드는 page-agent다.
• 이번 보강에서는 설치와 사용 순서를 공식 README 기준으로 더 촘촘하게 정리했다.
• 읽을 때는 전제 조건 → 설치 → 첫 실행 → 검증 순서로 보면 된다.
• “대단해 보인다”보다 “내 업무에서 반복 비용을 줄이는가”를 먼저 본다.

이 레포를 한 줄로 보면

PageAgent는 브라우저 확장이나 별도 헤드리스 환경 없이, 웹페이지 안에서 바로 자연어로 GUI를 제어하게 만드는 인페이지 에이전트다. 쉽게 말해 “웹앱 안에 AI 조작 레이어를 심는” 쪽에 가깝다.

왜 지금 이 레포가 뜨는가

많은 자동화 도구가 브라우저 바깥에서 움직인다면, PageAgent는 페이지 안으로 들어간다. 백엔드 대수술 없이 제품 안에 AI 코파일럿을 얹고 싶어 하는 SaaS 팀에게 아주 매력적인 그림이다. 게다가 멀티모달 스크린샷 의존 대신 텍스트 기반 DOM 조작을 강조하는 것도 차별점이다.

레포 안에서 먼저 볼 것

• 인페이지 JavaScript 방식이라 통합이 가볍다
• 텍스트 기반 DOM 조작으로 스크린샷 의존도를 낮춘다
• 옵션으로 Chrome 확장과 MCP Server까지 제공해 멀티페이지 작업도 확장 가능하다

설치 전에 확인할 것

• 프론트엔드 코드에 스크립트 또는 npm 패키지를 붙일 수 있는 환경
• 사용할 LLM API Key와 baseURL
• 처음 실험할 단일 페이지 하나

설치 방법

공식 확인 링크

• GitHub README: https://github.com/alibaba/page-agent
• 공식 문서: https://alibaba.github.io/page-agent/docs/introduction/overview
• 데모: https://alibaba.github.io/page-agent/
• Chrome extension 문서: https://alibaba.github.io/page-agent/docs/features/chrome-extension

가장 빠른 실험: Demo CDN

README 기준 가장 빠른 시작은 페이지에 demo script를 붙이는 것이다.

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.6.1/dist/iife/page-agent.demo.js" crossorigin="true"></script>

중국 미러가 필요하면 npmmirror 주소를 쓸 수 있다. 단, 이 경로는 무료 테스트 LLM API를 쓰는 기술 평가용이므로 프로덕션 기본값으로 보긴 어렵다.

정식 설치: npm

npm install page-agent

그다음 코드에서 불러온다.

import { PageAgent } from 'page-agent'
 
const agent = new PageAgent({
  model: 'qwen3.5-plus',
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'en-US',
})

언어는 실제 서비스 언어에 맞춰 조정하면 된다.

설치 확인

• 데모 페이지 또는 로컬 페이지에서 PageAgent 인스턴스가 생성되는지 확인한다.
• API Key 오류 없이 첫 명령이 서버로 전달되는지 콘솔에서 본다.

사용 방법

1. 초기에는 한 페이지에서만 버튼 클릭, 입력창 채우기처럼 단순한 명령을 테스트한다.
2. 예를 들어 Click the login button 같은 명령으로 시작한다.
3. 명령 안정성이 확보되면 폼 채우기나 설정 토글처럼 조금 더 긴 작업으로 확장한다.
4. 멀티페이지 이동이 필요할 때만 Chrome extension이나 MCP Server를 검토한다.

공식 README의 가장 짧은 예시는 아래다.

await agent.execute('Click the login button')

이 한 줄이 먹히면 그다음부터는 폼 필링, 메뉴 이동, 접근성 보조 같은 시나리오로 넓히면 된다. 핵심은 처음부터 20클릭짜리 복합 작업을 시키지 않는 것이다.

어디에 바로 써먹을 수 있나

사례 A. 사내 ERP 폼 자동화

반복 입력이 많은 백오피스 페이지라면 “거래처 등록하고 결제조건 선택해” 같은 자연어 명령을 붙이는 실험이 가능하다. 이때 핵심은 사람을 완전히 빼는 게 아니라, 반복 클릭을 줄이는 보조 레이어로 시작하는 것이다.

사례 B. 제품 내 AI 코파일럿

고객이 복잡한 설정 페이지에서 길을 잃는 제품이라면 PageAgent로 “이 기능 켜줘” 같은 내비게이션형 도우미를 만들 수 있다. 접근성 보조나 음성 명령 연동에도 잘 어울린다.

처음 해볼 최소 실험

1. 단일 페이지를 하나 고른다.
2. CDN 또는 npm 중 더 빠른 경로로 붙인다.
3. Click the login button 수준의 단순 명령 1~2개만 실행한다.
4. 오작동 요소를 기록한 뒤 DOM 구조를 정리하거나 프롬프트를 좁혀본다.

검증 포인트는 간단하다. 잘 되는지 볼 때는 데모 성공보다 실제 제품 페이지에서 오작동 없이 동일 명령을 얼마나 안정적으로 수행하는지 확인해야 한다.

볼 때 주의할 점

• 클라이언트사이드 개선용이지 서버 자동화 만능 도구는 아니다.
• 페이지 구조가 자주 바뀌면 명령 안정성이 떨어질 수 있다.
• 무료 테스트 LLM API는 기술 평가용이라는 점을 명확히 봐야 한다.

다음 읽기

• 🔥 05. Lightpanda
• 🔥 06. Impeccable
• 🔥 Git Trend 허브

이 글은 AI를 활용해 초안을 정리했고, GitHub README와 공식 링크를 다시 확인해 실무 적용 관점으로 풀어썼다.