Stagehand com a Browser API da Bright Data: Automação de Navegador

Neste post, você aprenderá:

O que é o Stagehand e o que ele oferece para automação de navegador.
Os benefícios de usar o Stagehand junto com sessões de navegador stealth baseadas em nuvem fornecidas pela Browser API da Bright Data.
Um guia passo a passo para configurar a Browser API no Stagehand.

Vamos começar!

O que é o Stagehand?

Stagehand é um framework de automação de navegador de código aberto desenvolvido pela Browserbase. Ele combina IA em linguagem natural com código determinístico. Resolve o trade-off entre ferramentas frágeis baseadas em seletores (como o Playwright) e agentes de IA imprevisíveis, permitindo escolher quando usar cada abordagem.

Ele funciona traduzindo instruções em ações de navegador e saídas estruturadas, usando um LLM subjacente mais uma camada de execução controlada. O Stagehand também suporta o desenvolvimento de agentes de IA baseados em navegador.

Crescimento de estrelas do Stagehand no GitHub ao longo do tempo

Ele também possui recursos que o fazem operar como uma ferramenta de scraping de dados com IA. O Stagehand conta com uma grande comunidade de desenvolvedores, com mais de 22,9 mil estrelas no GitHub e mais de 1 milhão de downloads semanais no npm.

Recursos do Stagehand

Os principais recursos oferecidos pelo Stagehand são:

Execução act(): Execute ações no navegador como cliques, rolagem e preenchimento de formulários usando prompts em linguagem natural.
Dados estruturados extract(): Extraia o conteúdo da página em schemas validados pelo Zod para uso confiável.
Consciência de página observe(): Detecte elementos acionáveis em uma página antes de executar operações, melhorando a segurança e a precisão.
Fluxos autônomos agent(): Execute tarefas de navegador com múltiplas etapas de ponta a ponta com supervisão mínima.
Automação autocorretiva: Adapta-se a mudanças na interface, reduzindo falhas frágeis baseadas em seletores.
Cache de ações: Evite chamadas redundantes ao LLM armazenando ações em cache, garantindo execução altamente previsível e econômica em múltiplas execuções.
Flexibilidade de LLM: Funciona com múltiplos provedores mantendo a execução determinística e depurável.
Primitivas combináveis: Combine act, extract, observe e agent para criar pipelines de automação personalizados.
Ferramentas focadas no desenvolvedor: Projetadas para manutenibilidade, reprodutibilidade e integração em sistemas de IA modernos.

Saiba mais na documentação oficial.

Por que combinar o Stagehand com a Browser API da Bright Data

Ferramentas de automação de navegador como o Stagehand enfrentam os mesmos problemas centrais:

Sites bloqueiam ativamente o tráfego automatizado usando sistemas de detecção de bots, CAPTCHAs, fingerprinting e verificações de reputação de IP. Isso torna as automações frágeis, pois um script pode funcionar em testes, mas falhar de forma imprevisível em produção.
Executar muitas instâncias de navegador localmente ou em infraestrutura autogerenciada consome muitos recursos. Navegadores exigem CPU e memória substanciais, tornando a execução simultânea de muitas instâncias custosa e difícil de escalar de forma confiável.
Gerenciar proxies e distribuição geográfica adiciona sobrecarga operacional. Com o tempo, essa complexidade se torna difícil de manter para cargas de trabalho de scraping ou agentes de IA em nível de produção.

A Browser API da Bright Data resolve esses problemas transferindo a execução local do navegador para uma infraestrutura gerenciada e baseada em nuvem, projetada para escala e stealth.

Em vez de gerenciar navegadores localmente, você se conecta por meio de um único endpoint CDP. Você obtém acesso a navegadores remotos pré-configurados com rotação de Proxy integrada, Resolução de CAPTCHA e evasão avançada de fingerprinting.

O que diferencia a Bright Data é sua arquitetura de nível empresarial, respaldada por uma rede de Proxy com mais de 400 milhões de IPs residencialis. Isso permite alta anonimidade, geolocalização global e concorrência infinita, com uma taxa de sucesso de 99,95% e uptime garantido por SLA de 99,99%.

Como integrar o Stagehand com a Browser API

Neste capítulo, você verá como usar o Stagehand para automatizar instâncias de navegador remotas. Em detalhes, você se conectará a sessões de navegador em nuvem stealth, antidetecção e infinitamente escaláveis via Browser API da Bright Data.

Siga as instruções abaixo.

Pré-requisitos

Para acompanhar esta seção do tutorial, certifique-se de ter:

Node.js 20+ instalado localmente (Node.js 22+ recomendado).
Uma chave de API de um provedor de IA compatível com o Stagehand (aqui, usaremos uma chave de API da OpenAI).
Uma conta na Bright Data.
Conhecimento básico da API do Stagehand e seus recursos de automação de navegador com IA.

Passo #1: Inicializar o projeto Stagehand

Configure um novo projeto Stagehand seguindo o guia de início rápido. Como alternativa, execute o comando abaixo:

npx create-browser-app bright-data-stagehand-example

