browser-use → Stagehand no Browserbase (/browser-use-to-stagehand)

Converta um script do browser-use (Python) em um script idiomático do Stagehand v3 (TypeScript) no Browserbase, escolhendo o nível certo de determinismo em cada etapa, em vez de produzir uma cópia agente a agente.

Princípio fundamental: o browser-use é baseado em agentes por padrão (o LLM decide todas as ações). O Stagehand permite que você escolha o nível de IA a ser utilizado. Uma boa migração substitui loops de agente opacos por um fluxo inspecionável e predominantemente determinístico — utilizando IA apenas onde a página é genuinamente imprevisível. Trata-se de uma refatoração com discernimento, não de uma transpilagem.

Fonte de verdade e versões. O valor duradouro dessa habilidade está no discernimento — o espectro de determinismo e a decisão entre decomposição e agente — e não nos detalhes da API, que mudam a cada lançamento. Os mapeamentos de código aqui apresentados são um instantâneo validado contra o @browserbasehq/stagehand 3.6.x e o browser-use 0.13.x (2026-06). Em caso de conflito, a documentação atualizada prevalece — sempre verifique em relação ao pacote instalado e a estas fontes antes de gerar código:

• Stagehand v3: https://docs.stagehand.dev/v3 · tipos instalados: node_modules/@browserbasehq/stagehand
• Browserbase: https://docs.browserbase.com
• browser-use: https://docs.browser-use.com

Se a versão principal do Stagehand instalado não for 3, considere esta habilidade apenas conceitual e siga a documentação online para cada assinatura.

Arquivos de referência (leia conforme necessário)

• references/api-mapping.md — o mapeamento mecânico do browser-use → Stagehand : detecção de variantes, a tabela completa de recursos, código antes/depois, opções da plataforma Browserbase e armadilhas da versão v3. Leia isso para qualquer construção não trivial.
• references/determinism.md — como escolher agent() vs act/extract/observe vs em cache observe→act. A árvore de decisão. Leia isso ao decidir como traduzir um Agent(task=…).
• references/trace-assisted.md — o fluxo de trabalho opcional “execute no Browserbase, leia os logs e, em seguida, reescreva” para scripts opacos/instáveis.
• references/guide.md — o guia de migração para humanos: mudança de filosofia, mapeamento de recursos, o espectro do determinismo e um caminho de migração recomendado.
• references/prompt.md — uma versão autônoma e independente de ferramentas dessa habilidade; cole-a em qualquer assistente de IA junto com um script de uso do navegador.
• EXAMPLES.md — pares de scripts “antes” e “depois”.

Fluxo de trabalho

1. Obtenha a fonte

Obtenha o(s) script(s) de uso do navegador. Se o usuário tiver descrito apenas um script, peça o(s) arquivo(s). Anote o destino: TypeScript Stagehand no Browserbase, a menos que seja indicado o contrário.

Primeiro, avalie o escopo — isso é mesmo migrável? Nem todo arquivo de uso do navegador é um Agent(task=…) script. Se a fonte for o browser-use rodando como um servidor MCP (uvx browser-use --mcp, uma mcpServers config), não há equivalente no Stagehand — marque-o como fora do escopo, não invente um (consulte mapeamento de API §3.7b). Se a chamada do `browser-use` estiver incorporada em um aplicativo maior (um wrapper de classe/ferramenta, rota web, tarefa em fila), converta apenas a superfície do `browser-use` e preserve a integração com o aplicativo ao redor — consulte o mapeamento de API §3.8.

2. Detecte a variante do uso do navegador

Identifique a versão legada (pré-0.12) versus a estável versus a beta do Rust (somente quando as importações vierem de browser_use.beta) — consulte api-mapping §1. Observação: a superfície clássica de nível superior from browser_use import Agent, ChatBrowserUse continua ativa e funcionando na versão 0.13.x — ChatBrowserUse por si só não é um indicador de versão beta; apenas uma browser_use.beta import é. Todas as variantes são traduzidas de forma idêntica; portanto, em caso de dúvida, proceda com o mapeamento estável. Normalize os nomes legados antes de traduzir. Indique qual variante você encontrou.

3. Faça um inventário do script

Extraia um inventário estruturado antes de escrever qualquer TypeScript:

• Tarefa(s) — as task= string(s); divida cada uma em suas etapas ordenadas implícitas.
• Modelo — o Chat* provedor + ID do modelo.
• Configuração do navegador — local vs cdp_url/Browserbase; modo headless; proxies; user_data_dir/storage_state.
• Saída estruturada — quaisquer output_model_schema modelos Pydantic.
• Segredos — sensitive_data, uso de variáveis de ambiente, fluxos de login.
• Medidas de segurança — allowed_domains, max_steps.
• Ações personalizadas — @tools.action / Controller funções e se cada uma delas é um efeito colateral determinístico ou uma capacidade do agente.
• Configuração — initial_actions, modelos secundários (page_extraction_llm, planner_llm).

4. Decida o nível de determinismo por etapa

Para cada etapa do inventário, aplique a árvore de decisão em determinism.md:

• Navegar para uma URL conhecida → page.goto(url) na página Stagehand (sem IA).
• Ação na página → act("…"); se se repetir, observe() uma vez, repita act(action) (sem chamada de LLM).
• Leitura de dados → extract("…", zodSchema).
• Genuinamente aberto → manter stagehand.agent().execute(...) (aprimorado com maxSteps/systemPrompt).

