저는 최근 6개월간 Stagehand 기반의 브라우저 자동화 시스템을 운영하면서, 단순한 Playwright 스크립트에서 출발해 완전한 AI 기반 셀프힐링(self-healing) 자동화 파이프라인까지 진화시켰습니다. 이 글에서는 Stagehand의 액션 추상화 레이어와 DeepSeek V3.2를 결합해 안정적이면서도 비용 효율적인 브라우저 자동화 시스템을 구축하는 전 과정을 공유합니다. 모든 모델 호출은 HolySheep AI 게이트웨이를 통해 이루어지며, 단일 API 키로 GPT-4.1, Claude Sonnet 4.5, Gemini 2.5 Flash, DeepSeek V3.2를 자유롭게 라우팅할 수 있습니다.

아키텍처: 왜 Stagehand인가

Stagehand는 Browserbase에서 만든 AI 네이티브 브라우저 자동화 프레임워크입니다. 기존 Playwright/Puppeteer의 셀렉터 기반 접근에서 벗어나 "click the login button" 같은 자연어 액션을 코드로 표현할 수 있게 해줍니다. 핵심 구조는 다음과 같습니다.

DeepSeek V3.2는 이 아키텍처에서 이상적인 모델입니다. 함수 호출(function calling) 정확도가 GPT-4.1 대비 약 92% 수준이지만, 입력 토큰 가격이 1/19 수준(0.42 USD/MTok 대 8 USD/MTok)입니다. 액션 추론처럼 짧고 빈번한 호출이 많은 워크로드에서 이 가격 차이는 누적 비용에 결정적인 영향을 줍니다.

환경 설정 및 HolySheep AI 연동

먼저 프로젝트를 초기화하고 Stagehand SDK를 설치합니다. Node.js 18 이상을 권장합니다.

# 프로젝트 초기화
mkdir stagehand-deepseek && cd stagehand-deepseek
npm init -y
npm install @browserbasehq/stagehand playwright zod p-limit
npx playwright install chromium


환경 변수 파일 생성

cat > .env << 'EOF'
HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY
HOLYSHEEP_BASE_URL=https://api.holysheep.ai/v1
STAGEHAND_MODEL=deepseek-chat
EOF

Stagehand는 기본적으로 OpenAI 호환 클라이언트를 사용하므로, base URL만 HolySheep 게이트웨이로 바꾸면 DeepSeek V3.2가 그대로 동작합니다. 이 부분이 HolySheep의 가장 큰 장점입니다. 별도의 어댑터 코드 없이 표준 OpenAI 호환 인터페이스를 그대로 재사용할 수 있습니다.

// src/config.ts
import { Stagehand } from "@browserbasehq/stagehand";
import { config } from "dotenv";
config();

export const stagehandConfig = {
  env: "LOCAL" as const,
  headless: true,
  verbose: 1,
  // LLM 설정: HolySheep 게이트웨이를 통한 DeepSeek V3.2
  modelName: process.env.STAGEHAND_MODEL ?? "deepseek-chat",
  modelClientOptions: {
    apiKey: process.env.HOLYSHEEP_API_KEY,
    baseURL: process.env.HOLYSHEEP_BASE_URL, // https://api.holysheep.ai/v1
  },
  // Chromium 실행 옵션: 컨테이너 환경 대응을 위한 샌드박스 비활성화
  localBrowserLaunchOptions: {
    chromiumSandbox: false,
    args: ["--disable-dev-shm-usage", "--no-sandbox", "--disable-gpu"],
  },
};

export async function createStagehand(): Promise<Stagehand> {
  return new Stagehand(stagehandConfig);
}

핵심 구현: AI 기반 액션 실행 패턴

제가 실전에서 사용하는 패턴은 "계획(plan) - 실행(act) - 검증(observe)" 3단계 루프입니다. 단일 액션 호출은 비효율적이므로, 한 번의 LLM 호출로 여러 액션을 묶어 처리합니다.

// src/automation.ts
import { z } from "zod";
import { createStagehand } from "./config";

// 작업 추출 스키마: LLM이 페이지에서 무엇을 해야 하는지 구조화
const ActionPlanSchema = z.object({
  goal: z.string().describe("이번 액션 시퀀스의 상위 목표"),
  steps: z.array(
    z.object({
      action: z.enum(["click", "type", "extract", "navigate", "wait"]),
      selector: z.string().optional(),
      text: z.string().optional(),
      rationale: z.string().describe("왜 이 액션을 선택했는지"),
    })
  ).min(1).max(8),
});

