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

Konvertieren Sie ein „browser-use“-Skript (Python) in ein idiomatisches Stagehand v3-Skript (TypeScript) auf Browserbase, wobei Sie bei jedem Schritt den richtigen Grad an Determinismus wählen, anstatt eine eins-zu-eins-Kopie mit Agenten zu erstellen.

Kernprinzip: „browser-use“ ist standardmäßig agentisch (das LLM entscheidet über jede Aktion). Mit Stagehand können Sie wählen, in welchem Umfang KI zum Einsatz kommen soll. Eine gute Migration ersetzt undurchsichtige Agenten-Schleifen durch eine überprüfbare, größtenteils deterministische Pipeline – wobei KI nur dort eingesetzt wird, wo die Seite tatsächlich unvorhersehbar ist. Dies ist eine Refaktorisierung mit Urteilsvermögen, keine Transpilation.

Quelle der Wahrheit & Versionen. Der dauerhafte Wert dieser Funktion liegt im Urteilsvermögen – dem Determinismus- Spektrum und der Entscheidung zwischen „Dekomponieren“ und „Agent“ – nicht in den API-Spezifikationen, die sich mit jedem Release ändern. Die hier aufgeführten Code-Zuordnungen sind eine Momentaufnahme, die anhand von „@browserbasehq/stagehand“ 3.6.x und „browser-use“ 0.13.x (2026-06) validiert wurde. Bei Konflikten haben die Live-Dokumente Vorrang – überprüfe stets anhand des installierten Pakets und dieser Quellen, bevor du Code ausgibst:

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

Wenn die Hauptversionsnummer des installierten Stagehand nicht 3 ist, betrachten Sie diese Funktion als rein konzeptionell und orientieren Sie sich bei jeder Signatur an der aktuellen Dokumentation.

Referenzdateien (bei Bedarf lesen)

• references/api-mapping.md — die mechanische Zuordnung von „browser-use“ zu „Stagehand“ : Variantenerkennung, die vollständige Funktionstabelle, Vorher-Nachher-Code, „Browserbase“-Plattformoptionen und Fallstricke der Version v3. Lies dies bei jeder nicht trivialen Konstruktion.
• references/determinism.md — So wählen Sie agent() vs act/extract/observe vs zwischengespeichert observe→act. Der Entscheidungsbaum. Lies dies, wenn du entscheidest, wie ein „Agent(task=…)“ übersetzt werden soll.
• references/trace-assisted.md — Der optionale Workflow „Auf Browserbase ausführen, Protokolle lesen, dann umschreiben“ für undurchsichtige/unzuverlässige Skripte.
• references/guide.md — Der Leitfaden zur Migration durch Menschen: Paradigmenwechsel, Funktionszuordnung, das Determinismus-Spektrum und ein empfohlener Migrationspfad.
• references/prompt.md — eine in sich geschlossene, toolunabhängige Version dieser Fähigkeit; füge sie zusammen mit einem Skript zur Browserbenutzung in einen beliebigen KI-Assistenten ein.
• EXAMPLES.md — Skriptpaare „vorher/nachher“.

Arbeitsablauf

1. Quelle beschaffen

Besorgen Sie sich das/die Browser-Use-Skript(e). Falls der Nutzer lediglich ein Skript beschrieben hat, fragen Sie nach der/den Datei(en). Beachten Sie das Ziel: TypeScript Stagehand auf Browserbase, sofern nicht anders angegeben.

Prüfen Sie zunächst den Umfang – ist dies überhaupt migrierbar? Nicht jede Browser-Use-Datei ist ein Agent(task=…) Skript. Wenn es sich bei der Quelle um „browser-use“ handelt, das als MCP-Server läuft (uvx browser-use --mcp, eine mcpServers Konfiguration), gibt es kein Stagehand-Äquivalent – kennzeichnen Sie es als außerhalb des Geltungsbereichs und erfinden Sie keines (siehe API-Mapping §3.7b). Wenn der „browser-use“-Aufruf in eine größere App eingebettet ist (ein Klassen-/Tool-Wrapper, eine Web-Route, eine Warteschlangenaufgabe), konvertiere nur die „browser-use“-Oberfläche und behalte die umgebenden App-Verbindungen bei – siehe API-Mapping §3.8.

