Stagehand + Scrapeless: Tự động hóa trình duyệt AI trên trình duyệt đám mây

Tóm tắt:

• Stagehand là một framework tự động hóa trình duyệt AI kết hợp hướng dẫn bằng tiếng Anh đơn giản với mã Playwright thực tế, cung cấp ba nguyên lí cơ bản — act, extract, và observe — trên nền tảng một phiên làm việc của Chrome DevTools Protocol.
• Hướng Stagehand đến Scrapeless Scraping Browser bằng cách thiết lập một trường: localBrowserLaunchOptions.cdpUrl đến điểm cuối WebSocket của Scrapeless. Không có gì khác trong mã Stagehand của bạn thay đổi.
• Trình duyệt sau đó hoạt động trên đám mây, vì vậy việc tự động hóa của bạn có các phiên quản lý, nhận dạng dấu vân tay và truy cập địa chỉ cư trú thay vì một Chromium cục bộ mà bạn phải khởi động, mở rộng và giữ không bị chặn.
• Bạn mang theo chính khóa mô hình của mình. Stagehand gọi một mô hình ngôn ngữ cho act/extract/observe; trình duyệt và mô hình là hai vấn đề riêng biệt.
• Bắt đầu miễn phí. Tài khoản Scrapeless mới bao gồm tín dụng Scraping Browser miễn phí — đăng ký tại app.scrapeless.com.

Stagehand, framework mã nguồn mở từ Browserbase, nằm giữa hai giới hạn: các kịch bản chọn lọc dễ gãy với mỗi thay đổi markup và những tác nhân tự do mà bạn không thể dự đoán. Nó cung cấp cho bạn ba nguyên lí có thể phối hợp — act để thực hiện một việc gì đó, extract để lấy dữ liệu có cấu trúc, và observe để tìm các phần tử — mỗi nguyên lí được thúc đẩy bởi một hướng dẫn ngôn ngữ tự nhiên và mỗi nguyên lí đều trả về quyền kiểm soát của bạn. Điều mà Stagehand vẫn cần là một trình duyệt để điều khiển. Chạy trình duyệt đó cục bộ có nghĩa là khởi động Chromium, mở rộng nó và giữ cho nó không bị chặn. Hướng dẫn này kết nối Stagehand với Scraping Browser thay thế, vì vậy framework vẫn giữ nguyên và trình duyệt chuyển lên đám mây. Mỗi lệnh và đầu ra dưới đây được ghi lại từ một phiên chạy thực tế.

Điều Gì Mà Tích Hợp Này Mang Đến Cho Bạn

Stagehand kết nối với một trình duyệt qua Chrome DevTools Protocol. Scrapeless Scraping Browser chính xác cung cấp điều đó: một môi trường Chrome thực tế mà bạn truy cập qua một URL WebSocket. Kết nối hai cái này có nghĩa là:

• Không có trình duyệt cục bộ để vận hành. Bạn không khởi động, vá hoặc mở rộng Chromium; phiên làm việc chạy bên máy chủ và bạn kết nối với nó.
• Quản lý các phiên làm việc và truy cập. Trình duyệt đám mây xử lý các hồ sơ thiết bị thực tế và định tuyến cư trú, khiến các trang mà Stagehand đọc giống như của một khách truy cập thực sự.
• API Stagehand giống nhau. act, extract, và observe hoạt động giống nhau bất kể trình duyệt là cục bộ hay từ xa — chỉ có URL kết nối là thay đổi.
• Một phân chia sạch giữa các vấn đề. Scrapeless chạy trình duyệt; mô hình mà bạn chọn chạy lý luận. Bạn có thể thay đổi bất kỳ cái nào mà không chạm đến cái còn lại.

Các yêu cầu tiên quyết

• Node.js 20.19+ hoặc 22.12+ và một trình quản lý gói (hướng dẫn này sử dụng pnpm).
• Một khóa API Scrapeless cho Scraping Browser — lấy một cái trong gói miễn phí tại app.scrapeless.com.
• Một khóa API nhà cung cấp mô hình. Stagehand gọi một mô hình ngôn ngữ cho các nguyên lí của nó; bất kỳ nhà cung cấp được hỗ trợ nào đều hoạt động.

Cài đặt

Thêm Stagehand và Zod, cái mà định loại đầu ra có cấu trúc của extract:

pnpm add @browserbasehq/stagehand zod

Kết nối Stagehand với Scraping Browser

Tất cả tích hợp là một trường duy nhất. localBrowserLaunchOptions.cdpUrl của Stagehand chấp nhận một điểm cuối CDP WebSocket; truyền URL của Scrapeless Scraping Browser, với khóa API của bạn như tham số truy vấn token. Mô hình được cung cấp riêng biệt như một llmClient.

