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

Convierte un script de browser-use (Python) en un script idiomático de Stagehand v3 (TypeScript) en Browserbase, eligiendo el nivel adecuado de determinismo en cada paso en lugar de generar una copia agente a agente.

Principio fundamental: «browser-use» es «agente» por defecto (el LLM decide cada acción). Stagehand te permite elegir en qué medida utilizar la IA. Una buena migración sustituye los bucles de agente opacos por un flujo de trabajo inspeccionable y mayoritariamente determinista, utilizando la IA solo cuando la página es realmente impredecible. Se trata de una refactorización con criterio, no de una transpilación.

Fuente de verdad y versiones. El valor duradero de esta habilidad es el criterio —el espectro de determinismo y la decisión entre descomposición y agente— y no los detalles de la API, que cambian con cada lanzamiento. Las correspondencias de código aquí presentadas son una instantánea validada con @browserbasehq/stagehand 3.6.x y browser-use 0.13.x (2026-06). En caso de conflicto, prevalecen los documentos en línea: comprueba siempre con el paquete instalado y estas fuentes antes de generar 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

Si la versión principal de Stagehand instalada no es la 3, considera esta habilidad como meramente conceptual y sigue la documentación en línea para cada firma.

Archivos de referencia (léelos según sea necesario)

• references/api-mapping.md — La correspondencia mecánica entre browser-use y Stagehand: detección de variantes, la tabla completa de características, código antes y después, opciones de la plataforma Browserbase y aspectos a tener en cuenta en la versión v3. Léelo para cualquier construcción que no sea trivial.
• references/determinism.md — Cómo elegir agent() vs act/extract/observe vs en caché observe→act. El árbol de decisión. Léelo a la hora de decidir cómo traducir un Agent(task=…).
• references/trace-assisted.md — El flujo de trabajo opcional «ejecútalo en Browserbase, lee los registros y luego reescribe» para scripts opacos o inestables.
• references/guide.md — La guía de migración para humanos: cambio de filosofía, correspondencia de funciones, el espectro del determinismo y una ruta de migración recomendada.
• references/prompt.md — una versión autónoma e independiente de herramientas de esta habilidad; pégala en cualquier asistente de IA junto con un script de uso del navegador.
• EXAMPLES.md — pares de scripts «antes y después».

Flujo de trabajo

1. Obtener la fuente

Consigue el script o scripts de uso del navegador. Si el usuario solo ha descrito un script, pídele los archivos. Ten en cuenta el destino: TypeScript Stagehand en Browserbase, a menos que se indique lo contrario.

En primer lugar, evalúa el alcance: ¿es siquiera migrable? No todos los archivos de uso del navegador son un Agent(task=…) script. Si el código fuente es «browser-use» ejecutándose como un servidor MCP (uvx browser-use --mcp, una mcpServers configuración), no existe un equivalente en Stagehand: márcalo como fuera de alcance, no inventes uno (véase mapeo de API, apartado 3.7b). Si la llamada a «browser-use» está incrustada en una aplicación más amplia (un envoltorio de clase/herramienta, una ruta web, una tarea en cola), convierte solo la superficie de «browser-use» y conserva el código de enlace de la aplicación circundante — véase mapeo de API, apartado 3.8.

2. Detectar la variante de «browser-use»

Identifica la versión heredada (anterior a la 0.12) frente a la estable frente a la beta de Rust (solo cuando las importaciones procedan de browser_use.beta) — véase «api-mapping», apartado 1. Nota: la superficie clásica de nivel superior from browser_use import Agent, ChatBrowserUse sigue vigente en la versión 0.13.x — ChatBrowserUse por sí sola no indica que se trate de una beta; solo lo indica una browser_use.beta import lo es. Todas las variantes se traducen de forma idéntica, así que, en caso de duda, procede con la asignación estable. Normaliza los nombres heredados antes de traducir. Indica qué variante has encontrado.

3. Haz un inventario del script

Elabora un inventario estructurado antes de escribir ningún código en TypeScript:

• Tarea(s): las task= cadena(s); divide cada una en los pasos ordenados que implica.
• Modelo: el Chat* proveedor + el ID del modelo.
• Configuración del navegador: local frente a cdp_url/Browserbase; modo sin interfaz gráfica; proxies; user_data_dir/storage_state.
• Salida estructurada: cualquier output_model_schema modelos Pydantic.
• Secretos — sensitive_data, uso de variables de entorno, flujos de inicio de sesión.
• Medidas de seguridad — allowed_domains, max_steps.
• Acciones personalizadas — @tools.action / Controller funciones, y si cada una de ellas es un efecto secundario determinista o una capacidad del agente.
• Configuración — initial_actions, modelos secundarios (page_extraction_llm, planner_llm).

4. Decidir el nivel de determinismo por paso

Para cada paso del inventario, aplica el árbol de decisión de determinism.md:

• Navegar a una URL conocida → page.goto(url) en la página de Stagehand (sin IA).
• Acción en la página → act("…"); si se repite, observe() una vez y luego volver a reproducir act(action) (sin llamada a LLM).
• Lectura de datos → extract("…", zodSchema).
• Verdaderamente abierto → mantener stagehand.agent().execute(...) (restringido con maxSteps/systemPrompt).

Por defecto, se recurre a la descomposición cuando se conoce el flujo; mantener agent() solo cuando no lo sea. Para una primera conversión directa, una agent() es aceptable; indícalo y señala la ruta de optimización.

5. Realizar la reescritura de Stagehand v3

En primer lugar, verifica la API. Antes de escribir, confirma las firmas exactas que vas a utilizar comparándolas con el paquete instalado (node_modules/@browserbasehq/stagehand tipos) o https://docs.stagehand.dev/v3. Las correspondencias que aparecen a continuación corresponden a una instantánea de la versión 3.6.x; si hay alguna diferencia con la versión instalada, prevalecerá la versión instalada. A continuación, genera código TypeScript ejecutable. Siempre:

• import { Stagehand } from "@browserbasehq/stagehand"; y import { z } from "zod"; al extraer.
• Obtén la página mediante const page = stagehand.context.pages()[0];.
• Llama a los métodos de IA en la instancia: stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — nunca page.act(...).
• Establecer el modelo como una "provider/model" cadena.
• Por defecto, env: "BROWSERBASE"; mostrar env: "LOCAL" como opción de desarrollo.
• Pasa los secretos a través de variables y process.env, nunca codificados de forma fija.
• await stagehand.init() al principio, await stagehand.close() en un finally.

Incluye la configuración del proyecto para que se ejecute (consulta las plantillas más abajo).

6. Redacta el resumen de la migración

Junto con el código, elabora un breve resumen:

• Variante detectada y opciones de determinismo elegidas (qué pasos se convirtieron en determinísticos frente a IA frente a agente), con el razonamiento correspondiente.
• Requiere revisión humana: cualquier elemento que no se haya asignado 1:1: pérdida de allowed_domains medidas de seguridad, lógica de acciones personalizadas, intención del modelo secundario, cadenas de tareas ambiguas.
• Siguiente paso recomendado: Browserbase Context para la reutilización de la autenticación, almacenamiento en caché para producción o la ruta asistida por trazas si el flujo era opaco.

7. Ofrecer la ruta asistida por traza (solo si está justificado)

Si el código fuente era un único archivo grande y opaco agent(task=…), era inestable o tu reescritura no se puede mapear con seguridad , ofrece el flujo de trabajo asistido por trazas (trace-assisted.md): ejecuta el original en Browserbase, extrae sessions.logs.listy reescribe a partir del comportamiento observado. No ejecutes nada sin el visto bueno del usuario.

Plantillas de salida

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

Añade "ai": "^5.0.0" (Vercel AI SDK) solo si una acción personalizada de uso del navegador se asigna a un agente tool. Fija la v5, no la v4: Stagehand 3.6.x incluye ai la v5 y las agent({ tools }) como la v5 ToolSet, donde el campo «schema» de una herramienta es inputSchema. El tool() emite parameters en su lugar y no superará la comprobación de tipos con respecto a la v5 de Stagehand ToolSet. Si no puedes controlar la versión ai , omite el tool() ayudante y pasa un objeto simple { description, inputSchema: zodSchema, execute } : cumple con la v5 ToolSet independientemente de cuál ai principal se resuelva.

.env

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

index.ts Esqueleto (descompuesto, la 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 comprobación de validación (antes de darlo por terminado)

• Los métodos de IA se aplican a la instancia (stagehand.act/extract/observe), no en la página.
• Página obtenida a través de stagehand.context.pages()[0].
• Modelo es una "provider/model" cadena de caracteres; la clave del proveedor correspondiente se encuentra en .env.
• extract utiliza un esquema Zod; zod se encuentra en «dependencies».
• Los secretos utilizan variables + process.env; nada está codificado de forma fija.
• init() / close() presentes; close() en finally.
• Se tiene en cuenta cada paso de uso del navegador, situado deliberadamente en el espectro del determinismo.
• El resumen de la migración enumera las opciones de determinismo y los elementos que «requieren revisión humana».

Errores comunes que hay que evitar

• Copiar la sintaxis de la v2 (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) de entradas antiguas del blog. Utiliza la v3; consulta las «Notas de versión» de api-mapping.
• Traducir cada paso a act() — navegar con page.goto y almacena en caché los pasos repetibles mediante observe→act; no gastes una llamada al LLM en cada acción.
• Establecer todo por defecto en agent(): eso solo reproduce el carácter no determinista del uso del navegador en un nuevo marco. Descompón el flujo cuando se conozca.
• Eliminar en silencio allowed_domains: Stagehand no tiene un cortafuegos de dominio; márcalo para su revisión.
• Inventar opciones de Browserbase/Stagehand: si no estás seguro de un campo, consulta https://docs.stagehand.dev/v3 / https://docs.browserbase.com en lugar de adivinar.