Webwright
"터미널 하나면 충분한 웹 에이전트"

Microsoft가 공개한 1,500줄짜리 미니멀 웹 에이전트 하네스. Online-Mind2Web 86.7%, Odysseys 60.1%로 오픈소스 최고 성능을 기록했다. 어떻게 이게 가능했는지, 코드 한 줄까지 파고든다.

1프로젝트 한 줄 요약

결국 무엇인가?

한 줄로 줄이면 — Webwright는 "사람 엔지니어가 브라우저 자동화 스크립트를 짤 때처럼" LLM이 일하게 만드는 가장 작은 단위의 하네스다. 그 이상도 이하도 아니다. 멀티 에이전트도, 그래프 엔진도, 플러그인 레이어도, 숨겨진 오케스트레이션도 없다. 그냥 터미널, 브라우저, 모델 세 개뿐.

2왜 주목받는가

트렌딩 이유와 경쟁 제품 대비 장점.

2026년 5월 기준 GitHub 별은 13개로 적지만, TrendShift 상위에 오른 이유는 벤치마크 수치와 Microsoft 출시라는 시그널 두 가지다. AutoGen·Magentic-One 같은 거대 프레임워크를 만든 같은 회사가, 정반대 철학으로 "1,500줄이면 충분하다"고 선언한 셈이다.

경쟁 제품과 비교

벤치마크 수치 정리:

3기술 스택 전체 지도

백엔드·자동화 환경·도구까지 한 장으로.

pyproject.toml을 직접 까서 보면 의존성이 놀랍도록 짧다. 그래서 한눈에 그릴 수 있다.

코어 의존성 (전부 9개)

구조적 레이어 정리

인프라 / 통합

외부 인프라는 거의 없다. 선택사항으로 Browserbase(브라우저 클라우드)에 연결할 수 있고, 모델 API 키만 cred.sh에 export하면 끝. 도커도, 쿠버네티스도, 메시지 큐도 없다. 1인 개발자 PC에서 그대로 돌아간다.

4아키텍처 심화 분석

루프의 한 사이클을 코드 레벨로 해부한다.

핵심을 한 그림으로:

┌──────────────────────────────────────────────────────────────┐
│              Webwright Agent Loop (한 스텝)                  │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐    1) query(messages)                         │
│   │ messages │ ──────────────────────────┐                   │
│   │  list    │                           │                   │
│   └──────────┘                           ▼                   │
│        ▲                          ┌──────────────┐           │
│        │                          │  Model       │           │
│        │ 5) add_messages(...)     │ (OpenAI /    │           │
│        │                          │  Anthropic / │           │
│        │                          │  OpenRouter) │           │
│        │                          └──────┬───────┘           │
│        │                                 │                   │
│        │                                 │ 2) JSON 응답      │
│        │                                 ▼                   │
│        │                       {                             │
│        │                         "thought": "...",           │
│        │                         "bash_command": "...",      │
│        │                         "done": false,              │
│        │                         "final_response": ""        │
│        │                       }                             │
│        │                                 │                   │
│        │                                 │ 3) execute        │
│        │                                 ▼                   │
│        │                    ┌────────────────────────┐       │
│        │                    │  Environment           │       │
│        │                    │ (local_workspace)      │       │
│        │                    │                        │       │
│        │                    │  subprocess.run(bash)  │       │
│        │                    │       │                │       │
│        │                    │       ▼                │       │
│        │                    │  ┌──────────────┐      │       │
│        │                    │  │ Playwright   │      │       │
│        │                    │  │ heredoc      │      │       │
│        │                    │  │   browser    │      │       │
│        │                    │  │   page       │      │       │
│        │                    │  │   screenshot │      │       │
│        │                    │  └──────────────┘      │       │
│        │                    └──────────┬─────────────┘       │
│        │                               │                     │
│        │                               │ 4) Observation:     │
│        │                               │    stdout/stderr/   │
│        │                               │    returncode       │
│        └───────────────────────────────┘                     │
│                                                              │
│   ⇣ 반복 (step_limit=100 까지)                              │
│   ⇣ summary_every_n_steps=20 마다 자동 컨텍스트 압축         │
│   ⇣ done=true 가 들어오면 self_reflection 게이트 통과 후 종료│
│                                                              │
└──────────────────────────────────────────────────────────────┘