O comando npx create-browser-app cria um novo projeto Stagehand no diretório bright-data-stagehand-example.

Após executá-lo, você deverá ver:

Em seguida, entre no diretório do projeto:

cd bright-data-stagehand-example

A estrutura do seu projeto deve ser assim:

bright-data-stagehand-example/
├── .cursorrules
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.json

Reserve alguns minutos para explorar os arquivos gerados e se familiarizar com a estrutura do projeto. Foque no index.ts, que representa o arquivo principal do Stagehand.

Agora, limpe o arquivo index.ts deixando apenas:

import { Stagehand } from "@browserbasehq/stagehand";

Em breve você verá como conectar o Stagehand à Browser API da Bright Data. Ótimo!

Passo #2: Configurar a leitura de variáveis de ambiente

Seu projeto de automação em nuvem com Stagehand dependerá de alguns segredos (ex.: chave de API do provedor de IA, credenciais da Browser API da Bright Data, etc.). Em vez de codificá-los diretamente no código, a melhor prática é carregá-los a partir de variáveis de ambiente.

Por padrão, o Stagehand não carrega arquivos .env automaticamente. Para habilitar isso, comece instalando o pacote dotenv:

npm install dotenv

Em seguida, em index.ts, adicione o seguinte:

import dotenv from "dotenv";

dotenv.config({
  path: ".env",
});

Agora, você precisa definir um arquivo .env. Você pode criá-lo copiando o arquivo .env.example gerado quando você executou npx create-browser-app. Caso contrário, adicione manualmente um arquivo .env ao seu projeto Stagehand:

bright-data-stagehand-example/
├── .cursorrules
├── .env           # <---------
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.json

Preencha o arquivo .env com sua chave de API do provedor de IA (neste caso, OpenAI):

OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Substitua o placeholder <YOUR_OPENAI_API_KEY> pela sua chave de API real da OpenAI.

O Stagehand lerá automaticamente a variável de ambiente OPENAI_API_KEY em tempo de execução, portanto nenhuma configuração adicional é necessária. Excelente!

Passo #3: Começar a usar a Browser API da Bright Data

É hora de recuperar a URL de conexão remota baseada em CDP para a Browser API da Bright Data.

Se ainda não o fez, crie uma conta na Bright Data. Se já tiver, faça login e acesse o painel de controle:

Em seguida, navegue até a opção “Web Access > Web Access API” no menu à esquerda:

Se você já vir uma entrada de Browser API na tabela “My APIs” (como abaixo, via API browser_api), você está pronto para continuar:

Caso contrário, clique no dropdown do botão “Create API” e selecione “Browser API”:

Isso iniciará o assistente de configuração da Browser API. Dê um nome à sua Browser API (ex.: browser_api) e configure a API de acordo com suas necessidades:

Quando terminar, clique no botão “Add API”. Acesse a página de detalhes da Browser API:

Aqui, você encontrará os detalhes de conexão para integrações baseadas em CDP (a URL em “Puppeteer / Playwright”). A URL WebSocket da Browser API segue este formato:

wss://<BROWSER_API_USERNAME>:<BROWSER_API_USERNAME>@brd.superproxy.io:9222

Copie o nome de usuário e a senha da Browser API da página da Browser API e adicione-os ao seu arquivo .env:

BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"

Você usará essas variáveis posteriormente em index.ts para construir a URL de conexão CDP remota.

Agora você tem todos os elementos necessários para automação de navegador em nuvem com Stagehand via Browser API da Bright Data. Excelente!

Passo #4: Conectar à Browser API da Bright Data no Stagehand

Em index.ts, comece lendo as credenciais da Browser API a partir das suas variáveis de ambiente:

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 || "";

Em seguida, inicialize o Stagehand dentro de uma função main() para conexão com a Browser API da Bright Data via URL WebSocket CDP:

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);

O trecho acima configura o Stagehand com a URL WSS autenticada da Browser API construída usando as credenciais lidas das variáveis de ambiente. Em seguida, inicia uma sessão remota do navegador e expõe um objeto de página para automação. Após executar sua lógica de automação, ele encerra a sessão e libera todos os recursos remotos do navegador.

No exemplo acima, configuramos o OpenAI GPT-5.4 Mini. Observe que qualquer outro modelo da OpenAI (ou uma configuração de provedor de IA compatível) também funcionará.

A parte essencial está no construtor do Stagehand. A configuração pode parecer um pouco confusa no início porque, para conectar a um navegador remoto, você ainda precisa definir env como "LOCAL". Então, dentro de localBrowserLaunchOptions, você precisa fornecer a URL WSS da Browser API da Bright Data via campo cdpUrl.

Portanto, mesmo que env esteja definido como "LOCAL", o Stagehand na verdade se conecta às instâncias remotas de navegador antidetecção em nuvem da Bright Data.

Agora você pode testar a integração com um exemplo simples para confirmar que tudo está funcionando corretamente.

Passo #5: Verificar a integração com a Browser API da Bright Data

Para verificar que a integração com a Browser API funciona, tente a seguinte lógica de automação:

// 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,
});