2. Erkenne die „browser-use“-Variante

Unterscheide zwischen Legacy (vor 0.12), Stable und Rust Beta (nur wenn Importe aus browser_use.beta) – siehe api-mapping §1. Hinweis: Die klassische Top-Level- from browser_use import Agent, ChatBrowserUse ist in 0.13.x nach wie vor vorhanden – ChatBrowserUse allein ist kein Hinweis auf eine Beta-Version; nur ein browser_use.beta Import ist es. Alle Varianten werden identisch übersetzt; im Zweifelsfall daher mit der stabilen Zuordnung fortfahren. Legacy-Namen vor der Übersetzung normalisieren. Geben Sie an, welche Variante Sie gefunden haben.

3. Erstellen Sie eine Bestandsaufnahme des Skripts

Erstellen Sie eine strukturierte Bestandsaufnahme, bevor Sie TypeScript schreiben:

• Aufgabe(n) – die task= Zeichenkette(n); unterteilen Sie jede in die implizierten, geordneten Schritte.
• Modell — die Chat* Anbieter + Modell-ID.
• Browserkonfiguration – lokal vs. cdp_url/Browserbase; Headless-Modus; Proxys; user_data_dir/storage_state.
• Strukturierte Ausgabe – beliebige output_model_schema Pydantic-Modelle.
• Geheime Daten — sensitive_data, Verwendung von Umgebungsvariablen, Anmeldeabläufe.
• Sicherheitsvorkehrungen — allowed_domains, max_steps.
• Benutzerdefinierte Aktionen – @tools.action / Controller Funktionen und die Frage, ob es sich bei jeder einzelnen um einen deterministischen Nebeneffekt oder eine Agentenfähigkeit handelt.
• Einrichtung — initial_actions, sekundäre Modelle (page_extraction_llm, planner_llm).

4. Bestimmen Sie den Determinismusgrad pro Schritt

Wende für jeden Schritt aus der Liste den Entscheidungsbaum in determinism.md an:

• Zu einer bekannten URL navigieren → page.goto(url) auf der „Stagehand“-Seite (keine KI).
• Aktion auf der Seite → act("…"); falls sie sich wiederholt, observe() einmal, dann erneut ausführen act(action) (kein LLM-Aufruf).
• Daten lesen → extract("…", zodSchema).
• Wirklich offen → beibehalten stagehand.agent().execute(...) (eingeschränkt durch maxSteps/systemPrompt).

Standardmäßig auf Zerlegung, wenn der Ablauf bekannt ist; beibehalten agent() nur dort, wo er nicht bekannt ist. Für einen ersten „Lift-and-Shift“ ist eine originalgetreue agent() Übersetzung akzeptabel – weisen Sie darauf hin und vermerken Sie den Optimierungspfad.

5. Erstellen Sie die Stagehand-v3-Umschreibung

Überprüfen Sie zunächst die API. Vergewissern Sie sich vor dem Schreiben, dass die genauen Signaturen, die Sie verwenden wollen, mit dem installierten Paket übereinstimmen (node_modules/@browserbasehq/stagehand Typen) oder unter https://docs.stagehand.dev/v3. Die folgenden Zuordnungen stammen aus einem 3.6.x-Snapshot; sollten sich in der installierten Version Abweichungen ergeben, ist die installierte Version maßgebend. Erzeuge anschließend ausführbares TypeScript. Immer:

• import { Stagehand } from "@browserbasehq/stagehand"; und import { z } from "zod"; beim Extrahieren.
• Rufen Sie die Seite über const page = stagehand.context.pages()[0];.
• Rufen Sie KI-Methoden auf der Instanz auf: stagehand.act(...), stagehand.extract(...), stagehand.observe(...) — niemals page.act(...).
• Das Modell als "provider/model" Zeichenkette fest.
• Standardmäßig env: "BROWSERBASE"; zeige env: "LOCAL" als Entwicklungsoption an.
• Geheimnisse über variables und process.env, niemals fest codiert.
• await stagehand.init() zu Beginn, await stagehand.close() in einer finally.

Fügen Sie die Projekteinstellungen so ein, dass es läuft (siehe die Vorlagen unten).

6. Verfassen Sie die Zusammenfassung der Migration

Erstellen Sie neben dem Code eine kurze Zusammenfassung:

