이 블로그 게시물에서 배울 내용:
- Stagehand가 무엇이며 브라우저 자동화를 위해 무엇을 제공하는지.
- Bright Data의 Browser API가 제공하는 클라우드 기반 스텔스 브라우저 세션과 함께 Stagehand를 사용하는 이점.
- Stagehand에서 Browser API를 설정하는 단계별 가이드.
바로 시작해 봅시다!
Stagehand란 무엇인가?
Stagehand는 Browserbase가 개발한 오픈 소스 브라우저 자동화 프레임워크입니다. 자연어 AI와 결정론적 코드를 결합하며, 각 접근 방식을 언제 사용할지 선택할 수 있게 하여 취약한 셀렉터 기반 도구(예: Playwright)와 예측 불가능한 AI 에이전트 사이의 트레이드오프를 해결합니다.
기본 LLM과 제어된 실행 레이어를 사용하여 명령을 브라우저 동작과 구조화된 출력으로 변환하는 방식으로 작동합니다. Stagehand는 브라우저 기반 AI 에이전트 개발도 지원합니다.
또한 AI 웹 스크래핑 도구로 작동하는 기능도 갖추고 있습니다. Stagehand는 GitHub에서 22,900개 이상의 스타와 npm에서 주간 100만 회 이상의 다운로드를 기록하며 대규모 개발자 커뮤니티의 지원을 받고 있습니다.
Stagehand 기능
Stagehand가 제공하는 주요 기능은 다음과 같습니다:
act()실행: 일반 영어 프롬프트를 사용하여 클릭, 스크롤, 양식 작성과 같은 브라우저 작업을 수행합니다.extract()구조화된 데이터: 안정적인 다운스트림 사용을 위해 엄격한 Zod 검증 스키마로 페이지 콘텐츠를 추출합니다.observe()페이지 인식: 작업 실행 전 페이지의 실행 가능한 요소를 감지하여 안전성과 정밀도를 향상시킵니다.agent()자율 워크플로우: 최소한의 감독으로 다단계 브라우저 작업을 엔드투엔드로 실행합니다.- 자가 치유 자동화: UI 변경에 적응하여 취약한 셀렉터 기반 오류를 줄입니다.
- 액션 캐싱: 액션을 캐싱하여 중복 LLM 호출을 방지하고, 여러 실행에 걸쳐 높은 예측 가능성과 비용 효율적인 실행을 보장합니다.
- LLM 유연성: 실행을 결정론적이고 디버깅 가능하게 유지하면서 여러 제공업체와 함께 작동합니다.
- 조합 가능한 프리미티브: act, extract, observe, agent를 결합하여 맞춤형 자동화 파이프라인을 구축합니다.
- 개발자 중심 도구: 유지 관리성, 재현성, 현대 AI 시스템 통합을 위해 설계되었습니다.
공식 문서에서 자세한 내용을 확인하세요.
Stagehand와 Bright Data의 Browser API를 함께 사용하는 이유
Stagehand와 같은 브라우저 자동화 도구는 동일한 핵심 문제에 직면합니다:
- 웹사이트는 봇 탐지 시스템, CAPTCHA, 핑거프린팅, IP 평판 검사를 사용하여 자동화된 트래픽을 적극적으로 차단합니다. 이로 인해 테스트에서는 작동하지만 프로덕션에서 예측 불가능하게 실패할 수 있어 자동화가 불안정해집니다.
- 로컬 또는 자체 관리 인프라에서 많은 브라우저 인스턴스를 실행하는 것은 리소스 집약적입니다. 브라우저는 상당한 CPU와 메모리를 필요로 하므로, 동시에 많은 인스턴스를 실행하는 것은 비용이 많이 들고 안정적으로 확장하기 어렵습니다.
- 프록시 및 지역 분산 관리는 운영 오버헤드를 추가합니다. 시간이 지남에 따라 이 복잡성은 프로덕션 수준의 스크래핑 또는 AI 에이전트 워크로드에서 유지하기 어려워집니다.
Bright Data의 Browser API는 로컬 브라우저 실행을 확장성과 스텔스를 위해 엔지니어링된 완전 관리형 클라우드 기반 인프라로 전환하여 이러한 문제를 해결합니다.
브라우저를 로컬에서 처리하는 대신 단일 CDP 엔드포인트를 통해 연결할 수 있습니다. 내장된 프록시 로테이션, CAPTCHA 해결, 고급 핑거프린팅 회피 기능을 갖춘 원격의 사전 구성된 브라우저에 액세스할 수 있습니다.
Bright Data가 돋보이는 것은 4억 개 이상의 주거용 IP로 구성된 프록시 네트워크를 기반으로 한 엔터프라이즈급 아키텍처입니다. 이를 통해 높은 익명성, 글로벌 지역 타겟팅, 무한한 동시성을 구현하면서 99.95%의 성공률과 SLA 기반 99.99%의 가동 시간을 제공합니다.
Stagehand와 Browser API 통합 방법
이 챕터에서는 Stagehand를 사용하여 원격 브라우저 인스턴스를 자동화하는 방법을 살펴봅니다. 구체적으로 Bright Data의 Browser API를 통해 스텔스, 안티 감지, 무한 확장 가능한 클라우드 브라우저 세션에 연결합니다.
아래 지침을 따르세요.
사전 요구 사항
이 튜토리얼 섹션을 따라하려면 다음이 필요합니다:
- Node.js 20+ 로컬 설치 (Node.js 22+ 권장).
- 지원되는 Stagehand AI 제공업체의 API 키 (여기서는 OpenAI API 키를 사용합니다).
- Bright Data 계정.
- Stagehand API 및 AI 기반 브라우저 자동화 기능에 대한 기본 지식.
Step #1: Stagehand 프로젝트 초기화
빠른 시작 가이드를 따라 새 Stagehand 프로젝트를 설정하거나, 아래 명령어를 실행하세요:
npx create-browser-app bright-data-stagehand-examplenpx create-browser-app 명령어는 bright-data-stagehand-example 디렉토리에 새 Stagehand 프로젝트를 생성합니다.
실행 후 다음과 같은 결과가 나타납니다:
다음으로 프로젝트 디렉토리로 이동합니다:
cd bright-data-stagehand-example프로젝트 구조는 다음과 같습니다:
bright-data-stagehand-example/
├── .cursorrules
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.json생성된 파일을 잠시 살펴보고 프로젝트 구조에 익숙해지세요. Stagehand 메인 파일인 index.ts에 집중하세요.
이제 index.ts 파일을 다음만 남기고 정리하세요:
import { Stagehand } from "@browserbasehq/stagehand";곧 Stagehand를 Bright Data의 Browser API에 연결하는 방법을 살펴보겠습니다. 잘 하셨습니다!
Step #2: 환경 변수 읽기 구성
Stagehand 클라우드 자동화 프로젝트는 몇 가지 시크릿(예: AI 제공업체 API 키, Bright Data Browser API 자격 증명 등)에 의존합니다. 코드에 하드코딩하는 대신, 환경 변수에서 로드하는 것이 모범 사례입니다.
기본적으로 Stagehand는 .env 파일을 자동으로 로드하지 않습니다. 이를 활성화하려면 먼저 `dotenv 패키지를 설치하세요:
npm install dotenv다음으로 index.ts에 다음을 추가합니다:
import dotenv from "dotenv";
dotenv.config({
path: ".env",
});이제 .env 파일을 정의해야 합니다. npx create-browser-app을 실행할 때 생성된 .env.example 파일을 복사하거나, Stagehand 프로젝트에 수동으로 .env 파일을 추가하세요:
bright-data-stagehand-example/
├── .cursorrules
├── .env # <---------
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.jsonAI 제공업체 API 키(여기서는 OpenAI)로 .env 파일을 채웁니다:
OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"<YOUR_OPENAI_API_KEY> 플레이스홀더를 실제 OpenAI API 키로 교체하세요.
Stagehand는 런타임에 OPENAI_API_KEY 환경 변수를 자동으로 읽으므로 추가 구성이 필요하지 않습니다. 훌륭합니다!
Step #3: Bright Data Browser API 시작하기
이제 Bright Data Browser API의 CDP 기반 원격 연결 URL을 가져올 시간입니다.
아직 계정이 없다면 Bright Data 계정을 생성하세요. 이미 계정이 있다면 로그인하여 제어판에 접속하세요:
다음으로 왼쪽 메뉴에서 “Web Access > Web Access API” 옵션으로 이동합니다:
“My APIs” 테이블에 이미 Browser API 항목이 표시되어 있다면(아래와 같이 browser_api API를 통해), 바로 진행하면 됩니다:
그렇지 않다면 “Create API” 버튼의 드롭다운을 클릭하고 “Browser API”를 선택하세요:
그러면 Browser API 설정 마법사가 시작됩니다. Browser API에 이름(예: browser_api)을 지정하고 필요에 맞게 API를 구성하세요:
완료되면 “Add API” 버튼을 클릭하고 Browser API 세부 정보 페이지로 이동합니다:
여기서 CDP 기반 통합을 위한 연결 세부 정보(“Puppeteer / Playwright” 아래의 URL)를 찾을 수 있습니다. Browser API WebSocket URL은 다음 형식을 따릅니다:
wss://<BROWSER_API_USERNAME>:<BROWSER_API_USERNAME>@brd.superproxy.io:9222Browser API 페이지에서 Browser API 사용자 이름과 비밀번호를 복사하여 .env 파일에 추가합니다:
BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"나중에 index.ts에서 이 변수들을 사용하여 원격 CDP 연결 URL을 구성합니다.
이제 Bright Data Browser API를 통한 Stagehand 클라우드 브라우저 자동화에 필요한 모든 구성 요소가 준비되었습니다. 훌륭합니다!
Step #4: Stagehand에서 Bright Data Browser API에 연결
index.ts에서 환경 변수로부터 Browser API 자격 증명을 읽는 것부터 시작합니다:
const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";다음으로 CDP WebSocket URL을 통해 Bright Data Browser API에 연결하기 위해 main() 함수 내에서 Stagehand를 초기화합니다:
async function main() {
// configure Stagehand to connect remotely to Bright Data's Browser API
// and use an OpenAI model
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
},
model: "openai/gpt-5.4-mini",
});
// launch Stagehand and get the browser page
await stagehand.init();
const page = stagehand.context.pages()[0];
// browser automation logic...
// close the Stagehand instance and release the browser resources
await stagehand.close();
}
main().catch(console.error); 위 스니펫은 환경 변수에서 읽은 자격 증명으로 구성된 인증된 Browser API WSS URL을 사용하여 Stagehand를 구성합니다. 그런 다음 원격 브라우저 세션을 시작하고 자동화를 위한 페이지 객체를 노출합니다. 자동화 로직 실행 후 세션을 종료하고 모든 원격 브라우저 리소스를 해제합니다.
위 예제에서는 OpenAI GPT-5.4 Mini를 구성했습니다. 다른 OpenAI 모델이나 지원되는 AI 제공업체 설정도 작동합니다.
핵심 부분은 Stagehand 생성자에 있습니다. 원격 브라우저에 연결하기 위해 env를 "LOCAL"로 설정해야 하기 때문에 처음에는 구성이 약간 혼란스러울 수 있습니다. 그런 다음 localBrowserLaunchOptions 내에서 cdpUrl 필드를 통해 Bright Data Browser API WSS URL을 제공해야 합니다.
따라서 env가 "LOCAL"로 설정되어 있더라도 Stagehand는 실제로 Bright Data의 원격 안티 감지 클라우드 브라우저 인스턴스에 연결됩니다.
이제 간단한 예제로 통합을 테스트하여 모든 것이 올바르게 작동하는지 확인할 수 있습니다.
Step #5: Bright Data Browser API 통합 확인
Browser API와의 통합이 작동하는지 확인하려면 다음 자동화 로직을 시도해 보세요:
// connect to the example.com page
await page.goto("https://example.com");
// take the screenshot of the page
await page.screenshot({
path: "screenshot.png",
type: "png",
fullPage: false,
});이 코드는 원격 브라우저(Bright Data Browser API를 통해 노출됨)에 example.com을 열고 스크린샷을 캡처하도록 지시합니다.
모두 합쳐봅시다:
// index.ts
import { Stagehand } from "@browserbasehq/stagehand";
import dotenv from "dotenv";
// load the environment variables from the .env file
dotenv.config({
path: ".env",
});
// read the Bright Data Browser API credentials
const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";
async function main() {
// configure Stagehand to connect remotely to Bright Data's Browser API
// and use an OpenAI model
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
},
model: "openai/gpt-5.4-mini",
});
// launch Stagehand and get the browser page
await stagehand.init();
const page = stagehand.context.pages()[0];
// connect to the example.com page
await page.goto("https://example.com");
// take the screenshot of the page
await page.screenshot({
path: "screenshot.png",
type: "png",
fullPage: false,
});
// close the Stagehand instance and release the browser resources
await stagehand.close();
}
main().catch(console.error);다음 명령으로 스크립트를 실행합니다:
npm run start터미널에서 다음과 유사한 로그가 표시됩니다:
중요: 로그에 “connecting to local browser”가 표시될 수 있습니다. 이는 필수 env: "LOCAL" 구성 때문입니다. 그러나 실제 연결은 Bright Data의 원격 Browser API로 이루어집니다.
실행이 완료되면 프로젝트 디렉토리에 screenshot.png 파일이 나타납니다:
bright-data-stagehand-example/
├── .cursorrules
├── .env
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
├── screenshot.png # <---------
└── tsconfig.jsonscreenshot.png를 열면 렌더링된 example.com 페이지가 표시됩니다:
이는 Stagehand가 대상 사이트에 성공적으로 연결하고 예상대로 브라우저 자동화를 실행했음을 확인합니다.
Bright Data Browser API가 사용되었는지 확인하려면 Bright Data 대시보드를 확인하세요:
원격 CDP 연결을 통한 구성된 Browser API 세션의 활성 사용을 나타내는 트래픽 급증이 표시됩니다. 이는 모든 Stagehand 자동화가 Bright Data의 Browser API를 통해 올바르게 라우팅되고 있음을 확인합니다. 훌륭합니다!
Step #6: 실제 AI 기반 원격 브라우저 자동화 구현
이제 Yahoo Finance에서 뉴스 기사 데이터를 수집하기 위해 브라우저 로직을 자동화한다고 가정해 봅시다.
Yahoo Finance 홈페이지는 무한 스크롤을 사용하여 새 기사를 동적으로 로드하기 때문에 좋은 예시입니다. 또한 엄격한 안티봇 및 안티스크래핑 보호로 알려진 사이트입니다.
Browser API가 제공하는 스텔스 및 안티봇 우회 기능 덕분에 차단 없이 Stagehand를 통해 Yahoo Finance에 접근할 수 있습니다.
스크래핑된 데이터가 특정 구조를 따르도록 하기 위해 Zod로 출력 데이터 유형을 정의하는 것부터 시작합니다:
import { z } from "zod";
// ...
// structured output schema
const YahooFinanceNewsSchema = z.object({
news: z.array(
z.object({
title: z
.string()
.describe("The visible headline text of the news article"),
articleUrl: z
.string()
.describe("The full article URL"),
imageUrl: z
.string()
.describe("The full image URL"),
source: z
.string()
.optional()
.describe("The publisher name, such as Reuters or Yahoo Finance"),
timestamp: z
.string()
.optional()
.describe("The visible publication time, such as '4h ago'"),
marketMoves: z
.array(
z.object({
ticker: z
.string()
.describe("The stock ticker symbol, such as NVDA or ^GSPC"),
changePercent: z
.string()
.optional()
.describe(
"The visible market percentage change, such as '+2.4%' or '-0.69%'"
),
})
)
.optional()
.describe(
"List of stock tickers mentioned in the article footer with their change percentages"
),
})
),
});이는 스크래핑된 데이터의 예상 출력 구조를 정의합니다. 특히 Yahoo Finance 뉴스 카드에서 사용 가능한 정보와 일치합니다:
npx create-browser-app으로 Stagehand 앱을 초기화한 경우 zod를 수동으로 설치할 필요가 없습니다. 이미 프로젝트 의존성에 포함되어 있습니다. 그렇지 않다면 다음으로 설치하세요:
npm install zod 이제 다음으로 브라우징 및 추출 흐름을 자동화할 수 있습니다:
// automate the news article loading
await stagehand.act(
`Scroll down multiple times and wait for articles to load in the "More News" section. Repeat until at least 20 news articles are loaded.`,
{
timeout: 90000, // 90-second timeout
}
);
// scrape the news information
const data = await stagehand.extract(
`Scrape all visible news articles`,
YahooFinanceNewsSchema,
{
"timeout": 120000, // 120-second timeout
}
);이는 더 많은 기사를 로드하기 위해 페이지를 스크롤하는 실제 사용자의 동작을 AI 명령으로 구현합니다. 그런 다음 AI 기반 구조화된 추출을 사용하여 페이지 콘텐츠를 정의된 스키마로 변환합니다.
자동화 스크립트가 두 가지 Stagehand AI 기반 API에 의존하는 방식에 주목하세요:
.act(): 브라우저 세션에서 작업 수행 (예: 스크롤, 클릭, 탐색).extract(): 스키마를 사용하여 페이지에서 구조화된 데이터 추출
훌륭합니다! 다음 단계는 스크래핑된 데이터를 내보내는 것입니다.
Step #7: 스크래핑된 데이터 추출
이 시점에서 스크래핑된 데이터는 이미 stagehand.extract()가 반환한 data 객체에 저장되어 있습니다. 마지막 단계는 나중에 재사용하거나 처리할 수 있도록 news.json 파일로 내보내는 것입니다.
Node.js의 기본 fs/promises API를 사용하여 이를 수행합니다:
import fs from "fs/promises";
// ...
// save extracted news to a JSON file
await fs.writeFile(
"news.json",
JSON.stringify(data.news, null, 2),
"utf-8"
);이는 깔끔하고 읽기 쉬운 형식으로 구조화된 뉴스 데이터를 담은 news.json 파일을 작성합니다.
임무 완료! Browser API를 브라우저 AI 에이전트로 활용하는 Stagehand 스크래핑 워크플로우가 완전히 구현되었습니다.
Step #8: 모두 합치기
Stagehand로 Yahoo Finance 스크래핑을 자동화하는 최종 index.ts 스크립트는 다음과 같습니다:
import { Stagehand } from "@browserbasehq/stagehand";
import dotenv from "dotenv";
import { z } from "zod";
import fs from "fs/promises";
// load the environment variables from the .env file
dotenv.config({
path: ".env",
});
// read the Bright Data Browser API credentials
const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";
// structured output schema
const YahooFinanceNewsSchema = z.object({
news: z.array(
z.object({
title: z
.string()
.describe("The visible headline text of the news article"),
articleUrl: z
.string()
.describe(
"The full article URL."
),
imageUrl: z
.string()
.describe(
"The full image URL."
),
source: z
.string()
.optional()
.describe("The publisher name, such as Reuters or Yahoo Finance"),
timestamp: z
.string()
.optional()
.describe("The visible publication time, such as '4h ago'"),
marketMoves: z
.array(
z.object({
ticker: z
.string()
.describe("The stock ticker symbol, such as NVDA or ^GSPC"),
changePercent: z
.string()
.optional()
.describe(
"The visible market percentage change, such as '+2.4%' or '-0.69%'"
),
})
)
.optional()
.describe(
"List of stock tickers mentioned in the article footer with their market change percentages"
),
})
),
});
async function main() {
// configure Stagehand to connect remotely to Bright Data's Browser API
// and use an OpenAI model
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
},
model: "openai/gpt-5.4-mini",
keepAlive: true,
verbose: 1,
});
// launch Stagehand and get the browser page
await stagehand.init();
const page = stagehand.context.pages()[0];
// go to Yahoo Finance
await page.goto("https://finance.yahoo.com/");
// automate the news article loading
await stagehand.act(
`Scroll down multiple times and wait for articles to load in the "More News" section. Repeat until at least 20 news articles are loaded.`,
{
timeout: 90000, // 90-second timeout
}
);
// scrape the news information
const data = await stagehand.extract(
`Scrape all visible news articles`,
YahooFinanceNewsSchema,
{
"timeout": 120000, // 120-second timeout
}
);
// save extracted news to a JSON file
await fs.writeFile(
"news.json",
JSON.stringify(data.news, null, 2),
"utf-8"
);
console.log("News exported to news.json");
// close the Stagehand instance and release the browser resources
await stagehand.close();
}
main().catch(console.error);그런 다음 .env 파일에는 다음이 저장됩니다:
OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"다음으로 스크립트를 실행합니다:
npm run start스크립트 실행이 완료되면 프로젝트 폴더에 news.json 파일이 나타납니다. 파일을 열면 다음과 같은 구조화된 데이터가 표시됩니다:
파일에 여러 번 스크롤한 후 Yahoo Finance 홈페이지에 표시되는 것과 동일한 기사가 포함되어 있지만, 이제 깔끔하고 구조화된 형식으로 저장되어 있음을 확인하세요.
이는 Browser API가 안티봇 보호가 있는 사이트에서도 동적 콘텐츠에 접근하고 대규모로 데이터를 추출할 수 있음을 증명합니다.
Et voilà! 이것은 하나의 예시에 불과하지만, Stagehand를 사용하여 다양한 시나리오와 사용 사례에서 Bright Data Browser API 워크플로우를 자동화할 수 있습니다.
결론
이 글에서는 Stagehand가 무엇이며 브라우저 자동화를 어떻게 지원하는지 알아보았습니다. 특히 Bright Data의 Browser API와 함께 사용하여 고도로 확장 가능하고 감지되지 않는 클라우드 브라우저 세션을 실행하는 방법을 살펴보았습니다.
그 결과 엔터프라이즈 수준의 워크로드로 확장 가능한 브라우저 자동화 설정이 완성됩니다. 동일한 통합으로 대규모 클라우드 인프라를 기반으로 한 에이전트 브라우저 AI 작업도 구현할 수 있습니다.
새 Bright Data 계정을 만들고 AI 준비가 된 웹 데이터 스크래핑 및 브라우저 자동화 솔루션을 탐색해 보세요!
