본문으로 건너뛰기

무대 담당자

그만큼@mastra/stagehand패키지는 다음을 사용하여 브라우저 자동화를 제공합니다.스테이지핸드 SDK브라우저베이스에서. Stagehand는 AI를 사용하여 페이지 컨텍스트를 이해하고 요소를 찾아 명시적인 선택기 대신 자연어 설명을 가능하게 합니다.

Stagehand를 사용해야 하는 경우
Stagehand를 사용해야 하는 경우에 대한 직접 링크

다음이 필요할 때 Stagehand를 사용하세요.

  • 자연어 요소 타겟팅("로그인 버튼 선택")
  • 페이지에서 AI 기반 데이터 추출
  • 기본 브라우저 기반 클라우드 통합
  • 일반적인 작업을 위한 더욱 간단한 Tool 인터페이스

빠른 시작
빠른 시작에 대한 직접 링크

패키지를 설치합니다:

npm install @mastra/stagehand

브라우저 인스턴스를 생성하고 Agent에 할당합니다.

src/mastra/agents/stagehand-agent.ts
import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
})

export const stagehandAgent = new Agent({
  id: 'stagehand-agent',
  name: 'Stagehand Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

Use stagehand tools to interact with pages:
- stagehand_navigate to go to URLs
- stagehand_act to perform actions described in natural language
- stagehand_extract to get structured data from the page
- stagehand_observe to find available actions on the page
- stagehand_screenshot to visually inspect the page`,
})

자연어 동작
자연어 동작에 대한 직접 링크

Agent가 stagehand_act Tool을 사용하면 자연어로 설명된 동작을 받을 수 있습니다.

  • "로그인 버튼을 클릭하세요."
  • "이메일 필드에 '[user@example.com](mailto:user@example.com)'을 입력하세요."
  • "국가 드롭다운에서 '미국'을 선택하세요." Stagehand의 AI는 작업을 해석하고 페이지에서 적절한 요소를 찾습니다.

데이터 추출
데이터 추출에 대한 직접 링크

Agent가 stagehand_extract Tool을 사용하면 페이지에서 구조화 데이터를 추출할 수 있습니다. 지침 예시: "제품 이름, 가격, 재고를 추출하세요."

이 Tool은 페이지 콘텐츠를 기반으로 구조화된 데이터를 반환합니다.

{
  "name": "Widget Pro",
  "price": "$29.99",
  "availability": "In Stock"
}

행동 관찰
행동 관찰에 대한 직접 링크

Agent가 stagehand_observe Tool을 사용하면 현재 페이지를 분석하고 가능한 동작을 반환합니다. 예제 지침: "이 로그인 양식에서 어떤 작업을 수행할 수 있나요?"

사용 가능한 작업 목록을 반환합니다.

[
  { "action": "Press 'Sign In' button", "element": "button" },
  { "action": "Type in 'Email' field", "element": "input" },
  { "action": "Open 'Forgot Password' link", "element": "a" }
]

스크린샷
스크린샷에 대한 직접 링크

Agent가 stagehand_screenshot Tool을 사용하면 현재 페이지의 PNG 이미지를 캡처하고 시각 기능을 지원하는 Model이 직접 해석할 수 있는 이미지 콘텐츠로 반환합니다. 이미지, 레이아웃 또는 색상 평가처럼 페이지를 시각적으로 검사해야 할 때는 스크린샷을 사용하세요. 텍스트 또는 구조화 데이터에는 대신 stagehand_extract 또는 stagehand_observe를 사용하세요.

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
})

비전을 지원하지 않는 Model의 스크린샷 Tool을 비활성화하려면 다음을 사용하세요.excludeTools:

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  excludeTools: ['stagehand_screenshot'],
})

브라우저베이스
브라우저베이스에 대한 직접 링크

Stagehand에는 클라우드 브라우저 인프라를 위한 기본 브라우저 베이스 통합 기능이 있습니다.

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.6-sol',
})

모든 구성 옵션은 StagehandBrowser 레퍼런스를 참조하세요.

녹음
녹음에 대한 직접 링크

Stagehand는 알파 브라우저 녹음 Tool을 선택할 수 있습니다.

const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  recording: {
    outputDir: './browser-recordings',
  },
})

이렇게 하면 Agent의 Tool 세트에 browser_record 및 browser_record_caption이 추가됩니다. 자세한 내용은 브라우저 녹화(알파)를 참조하세요.

On this page