• Erkannte Variante und die getroffenen Entscheidungen zum Determinismus (welche Schritte wurden deterministisch vs. KI vs. Agent), mit Begründung.
• Muss von einem Menschen überprüft werden – alles, was nicht 1:1 zugeordnet werden konnte: fehlende allowed_domains Leitplanken, Logik benutzerdefinierter Aktionen, Absicht des Sekundärmodells, mehrdeutige Aufgabenzeichenfolgen.
• Empfohlener nächster Schritt – „Browserbase Context“ zur Wiederverwendung der Authentifizierung, Caching für die Produktion oder der trace-gestützte Pfad, falls der Ablauf undurchsichtig war.

7. Bieten Sie den trace-gestützten Pfad an (nur wenn gerechtfertigt)

Wenn die Quelle ein einziger großer und undurchsichtiger agent(task=…), unzuverlässig war oder sich Ihre Neuprogrammierung nicht sicher abbilden lässt, bieten Sie den trace-gestützten Workflow an (trace-assisted.md): Führen Sie das Original auf Browserbase aus, extrahieren Sie sessions.logs.listund schreiben Sie den Code anhand des beobachteten Verhaltens um. Führen Sie nichts ohne die Zustimmung des Benutzers aus.

Ausgabevorlagen

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

Füge "ai": "^5.0.0" (Vercel AI SDK) nur hinzu, wenn eine benutzerdefinierte Browser-Nutzungsaktion einem Agenten zugeordnet ist tool. Verwenden Sie v5, nicht v4 – Stagehand 3.6.x bündelt ai v5 und Typen agent({ tools }) als v5 ToolSet, wobei das Schema-Feld eines Tools „inputSchema“ lautet. Der v4- tool() gibt stattdessen parameters stattdessen und scheitert bei der Typüberprüfung gegen Stagehands v5 ToolSet. Wenn Sie die heraufgezogene ai Version nicht beeinflussen können, lassen Sie den tool() Helper und übergeben Sie ein einfaches Objekt { description, inputSchema: zodSchema, execute } — dieses erfüllt die Anforderungen von v5 ToolSet , unabhängig davon, welche ai Hauptkategorie aufgelöst wird.

.env

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

index.ts Skelett (zerlegt, die bevorzugte Form)

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

Validierungscheckliste (vor der Erklärung als „fertig“)

• KI-Methoden werden auf der Instanz angewendet (stagehand.act/extract/observe), nicht auf der Seite.
• Seite abgerufen über stagehand.context.pages()[0].
• Modell ist eine "provider/model" Zeichenkette; der passende Provider-Schlüssel befindet sich in .env.
• extract verwendet ein ZOD-Schema; zod befindet sich in den Abhängigkeiten.
• Geheimnisse verwenden variables + process.env; nichts ist fest codiert.
• init() / close() vorhanden; close() in finally.
• Jeder Schritt der Browser-Nutzung wird berücksichtigt und bewusst auf dem Determinismus-Spektrum eingeordnet.
• Die Migrationszusammenfassung listet Determinismus-Entscheidungen und Punkte auf, die „eine Überprüfung durch einen Menschen erfordern“.

Häufige Fehler, die es zu vermeiden gilt

• Das Kopieren der v2-Syntax (page.act(), stagehand.page, modelName/modelClientOptions, enableCaching) aus alten Blogbeiträgen. Verwenden Sie v3 – siehe „Versionshinweise“ im API-Mapping.
• Jeden Schritt in „act()“ übersetzen – navigieren Sie mit page.goto und speichere wiederholbare Schritte über observe→act; verschwenden Sie nicht bei jeder Aktion einen LLM-Aufruf.
• Alles standardmäßig auf „agent()“ setzen – das reproduziert lediglich den Nichtdeterminismus der Browser-Nutzung in einem neuen Framework. Zerlege den Ablauf dort, wo er bekannt ist.
• allowed_domains stillschweigend weglassen – Stagehand hat keine Domänen-Firewall; zur Überprüfung markieren.
• Neue Browserbase-/Stagehand-Optionen erfinden — wenn du dir bei einem Feld unsicher bist, schau lieber unter https://docs.stagehand.dev/v3 / https://docs.browserbase.com nach, anstatt zu raten.