Padrão para decomposição quando o fluxo é conhecido; manter agent() apenas quando não for. Para um primeiro “lift-and-shift”, uma agent() tradução é aceitável — indique isso e anote o caminho de otimização.

5. Produza a reescrita do Stagehand v3

Primeiro, verifique a API. Antes de escrever, confirme as assinaturas exatas que você está prestes a usar em relação ao pacote instalado (node_modules/@browserbasehq/stagehand tipos) ou https://docs.stagehand.dev/v3. Os mapeamentos abaixo são um instantâneo da versão 3.6.x; se houver alguma diferença na versão instalada, a versão instalada prevalece. Em seguida, gere um código TypeScript executável. Sempre:

• import { Stagehand } from "@browserbasehq/stagehand"; e import { z } from "zod"; ao extrair.
• Obtenha a página por meio de const page = stagehand.context.pages()[0];.
• Chame métodos de IA na instância: stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — nunca page.act(...).
• Defina o modelo como uma "provider/model" string.
• O padrão é env: "BROWSERBASE"; exibir env: "LOCAL" como opção de desenvolvimento.
• Passe segredos via variables e process.env, nunca codificados diretamente.
• await stagehand.init() no início, await stagehand.close() em um finally.

Inclua a configuração do projeto para que ele seja executado (veja os modelos abaixo).

6. Escreva o resumo da migração

Juntamente com o código, elabore um breve resumo:

• Variante detectada e as escolhas de determinismo feitas (quais etapas se tornaram determinísticas vs. IA vs. agente), com o raciocínio.
• Requer revisão humana — qualquer coisa que não tenha sido mapeada 1:1: perda de allowed_domains barreiras de segurança, lógica de ação personalizada, intenção do modelo secundário, sequências de tarefas ambíguas.
• Próximo passo recomendado — Browserbase Context para reutilização de autenticação, armazenamento em cache para produção ou o caminho assistido por rastreamento, caso o fluxo tenha sido opaco.

7. Ofereça o caminho assistido por rastreamento (somente se justificado)

Se a fonte for um único código grande e opaco agent(task=…), instável ou se sua reescrita não puder ser mapeada com confiança , ofereça o fluxo de trabalho assistido por rastreamento (trace-assisted.md): execute o original no Browserbase, extraia sessions.logs.liste reescreva com base no comportamento observado. Não execute nada sem a autorização do usuário.

Modelos de saída

package.json

{
  "name": "stagehand-migration",
  "type": "module",
  "scripts": { "start": "tsx index.ts" },
  "dependencies": {
    "@browserbasehq/stagehand": "^3.0.0",
    "dotenv": "^16.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": { "tsx": "^4.0.0", "typescript": "^5.0.0" }
}

Adicione "ai": "^5.0.0" (Vercel AI SDK) somente se uma ação personalizada de uso do navegador corresponder a um agente tool. Fixe a v5, não a v4 — o Stagehand 3.6.x inclui ai a v5 e classifica agent({ tools }) como a v5 ToolSet, em que o campo de esquema de uma ferramenta é inputSchema. O tool() emite parameters em vez disso e falhará na verificação de tipos em relação ao v5 do Stagehand ToolSet. Se você não puder controlar a versão ai , ignore o tool() auxiliar e passe um objeto simples { description, inputSchema: zodSchema, execute } — ele atende à v5 ToolSet , independentemente de qual ai principal for resolvido.

.env

BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
ANTHROPIC_API_KEY=...   # or the provider matching your model string

index.ts Esqueleto (decomposto, a forma preferida)

import "dotenv/config";
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    model: "anthropic/claude-sonnet-4-6",
  });
  await stagehand.init();
  try {
    const page = stagehand.context.pages()[0];

    await page.goto("https://example.com");          // deterministic skeleton
    await stagehand.act("…");                          // AI where the page varies
    const data = await stagehand.extract("…", z.object({ /* … */ }));  // structured reads

    console.log(data);
  } finally {
    await stagehand.close();
  }
}

main().catch((err) => { console.error(err); process.exit(1); });

Lista de verificação de validação (antes de declarar concluído)

• Os métodos de IA estão na instância (stagehand.act/extract/observe), e não na página.
• Página obtida por meio de stagehand.context.pages()[0].
• Modelo é uma "provider/model" string; a chave do provedor correspondente está em .env.
• extract usa um esquema Zod; zod está nas dependências.
• Os segredos utilizam variables + process.env; nada codificado estaticamente.
• init() / close() presente; close() em finally.
• Cada etapa de uso do navegador é considerada, posicionada deliberadamente no espectro do determinismo.
• O resumo da migração lista as opções de determinismo e os itens que “precisam de revisão humana”.

Erros comuns a evitar

• Copiar a sintaxe da v2 (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) de posts antigos do blog. Use a v3 — consulte as “Notas de versão” do mapeamento de API.
• Traduzir cada etapa para “act()” — navegue com page.goto e armazene em cache as etapas repetíveis por meio de observe→act; não gaste uma chamada ao LLM em cada ação.
• Definir tudo como padrão em agent() — isso apenas reproduz o não determinismo do uso do navegador em uma nova estrutura. Decomponha onde o fluxo for conhecido.
• Descartar silenciosamente o `allowed_domains` — o Stagehand não possui firewall de domínio; sinalize para revisão.
• Inventar opções do Browserbase/Stagehand — se não tiver certeza sobre um campo, verifique https://docs.stagehand.dev/v3 / https://docs.browserbase.com em vez de adivinhar.