import { Stagehand, AISdkClient, getAISDKLanguageModel } from "@browserbasehq/stagehand";
import { z } from "zod";

// Nhà cung cấp mô hình của chính bạn (OpenAI ở đây; thay thế bằng bất kỳ khóa nhà cung cấp được hỗ trợ nào).
const model = getAISDKLanguageModel("openai", "gpt-4o-mini", {
  apiKey: process.env.OPENAI_API_KEY,
});

const stagehand = new Stagehand({
  env: "LOCAL",
  llmClient: new AISdkClient({ model }),
  localBrowserLaunchOptions: {
    cdpUrl:
      `wss://browser.scrapeless.com/api/v2/browser` +
      `?token=${process.env.SCRAPELESS_API_KEY}` +
      `&session_ttl=180&proxy_country=US`,
  },
});

await stagehand.init();

Sau init(), Stagehand đang điều khiển một phiên Chrome được lưu trữ bởi Scrapeless. Bối cảnh Playwright có sẵn dưới dạng stagehand.context, và ba nguyên lí AI sống trên phiên bản stagehand.

Điều khiển Trang

Chuyển hướng sử dụng ngữ cảnh chuẩn của Playwright. Lấy trang đang hoạt động và đi đến một mục tiêu:

const context = stagehand.context;
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://news.ycombinator.com", { waitUntil: "domcontentloaded" });

observe — tìm một phần tử bằng tiếng Anh đơn giản

observe trả về các phần tử ứng viên với một bộ chọn đã được giải quyết, vì vậy bạn có thể kiểm tra mục tiêu của hành động trước khi thực hiện:

const candidates = await stagehand.observe("liên kết đăng nhập trong thanh điều hướng trên cùng");
console.log(candidates[0]);

Một lần chạy trực tiếp đã trả về một ứng viên đã được giải quyết:

// Được thu thập từ một lần chạy trình thu thập trực tiếp với Trình duyệt Thu thập Không Thoát.
{
  "description": "Liên kết đến trang đăng nhập trong thanh điều hướng trên cùng",
  "method": "click",
  "arguments": [],
  "selector": "xpath=/html[1]/body[1]/center[1]/table[1]/tbody[1]/tr[1]/td[1]/table[1]/tbody[1]/tr[1]/td[3]/span[1]/a[1]"
}

extract — chuyển một trang thành dữ liệu có kiểu

extract nhận một hướng dẫn và một lược đồ Zod, và trả về dữ liệu phù hợp với lược đồ. Lược đồ là hợp đồng; Stagehand sẽ điền từ trang:

const result = await stagehand.extract(
  "trích xuất 3 tiêu đề câu chuyện hàng đầu và số điểm của chúng từ trang chính",
  z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })).max(3),
  }),
);
console.log(result);

Lần chạy trực tiếp đã trả về các hàng có kiểu trực tiếp từ trang chính:

// Được thu thập từ một lần chạy trực tiếp - các tiêu đề thực và số điểm từ trang chính.
{
  "stories": [
    { "title": "Chạy Gemma 4 26B với 5 mã/token trên một chiếc Xeon 13 năm tuổi không có GPU (neomindlabs.com)", "points": 82 },
    { "title": "Những bí ẩn của Trung tâm Dữ liệu Telegram (dev.moe)", "points": 163 },
    { "title": "Bộ nhớ mã nguồn mở cho các tác nhân lập trình, đồng bộ qua SSH (github.com/vshulcz)", "points": 43 }
  ]
}

act — thực hiện một hành động từ một hướng dẫn

act thực hiện một hành động bằng tiếng Anh đơn giản trên trang. Ở đây nó nhấn vào một liên kết điều hướng, điều này di chuyển phiên đến một URL mới:

console.log(page.url()); // https://news.ycombinator.com/
await stagehand.act("nhấn vào liên kết 'mới' trong thanh điều hướng trên cùng");
await page.waitForLoadState("domcontentloaded");
console.log(page.url()); // https://news.ycombinator.com/newest

Lần chạy trực tiếp đã điều hướng từ https://news.ycombinator.com/ đến https://news.ycombinator.com/newest, xác nhận rằng hướng dẫn đã được giải quyết thành một cú nhấp thực.

Đóng Phiên

Giải phóng trình duyệt đám mây khi lần chạy kết thúc:

await stagehand.close();

Tại Sao Chạy Trình Duyệt Trên Scrapeless

