실제로 작동하는 Claude 브라우저 에이전트를 구축한 방법 (스타터 키트 포함)

대부분의 브라우저 자동화(browser automation) 튜토리얼은 당신에게 거짓말을 하고 있습니다.

그들은 버튼을 클릭하고 양식을 채우는 깔끔한 20줄짜리 스크립트를 보여줍니다. 하지만 사이트가 shadow DOM을 로드하거나, 버튼이 cross-origin iframe 내부에 있거나, CAPTCHA가 흐름 중간에 당신을 가로막을 때 어떤 일이 발생하는지는 보여주지 않습니다. 또한, 당신의 에이전트가 눈치채기도 전에 조용히 루프를 돌며 API 호출로 200달러를 태워버리는 새벽 3시의 상황은 확실히 보여주지 않습니다.

저는 실제 환경에서도 살아남을 수 있는 Claude 기반의 브라우저 에이전트를 구축하기 위해 몇 주를 보냈습니다. 제가 배운 것들, 그리고 차이를 만들어낸 세 가지 요소를 소개합니다.

1. CDP 직접 제어 > Playwright 추상화 (에이전트 제어용)

Playwright와 Puppeteer는 스크립트 기반 자동화에는 훌륭합니다. 하지만 AI 기반 에이전트에는 최악입니다.

문제는 이렇습니다: Claude가 화면에 보이는 것을 바탕으로 다음에 무엇을 할지 결정할 때, 당신에게는 DOM 덤프나 스크린샷이 아니라 가공되지 않은 접근성 트리(accessibility tree) 데이터가 필요합니다. Chrome DevTools Protocol (CDP)는 에이전트가 읽을 수 있는 요소 UID와 직접 매핑되는 구조화된 형식으로 a11y 트리 스냅샷을 제공합니다. 당신이 Claude에게 "제출 버튼을 클릭해"라고 요청하면, Claude는 CSS 선택자를 추측하는 대신 스냅샷에서 정확한 요소를 식별할 수 있습니다.

저의 설정:

// innerHTML을 덤프하는 대신 구조화된 a11y 스냅샷을 가져옵니다
const { nodes } = await cdp.send('Accessibility.getFullAXTree');
// 요소 UID가 첨부된 nodes를 Claude에게 전달합니다
...

이것이 대부분의 튜토리얼이 건너뛰는 기본 골격입니다. 이것 없이는 당신의 에이전트는 눈을 감고 항해하는 것과 같습니다.

2. 프롬프트 캐싱(Prompt Caching)은 비용을 90% 절감합니다 — 첫날부터 적용하세요

모든 에이전트 루프는 동일한 시스템 프롬프트를 다시 보냅니다. 만약 한 세션에서 50번의 브라우저 동작을 실행한다면, 당신은 50번의 전체 시스템 프롬프트 입력 비용을 지불하고 있는 것입니다. Claude의 네이티브 프롬프트 캐싱(prompt caching)을 사용하면, 시스템 컨텍스트를 캐싱 가능하도록 표시할 수 있고 API는 이를 재사용합니다.

실제로 이는 입력 토큰 비용을 약 90% 절감하고, 반복 호출 시 지연 시간(latency)을 약 80% 줄여줍니다. 긴 브라우저 세션의 경우, 이는 0.50달러짜리 작업과 5달러짜리 작업의 차이를 만듭니다.

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  system: [
...

다른 무엇보다도 이 작업을 가장 먼저 수행하십시오. 이는 당신이 수행하는 모든 에이전트 호출에 걸쳐 복리로 적용됩니다.

3. 엄격한 종료 조건(Hard Termination Conditions)은 타협 불가능합니다

이것은 사람들이 가장 뼈아프게 겪는 문제입니다. 피드백 루프(feedback loop)에 빠진 통제되지 않는 에이전트는 4시간 만에 API 비용으로 5,000달러를 태워버릴 수 있습니다. 이는 이미 문서화되어 있으며, 실제 운영 환경(production)에서 발생하고 있는 일입니다. 처음부터 종료 조건(exit conditions)을 구축하지 않는다면 당신에게도 일어날 일입니다.

효과적인 패턴은 다음과 같습니다: 루프 카운터(loop counter), 에이전트가 동일한 페이지에서 순환하고 있는지 감지하기 위한 상태 해시(state hash), 그리고 액션 유형별 최대 재시도 게이트(max-retry gate)입니다.

const MAX_LOOPS = 25;
const MAX_RETRIES_PER_ACTION = 3;
let loopCount = 0;
...

이를 엄격한 타임아웃(hard timeout, 저는 복잡한 흐름의 경우 900초를 사용합니다)과 결합하면 피해 범위(blast radius)를 제한할 수 있습니다.

스타터 키트에 담은 내용

에이전트가 읽을 수 있는 컨텍스트를 위한 CDP a11y 스냅샷, 첫 호출부터 적용되는 프롬프트 캐싱(prompt caching), 그리고 엄격한 종료 게이트(termination gates)라는 이 세 가지 패턴은 모든 브라우저 에이전트에 필요한 핵심 골격(scaffolding)이지만, 거의 어떤 튜토리얼에서도 다루지 않는 내용입니다.

저는 이 전체 작동 설정을 스타터 키트로 패키징했습니다: https://knightops.gumroad.com/l/claude-browser-agent-starter-kit

이 키트에는 전체 에이전트 루프, CDP 스냅샷 포매터(formatter), 캐싱 레이어(caching layer), 그리고 종료 로직(termination logic)이 포함되어 있어 여러분의 프로젝트에 바로 적용할 수 있습니다. 브라우저 자동화(browser automation)와 씨름해 왔고 실제 운영 환경에서 제대로 작동하는 골격이 필요하다면, 이것이 가장 빠른 길입니다.

Claude 에이전트로 무언가를 구축하고 있다면 댓글을 남겨주세요. 무엇이 잘 작동하고 있는지에 대해 언제든 의견을 나누고 싶습니다.