export async function runAutomationFlow(url: string, goal: string) {
  const stagehand = await createStagehand();
  const page = stagehand.page;

  try {
    await page.goto(url, { waitUntil: "domcontentloaded" });

    // 1단계: 페이지 관찰 후 액션 계획 수립 (단일 LLM 호출)
    const plan = await stagehand.extract(
      현재 페이지에서 목표 [${goal}]를 달성하기 위한 최적의 액션 시퀀스를 JSON으로 반환하라,
      ActionPlanSchema
    );

    console.log(계획: ${plan.goal});
    for (const step of plan.steps) {
      console.log(  - ${step.action}: ${step.rationale});

      switch (step.action) {
        case "click":
          await stagehand.act(클릭: ${step.selector});
          break;
        case "type":
          await stagehand.act(입력 필드 [${step.selector}]에 "${step.text}" 타이핑);
          break;
        case "navigate":
          await page.goto(step.selector!, { waitUntil: "networkidle" });
          break;
        case "wait":
          await page.waitForTimeout(parseInt(step.text ?? "1000"));
          break;
      }
    }

    // 2단계: 결과 검증
    const result = await stagehand.extract(
      "현재 페이지에서 목표 달성 여부와 추출할 데이터를 JSON으로 반환",
      z.object({
        success: z.boolean(),
        data: z.record(z.string()),
      })
    );

    return result;
  } finally {
    await stagehand.close();
  }
}

이 패턴의 핵심은 "plan.steps 배열 최대 8개" 제약입니다. Stagehand 내부적으로 한 번의 observe() 호출이 페이지당 평균 2,500 토큰을 소비하는데, 8단계로 묶으면 토큰당 처리 액션 수가 약 5.7배 증가합니다. 실제 측정 결과, 단일 액션 호출 대비 종단간 지연 시간이 38% 단축됐습니다.

동시성 제어와 비용 최적화

프로덕션 환경에서는 여러 자동화 작업을 병렬로 실행해야 합니다. 하지만 Chromium 인스턴스당 메모리 사용량이 약 280MB이므로 무제한 병렬화는 불가능합니다. 저는 다음과 같은 워커 풀 패턴을 사용합니다.

// src/worker-pool.ts
import pLimit from "p-limit";
import { runAutomationFlow } from "./automation";

interface Job {
  url: string;
  goal: string;
  onResult: (result: unknown) => void;
}

export class AutomationPool {
  // CPU 코어당 2개의 브라우저 컨텍스트가 안전한 최대치
  private limiter = pLimit(Math.max(2, Math.floor(require("os").cpus().length * 2)));
  private metrics = { jobs: 0, totalMs: 0, estCostUsd: 0 };

  async submit(job: Job) {
    return this.limiter(async () => {
      const start = Date.now();
      const result = await runAutomationFlow(job.url, job.goal);
      const elapsed = Date.now() - start;

      // 비용 추적: DeepSeek V3.2 = 0.42 USD/MTok (입출력 동일가)
      this.metrics.jobs += 1;
      this.metrics.totalMs += elapsed;
      this.metrics.estCostUsd += this.estimateCost();
      console.log(작업 완료: ${elapsed}ms, 누적 비용 추정: $${this.metrics.estCostUsd.toFixed(4)});

      job.onResult(result);
      return result;
    });
  }

  // 비용 추정: 평균 작업당 약 428,000 토큰 소비 (실측)
  estimateCost(avgTokensPerJob = 428_000) {
    return (avgTokensPerJob / 1_000_000) * 0.42;
  }

  getStats() {
    return {
      ...this.metrics,
      avgLatencyMs: this.metrics.jobs > 0 ? this.metrics.totalMs / this.metrics.jobs : 0,
    };
  }
}

// 사용 예: 100개 URL을 병렬 처리
const pool = new AutomationPool();
const urls = Array.from({ length: 100 }, (_, i) => ({
  url: https://example.com/page/${i},
  goal: "가격 및 재고 정보 추출",
  onResult: (r) => console.log("결과:", r),
}));

await Promise.all(urls.map((u) => pool.submit(u)));
console.log("최종 통계:", pool.getStats());

벤치마크: 실측 데이터

제가 동일 작업(상품 페이지에서 가격, 재고, 리뷰 추출)을 100회 실행해 측정한 모델별 비교 데이터입니다. 모든 호출은 HolySheep AI 게이트웨이를 경유했습니다.

DeepSeek V3.2는 Gemini 2.5 Flash보다 약간 느리지만 비용은 1/3 수준이고, GPT-4.1 대비 비용은 1/13입니다. 성공률 94%는 셀프힐링 재시도 로직을 추가하면 98%까지 끌어올릴 수 있어, 대부분의 프로덕션 워크로드에서 DeepSeek V3.2가 최적의 선택입니다. 단, 페이지 구조가 복잡하거나 다단계 추론이 필요한 경우(예: 결제 플로우 자동화)는 Claude Sonnet 4.5

관련 리소스