Isso instrui o navegador remoto (exposto via Browser API da Bright Data) a abrir o example.com e capturar uma screenshot.

Junte tudo:

// 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);

Execute o script com:

npm run start

No terminal, você deverá ver logs semelhantes a:

Importante: Os logs podem mencionar “connecting to local browser.” Isso se deve à configuração necessária env: "LOCAL". No entanto, a conexão real é feita com a Browser API remota da Bright Data.

Após a conclusão da execução, um arquivo screenshot.png aparecerá no diretório do seu projeto:

bright-data-stagehand-example/
├── .cursorrules
├── .env           
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
├── screenshot.png       # <---------
└── tsconfig.json

Abra o screenshot.png e você deverá ver a página example.com renderizada:

Isso confirma que o Stagehand se conectou com sucesso ao site de destino e executou a automação do navegador conforme esperado.

Para verificar que a Browser API da Bright Data foi utilizada, verifique seu painel da Bright Data:

Observe o pico no Tráfego da Browser API

Você deverá ver um pico de Tráfego indicando uso ativo da sessão da Browser API configurada via conexão CDP remota. Isso confirma que toda a automação do Stagehand é corretamente roteada pela Browser API da Bright Data. Incrível!

Passo #6: Implementar automação de navegador remoto com IA no mundo real

Agora, suponha que você queira automatizar a lógica do navegador para coletar dados de artigos de notícias do Yahoo Finance.

Como a página inicial do Yahoo Finance carrega novos artigos

Este é um bom exemplo porque a página inicial do Yahoo Finance usa rolagem infinita para carregar novos artigos dinamicamente. É também um site conhecido por suas rigorosas proteções antibot e anti-scraping.

Graças às capacidades de stealth e bypass antibot fornecidas pela Browser API, você pode acessar o Yahoo Finance via Stagehand sem ser bloqueado.

Como você quer que os dados extraídos sigam uma estrutura específica, comece definindo um tipo de dados de saída com o 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"
        ),
    })
  ),
});

Isso define a estrutura de saída esperada para os dados extraídos. Em particular, corresponde às informações disponíveis nos cards de notícias do Yahoo Finance:

Observe as informações disponíveis nos cards de notícias do Yahoo Finance

Se você inicializar seu app Stagehand via npx create-browser-app, não precisará instalar o zod manualmente. Ele já está incluído nas dependências do projeto. Caso contrário, instale-o com:

npm install zod

Agora, você pode automatizar o fluxo de navegação e extração 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
  }
);

Isso replica o comportamento de um usuário real rolando a página para carregar mais artigos, mas guiado por instruções de IA. Em seguida, usa a extração estruturada com IA para converter o conteúdo da página no schema definido.

Observe como o script de automação depende de duas APIs com IA do Stagehand:

.act(): Executa ações na sessão do navegador (ex.: rolagem, cliques, navegação)
.extract(): Extrai dados estruturados da página usando um schema

Fantástico! O próximo passo é exportar os dados extraídos.

Passo #7: Exportar os dados extraídos

Neste ponto, os dados extraídos já estão armazenados no objeto data retornado por stagehand.extract(). O passo final é exportá-los para um arquivo news.json para que possam ser reutilizados ou processados posteriormente.

Faça isso usando a API nativa fs/promises do Node.js:

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"
);

Isso grava um arquivo news.json contendo os dados de notícias estruturados em um formato limpo e legível.

Missão cumprida! O fluxo de scraping com Stagehand usando a Browser API como agente de IA de navegador está agora totalmente implementado.

Passo #8: Juntar tudo

Seu script final index.ts para automatizar o scraping do Yahoo Finance com Stagehand ficará assim:

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);

Em seguida, o arquivo .env armazenará:

OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"

Inicie o script com:

npm run start

Quando o script terminar de executar, um arquivo news.json aparecerá na pasta do seu projeto. Se você abri-lo, deverá ver dados estruturados como este:

Observe os dados de notícias estruturados extraídos no arquivo \

Observe como o arquivo contém os mesmos artigos que aparecem na página inicial do Yahoo Finance após rolar várias vezes, mas agora em um formato limpo e estruturado.

Isso prova como a Browser API pode acessar conteúdo dinâmico e extrair dados em escala, mesmo de um site com proteções antibot.

Et voilà! Este foi apenas um exemplo, mas você pode usar o Stagehand para automatizar fluxos de trabalho da Browser API da Bright Data em muitos outros cenários e casos de uso.

Conclusão

Neste artigo, você aprendeu o que é o Stagehand e como ele suporta a automação de navegador. Especificamente, você viu como usá-lo com a Browser API da Bright Data para executar sessões de navegador em nuvem altamente escaláveis e não detectadas.

O resultado é uma configuração de automação de navegador que pode escalar para cargas de trabalho de nível empresarial. Com a mesma integração, você também pode implementar operações agênticas de IA no navegador respaldadas por infraestrutura em nuvem de grande escala.

Crie uma nova conta na Bright Data e explore nossas soluções de scraping de dados da web e automação de navegador prontas para IA!

Contate-nos Teste grátis