핵심 설계 패턴 4가지

5디렉토리 구조 해부

레포에 뭐가 어디 있는지.

Webwright/
├── pyproject.toml                # 패키지 메타 + 9개 의존성
├── README.md                     # 18KB, 자세한 설명
├── .claude-plugin/               # Claude Code 플러그인 메타
├── .codex-plugin/                # Codex(OpenAI 에이전트) 플러그인 메타
│
├── assets/
│   ├── webwright_logo.svg
│   ├── demo.mp4                  # 5.5MB 데모 영상
│   ├── om2w_autoeval_step100.png # Online-Mind2Web 결과 그래프
│   ├── odysseys_eval_step100.png # Odysseys 결과 그래프
│   └── task_showcase/            # 6개 실제 태스크 사례 (gallery)
│       ├── app.py                # Flask 갤러리 앱
│       ├── tasks/
│       │   ├── austin_apartments/{task.json, report.json}
│       │   ├── driving_weather/...
│       │   ├── nz_au_legal_jobs/...
│       │   ├── ophelia_pittsburgh/...
│       │   ├── pokemon_tcg/...
│       │   └── slickdeals/...
│       └── templates/{dashboard.html, task.html}
│
├── skills/webwright/             # Claude Code 스킬로 패키징된 버전
│   ├── SKILL.md                  # description + workflow
│   ├── commands/
│   │   ├── run.md                # /webwright:run 슬래시 커맨드
│   │   └── craft.md              # /webwright:craft (CLI 도구 생성)
│   └── reference/
│       ├── workflow.md           # plan→explore→final→verify 흐름
│       ├── playwright_patterns.md# heredoc 패턴, ARIA 스냅샷 레시피
│       └── cli_tool_mode.md      # 재사용 가능한 CLI 생성 규약
│
├── src/webwright/                # 실제 패키지 본체
│   ├── __init__.py
│   ├── exceptions.py             # FormatError, InterruptAgentFlow, LimitsExceeded
│   │
│   ├── agents/
│   │   └── default.py            # ~450줄, DefaultAgent 본체 ★
│   │
│   ├── environments/
│   │   ├── local_workspace.py    # Bash 실행 환경
│   │   └── local_browser.py      # Playwright 환경
│   │
│   ├── models/
│   │   ├── base.py               # Model 추상 클래스
│   │   ├── openai_model.py       # GPT-5.4 등 OpenAI 백엔드
│   │   ├── anthropic_model.py    # Claude Opus 4.7 등
│   │   └── openrouter_model.py   # OpenRouter 통합 백엔드
│   │
│   ├── tools/
│   │   ├── image_qa.py           # 스크린샷 질의응답
│   │   ├── self_reflection.py    # 최종 성공 판정
│   │   └── persistent_local_browser.py
│   │
│   ├── config/
│   │   ├── base.yaml             # 공통 설정 (system_template 포함!) ★
│   │   ├── model_openai.yaml     # OpenAI 오버레이
│   │   ├── model_claude.yaml     # Anthropic 오버레이
│   │   ├── model_openrouter.yaml
│   │   ├── local_browser.yaml
│   │   ├── persistent_browser.yaml
│   │   ├── crafted_cli.yaml
│   │   └── task_showcase.yaml
│   │
│   ├── run/
│   │   ├── cli.py                # webwright CLI 엔트리포인트
│   │   └── run_command.sh
│   │
│   └── utils/
│       ├── logging.py
│       ├── runtime.py
│       └── serialize.py          # recursive_merge 등
│
└── tests/
    ├── conftest.py
    └── unit/
        ├── test_doctor.py
        └── test_tool_model_routing.py

