Stagehand + Scrapeless: Automação de Navegador de IA em um Navegador na Nuvem

TL;DR:

• Stagehand é uma estrutura de automação de navegador baseada em IA que combina instruções em inglês simples com código real do Playwright, expondo três primitivas — act, extract e observe — sobre uma sessão do Chrome DevTools Protocol.
• Aponte o Stagehand para o Scrapeless Scraping Browser definindo um campo: localBrowserLaunchOptions.cdpUrl para o endpoint WebSocket do Scrapeless. Nada mais sobre o seu código Stagehand muda.
• O navegador então roda na nuvem, então sua automação tem sessões gerenciadas, fingerprinting e egress residencial em vez de um Chromium local que você precisa iniciar, escalar e manter desbloqueado.
• Você traz sua própria chave de modelo. O Stagehand chama um modelo de linguagem para act/extract/observe; o navegador e o modelo são preocupações separadas.
• Comece grátis. Novas contas do Scrapeless incluem créditos gratuitos para o Scraping Browser — inscreva-se em app.scrapeless.com.

Stagehand, a estrutura de código aberto da Browserbase, se posiciona entre dois extremos: scripts de seletores frágeis que quebram a cada mudança de marcação, e agentes livres que você não pode prever. Ele oferece três primitivas componíveis — act para fazer algo, extract para extrair dados estruturados, e observe para encontrar elementos — cada uma guiada por uma instrução em linguagem natural e cada uma retornando ao seu controle. O que o Stagehand ainda precisa é de um navegador para controlar. Executar esse navegador localmente significa iniciar o Chromium, escalá-lo e mantê-lo desbloqueado. Este guia conecta o Stagehand ao Scraping Browser do Scrapeless, assim a estrutura permanece a mesma e o navegador se move para a nuvem. Cada comando e saída abaixo foram capturados de uma execução ao vivo.

O que esta integração oferece a você

O Stagehand se conecta a um navegador através do Chrome DevTools Protocol. O Scrapeless Scraping Browser expõe exatamente isso: um ambiente real do Chrome que você acessa através de uma URL WebSocket. Conectar os dois significa:

• Sem navegador local para operar. Você não inicia, corrige ou escala o Chromium; a sessão roda no lado do servidor e você se conecta a ela.
• Sessões e egress gerenciados. O navegador na nuvem lida com perfis de dispositivo realistas e roteamento residencial, assim as páginas que o Stagehand lê parecem com as de um visitante real.
• A mesma API do Stagehand. act, extract e observe se comportam de forma idêntica, seja o navegador local ou remoto — apenas a URL de conexão muda.
• Uma divisão clara de preocupações. O Scrapeless executa o navegador; seu modelo escolhido executa o raciocínio. Você pode trocar qualquer um sem mexer no outro.

Pré-requisitos

• Node.js 20.19+ ou 22.12+ e um gerenciador de pacotes (este guia usa pnpm).
• Uma chave de API do Scrapeless para o Scraping Browser — obtenha uma no plano gratuito em app.scrapeless.com.
• Uma chave de API de provedor de modelo. O Stagehand chama um modelo de linguagem para suas primitivas; qualquer provedor suportado funciona.

Instalação

Adicione Stagehand e Zod, que tipa a saída estruturada de extract:

pnpm add @browserbasehq/stagehand zod

Conecte o Stagehand ao Scraping Browser

Toda a integração se resume a um campo. O localBrowserLaunchOptions.cdpUrl do Stagehand aceita um endpoint WebSocket do CDP; passe a URL do Scrapeless Scraping Browser, com sua chave API como o parâmetro de consulta token. O modelo é fornecido separadamente como um llmClient.

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

// Seu próprio provedor de modelo (OpenAI aqui; insira qualquer chave de provedor suportada).
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();

Depois de init(), o Stagehand está controlando uma sessão do Chrome hospedada pelo Scrapeless. O contexto do Playwright está disponível como stagehand.context, e as três primitivas de IA residem na instância stagehand.

Dirija a Página

A navegação utiliza o contexto padrão do Playwright. Pegue a página ativa e vá para um alvo:

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

observe — encontre um elemento em inglês simples

observe retorna elementos candidatos com um seletor resolvido, para que você possa inspecionar a que uma ação se dirigiria antes de executá-la:

const candidates = await stagehand.observe("o link de login na barra de navegação superior");
console.log(candidates[0]);

Uma execução ao vivo retornou um único candidato resolvido:

// Capturado de uma execução ao vivo contra o Scrapeless Scraping Browser.
{
  "description": "Link para a página de login na barra de navegação superior",
  "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 — transforme uma página em dados tipados

extract pega uma instrução e um esquema Zod, e retorna dados que correspondem ao esquema. O esquema é o contrato; o Stagehand o preenche a partir da página:

const result = await stagehand.extract(
  "extraia os 3 títulos de histórias principais e suas contagens de pontos da página inicial",
  z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })).max(3),
  }),
);
console.log(result);