Stagehand được thiết kế không thiên lệch về nơi mà trình duyệt sống — đó là điều khiến việc hoán đổi cdpUrl trở nên gọn gàng. Chạy Chromium trên máy tính xách tay của bạn là tốt cho một buổi trình diễn, nhưng một khối lượng công việc thực tế có nghĩa là đồng thời, vệ sinh phiên và không bị chặn trên nhiều trang. Trình duyệt Thu thập Không Thoát là một môi trường Chrome thực với các hồ sơ thiết bị và dấu vân tay thực tế và truy xuất từ nhà ở, được tiếp cận qua cùng một WebSocket CDP mà Stagehand đã nói chuyện. Bạn giữ mô hình lập trình của Stagehand và giao cho các hoạt động trình duyệt cho một dịch vụ được quản lý. Các tùy chọn kết nối — thời gian sống phiên, khu vực và dấu vân tay — được đề cập trong tài liệu Trình duyệt Thu thập, và cho tích hợp tác nhân dựa trên CDP khác xem hướng dẫn kỹ năng trình duyệt Hermes.

Nhận chìa khóa của bạn trên kế hoạch miễn phí tại app.scrapeless.com và các tín dụng Trình duyệt Thu thập bao gồm các lần chạy đầu tiên.

Kết Luận

Stagehand cung cấp act, extract, và observe trên một trình duyệt mà bạn chỉ định với một URL duy nhất. Đặt localBrowserLaunchOptions.cdpUrl cho điểm cuối của Trình duyệt Thu thập Không Thoát, cung cấp chìa khóa mô hình của bạn, và khung sẽ chạy không thay đổi trên một trình duyệt đám mây được quản lý — với extract trả về dữ liệu kiểu lược đồ và act điều khiển trang từ tiếng Anh đơn giản. Kết nối là một trường; mọi thứ bạn xây dựng trên đó vẫn giữ nguyên như vậy.
Sẵn sàng chạy các kịch bản Stagehand của bạn trên trình duyệt đám mây chưa? Bắt đầu miễn phí từ bảng điều khiển Scrapeless, xem trang sản phẩm Trình duyệt Scraping, hoặc so sánh các gói trên giá Scrapeless.

Câu hỏi thường gặp

Q: Stagehand là gì?
A: Stagehand là một framework tự động hóa trình duyệt mã nguồn mở từ Browserbase, bổ sung ba nguyên lý ngôn ngữ tự nhiên — act, extract, và observe — trên nền tảng phiên làm việc Chrome DevTools Protocol, giúp bạn kết hợp hướng dẫn bằng tiếng Anh đơn giản với mã Playwright có tính xác định.

Q: Stagehand kết nối với Trình duyệt Scraping Scrapeless như thế nào?
A: Cài đặt localBrowserLaunchOptions.cdpUrl trong constructor của Stagehand thành điểm cuối WebSocket Scrapeless wss://browser.scrapeless.com/api/v2/browser, với khóa API của bạn làm tham số truy vấn token. Stagehand sau đó điều khiển phiên làm việc đám mây qua CDP.

Q: Tôi vẫn cần một khóa ngôn ngữ mô hình không?
A: Có. Scrapeless cung cấp trình duyệt; Stagehand gọi một mô hình cho act, extract, và observe. Cung cấp khóa của nhà cung cấp của bạn thông qua cấu hình mô hình của Stagehand — trình duyệt và mô hình vẫn tách biệt.

Q: Mã Stagehand của tôi có thay đổi khi tôi chuyển sang trình duyệt đám mây không?
A: Không. Chỉ có URL kết nối thay đổi. act, extract, observe, và ngữ cảnh Playwright hoạt động như nhau cho dù trình duyệt là cục bộ hay phiên Scrapeless từ xa.

Q: Làm thế nào để tôi lấy dữ liệu có cấu trúc từ một trang?
A: Gọi extract với một hướng dẫn và một schema Zod. Stagehand trả về một đối tượng khớp với schema — ví dụ như một mảng { title, points } — vì vậy bạn nhận được dữ liệu có kiểu thay vì HTML thô.

Q: Làm thế nào để tôi thiết lập khu vực của trình duyệt?
A: Thêm tham số truy vấn proxy_country vào URL CDP của Scrapeless, để đầu ra của phiên phù hợp với thị trường bạn muốn xem.

Q: Tôi có thể kiểm tra một phần tử trước khi hành động trên nó không?
A: Có. Gọi observe với một mô tả; nó trả về các phần tử ứng viên với bộ chọn đã được giải quyết và phương pháp gợi ý, mà bạn có thể xem xét trước khi thực hiện act.