주목할 위치:

6학습 포인트

이 레포에서 무엇을 배울 수 있는가.

① Playwright async + heredoc 패턴

Webwright의 모든 브라우저 동작은 bash 한 줄 안에 들어가는 Python 스크립트다. 이 패턴은 LLM이 텍스트 한 덩어리만 출력할 때 매우 유용하다.

python - <<'PY'
import asyncio
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        ctx = await browser.new_context(viewport={"width": 1280, "height": 1800})
        page = await ctx.new_page()
        await page.goto("https://www.google.com/flights")
        await page.get_by_role("button", name="Search").click()
        snapshot = await page.locator("body").aria_snapshot()
        print(snapshot)
        await browser.close()

asyncio.run(main())
PY

여기서 핵심은 get_by_role() + aria_snapshot() 조합. CSS 셀렉터(div.btn-primary:nth-child(3))는 사이트가 바뀌면 깨지지만, ARIA role/name은 접근성 표준이라 안정적이다.

② JSON schema-enforced LLM 응답

system_template이 명령한다 — "응답은 strict JSON 객체 하나. 마크다운 금지, 코드 펜스 금지". 이건 LLM에게 매우 익숙하지 않은 제약인데, Webwright는 그걸 강하게 밀어붙인다. 결과적으로 모든 응답을 json.loads() 한 번으로 파싱 가능.

③ recursive_merge로 YAML 스택 합치기

-c base.yaml -c model_claude.yaml -c persistent_browser.yaml처럼 여러 YAML을 깊이 병합해서 최종 설정을 만든다. utils/serialize.py의 recursive_merge가 핵심. dict이면 키별로 재귀적 병합, list이면 덮어쓰기, UNSET sentinel로 "이 값은 안 건드림"을 표현.

④ 컨텍스트 압축 (history compaction)

매 20스텝(설정값)마다 자동으로 트리거되는 _compact_history(). 시스템 메시지를 보존한 채, 그 외 모든 메시지를 LLM에게 "요약해라"고 시켜서 한 줄 user 메시지로 치환한다. 100스텝짜리 long-horizon에서 토큰 폭발을 막는 트릭.

# default.py 의 _compact_history()
summary_request = self.model.format_message(
    role="user",
    content=self.config.summary_user_prompt,
)
response = self.model.query(self.messages + [summary_request])
self.messages = [system_message, summary_message]  # 압축!

⑤ 멀티 모델 백엔드 추상화

models/base.py의 Model 추상 클래스는 4개 메서드만 요구한다 — query(), format_message(), format_observation_messages(), get_template_vars(). 새 백엔드 추가는 이걸 구현하면 끝. OpenAI든, Gemini든, 자체 호스팅 vLLM이든.

⑥ 자기검증(self-verification) 아키텍처

이게 Webwright의 진짜 비밀 무기다. 모델은 plan.md(critical points 체크리스트)를 먼저 만들고, 그 다음 final_script.py를 작성하고, 실행 후 self_reflection이 "각 critical point에 대응되는 스크린샷이 정말 그 조건을 만족하는가?"를 2-stage로 검증한다.

실제 self_reflection 프롬프트는 모델에게 "엄격한 평가자" 역할을 부여한다. 응답 마지막 라인이 정확히 Status: success 또는 Status: failure여야 하고, 그게 아니면 자동으로 failure.

실습 아이디어

7하드웨어/시스템 요구사항

실제로 돌리려면 뭐가 필요한가.

8직접 해볼 수 있는 실습 과제

난이도별 5단계.

9관련 기술 심화 학습 로드맵

4주 코스로 정리.

10핵심 키워드 사전

한 번 더 정리.

11참고 링크

더 깊이 파고들 자료.