A execução ao vivo retornou linhas tipadas diretamente da página inicial:

// Capturado de uma execução ao vivo — títulos reais e contagens de pontos da página inicial.
{
  "stories": [
    { "title": "Executando Gemma 4 26B a 5 tokens/seg em um Xeon de 13 anos sem GPU (neomindlabs.com)", "points": 82 },
    { "title": "Mistérios dos Centros de Dados do Telegram (dev.moe)", "points": 163 },
    { "title": "Memória de código aberto para agentes de codificação, sincronizada via SSH (github.com/vshulcz)", "points": 43 }
  ]
}

act — execute uma ação a partir de uma instrução

act executa uma ação em inglês simples na página. Aqui ele clica em um link de navegação, o que move a sessão para uma nova URL:

console.log(page.url()); // https://news.ycombinator.com/
await stagehand.act("clique no link 'novo' na navegação superior");
await page.waitForLoadState("domcontentloaded");
console.log(page.url()); // https://news.ycombinator.com/newest

A execução ao vivo navegou de https://news.ycombinator.com/ para https://news.ycombinator.com/newest, confirmando que a instrução foi resolvida para um clique real.

Fechar a Sessão

Liberte o navegador em nuvem quando a execução terminar:

await stagehand.close();

Por que executar o navegador no Scrapeless

O Stagehand é deliberadamente não opinativo sobre onde o navegador reside — isso é o que torna a troca cdpUrl tão limpa. Executar o Chromium você mesmo é bom para uma demonstração no laptop, mas uma carga de trabalho real significa concorrência, higiene de sessão e permanecer desbloqueado em várias páginas. O Scrapeless Scraping Browser é um ambiente Chrome real com perfis de dispositivo e impressão digital realistas e saída residencial, acessado através do mesmo WebSocket CDP que o Stagehand já fala. Você mantém o modelo de programação do Stagehand e entrega as operações do navegador a um serviço gerenciado. As opções de conexão — duração da sessão, região e impressão digital — são cobertas na documentação do Scraping Browser, e para uma integração de agente diferente movida por CDP veja o passo a passo do skill do navegador Hermes.

Obtenha sua chave no plano gratuito em app.scrapeless.com e os créditos do Scraping Browser cobrem as primeiras execuções.

Conclusão

O Stagehand oferece act, extract e observe sobre um navegador que você aponta com uma única URL. Defina localBrowserLaunchOptions.cdpUrl para o endpoint do Scrapeless Scraping Browser, forneça sua chave de modelo, e a estrutura executa sem alterações em um navegador em nuvem gerenciado — com extract retornando dados tipados em esquema e act dirigindo a página a partir de inglês simples. A conexão é um campo; tudo que você constrói em cima disso permanece o mesmo.
Pronto para executar seus scripts Stagehand em um navegador na nuvem? Comece grátis no painel do Scrapeless, veja a página do produto Scraping Browser ou compare planos em preços Scrapeless.

FAQ

P: O que é Stagehand?
R: Stagehand é um framework de automação de navegador de código aberto da Browserbase que adiciona três primitivas em linguagem natural — act, extract e observe — sobre uma sessão do Protocolo DevTools do Chrome, para que você misture instruções em inglês simples com código determinístico do Playwright.

P: Como o Stagehand se conecta ao Scrapeless Scraping Browser?
R: Defina localBrowserLaunchOptions.cdpUrl no construtor Stagehand para o endpoint WebSocket do Scrapeless wss://browser.scrapeless.com/api/v2/browser, com sua chave API como o parâmetro de consulta token. O Stagehand então controla a sessão na nuvem via CDP.

P: Preciso de uma chave de modelo de linguagem?
R: Sim. O Scrapeless fornece o navegador; o Stagehand chama um modelo para act, extract e observe. Forneça sua própria chave de provedor através da configuração do modelo do Stagehand — o navegador e o modelo permanecem separados.

P: Meu código Stagehand muda quando eu migro para o navegador na nuvem?
R: Não. Apenas a URL de conexão muda. act, extract, observe e o contexto do Playwright se comportam da mesma forma, independentemente de o navegador ser local ou a sessão remota do Scrapeless.

P: Como eu extraio dados estruturados de uma página?
R: Chame extract com uma instrução e um esquema Zod. O Stagehand retorna um objeto que corresponde ao esquema — por exemplo, um array de { title, points } — para que você obtenha dados tipados em vez de HTML bruto.

P: Como eu defino a região do navegador?
R: Adicione um parâmetro de consulta proxy_country à URL CDP do Scrapeless, para que a saída da sessão corresponda ao mercado que você deseja ver.

P: Posso inspecionar um elemento antes de agir sobre ele?
R: Sim. Chame observe com uma descrição; ele retorna elementos candidatos com um seletor resolvido e um método sugerido, que você pode revisar antes de executar act.