Browser-Use-Tool

Das Browser-Use-Tool ermöglicht es Claude, Webseiten in einem Browser, den deine Anwendung ausführt, zu navigieren, zu lesen und mit ihnen zu interagieren. Es arbeitet mit der Seite sowohl über ihre Struktur (den „accessibility tree" (Barrierefreiheitsbaum), Elemente, Formulare und Tabs) als auch über Pixel (Screenshots und Viewport-Koordinaten), während das Computer-Use-Tool mit einem ganzen Desktop allein über Screenshots und Koordinaten arbeitet. Es ist ein von Anthropic definiertes „client toolset" (Client-Toolset): Ein einziger browser_toolset_20260801-Eintrag in deinem tools-Array gibt Claude standardmäßig 27 „member tools" (Mitglieds-Tools), etwa navigate, read_page, left_click und screenshot, plus vier weitere (javascript_exec, file_upload, read_console und read_network), wenn du sie aktivierst. Deine Anwendung führt jeden Aufruf gegen ihre eigene Browser-Automatisierung aus; nichts läuft auf Anthropics Seite. Es ist derzeit nicht in Claude Managed Agents verfügbar. Diese Seite sagt „deine Anwendung" für den „agent loop" (Agentenschleife), der die Messages API aufruft, und „dein Executor" (Ausführungskomponente) für den Teil davon, der den Browser steuert und Tool-Ergebnisse erzeugt.

Wähle Browser Use statt Computer Use, wenn die Aufgabe innerhalb von Webseiten bleibt: Claude kann die Struktur einer Seite lesen, auf ein Element zusätzlich zur Koordinate auch per Referenz einwirken, Formularwerte direkt setzen und über Tabs hinweg arbeiten, und du musst keinen Desktop betreiben. Wenn Claude nur Seiten lesen muss, auf die du es verweisen kannst, oder Quellen im Web finden soll, sind das Web-Fetch-Tool und das Web-Search-Tool noch leichtgewichtiger, weil sie Server-Tools sind, die die API für dich ausführt, ohne dass ein Browser betrieben werden muss. Wähle stattdessen Browser Use, wenn Seiten ihren Inhalt mit JavaScript aufbauen oder die Aufgabe bedeutet, auf der Seite zu handeln, statt sie nur zu lesen.

Mit Browser Use liest Claude Live-Webseiten und handelt auf ihnen, daher ist alles, was eine Seite liefert, nicht vertrauenswürdige Eingabe, und die Aktionen, die Claude ausführt, können reale Auswirkungen haben. Lies Sicherheitsüberlegungen, bevor du deployst.



Schnellstart

Das Browser-Use-Tool ist auf der Claude API ohne Beta-Header verfügbar: Füge einen Eintrag vom Typ browser_toolset_20260801, ohne name, zum tools-Array einer Messages API-Anfrage hinzu.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    tools=[{"type": "browser_toolset_20260801"}],
    messages=[
        {
            "role": "user",
            "content": "Open example.com/docs and tell me how to get started.",
        }
    ],
)
print(response)

Claudes erste Antwort endet mit stop_reason: "tool_use" und enthält einen oder mehrere Member-tool_use-Blöcke, die jeweils ein Member-Tool in name benennen und "toolset_name": "browser" tragen:

{
  "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the documentation and read the page to find the getting-started instructions."
    },
    {
      "type": "tool_use",
      "id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "name": "navigate",
      "toolset_name": "browser",
      "input": { "url": "https://example.com/docs" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "name": "read_page",
      "toolset_name": "browser",
      "input": { "filter": "interactive" }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Dein Executor führt navigate aus, dann read_page, und deine Anwendung gibt in ihrer nächsten Anfrage ein tool_result pro Block zurück und wiederholt dabei toolset_name auf jedem. Das navigate-Ergebnis meldet den geladenen Tab in einem browser_state-Block; das read_page-Ergebnis ist Text, in dem jedes Element eine Referenz trägt:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Navigated to https://example.com/docs" },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            }
          ]
        }
      ]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "toolset_name": "browser",
      "content": [
        {
          "type": "text",
          "text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
        }
      ]
    }
  ]
}

Claude hält nun Referenzen, auf die es einwirken kann, sodass sein nächster Zug ref_2 anklicken kann, um die Getting-Started-Seite zu öffnen, ohne den Link zuerst in einem Screenshot finden zu müssen.



So funktioniert Browser Use

Browser Use läuft als Agent-Loop: Claude gibt Member-Tool-Aufrufe zurück, dein Executor führt sie gegen den Browser aus, und du gibst die Ergebnisse zurück, bis Claude in Text antwortet.

Hier ist ein Gerüst des Tool-Aufruf-Schritts dieses Loops in zwei Teilen. Zuerst stehen Stub-Member-Handler stellvertretend für deine Browser-Automatisierung. Fünf Member (navigate, read_page, left_click, type und screenshot) geben den Text zurück, oder bei screenshot den Image-Block, der zum Ergebnisinhalt wird, und der Dispatcher wirft einen Fehler für jeden Member, den er nicht implementiert.

# Platzhalter-Bilddaten; ein echter Executor erfasst den Viewport und gibt die PNG-Bytes zurück
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="


def navigate(url):
    return f"navigated to {url}"


def read_page():
    return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'


def click(target):
    # Ein Ziel ist eine Elementreferenz aus read_page oder find oder eine Viewport-Koordinate
    if target["type"] == "ref":
        return f"clicked {target['ref']}"
    return f"clicked at ({target['x']}, {target['y']})"


def type_text(text):
    return f"typed: {text}"


def capture_screenshot() -> list[ImageBlockParam]:
    # screenshot antwortet mit einem Bildblock statt Text: gib die Ergebnis-Inhaltsliste zurück
    return [
        {
            "type": "image",
            "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
        }
    ]


def handle_browser_action(name, tool_input):
    if name == "navigate":
        return navigate(tool_input["url"])
    elif name == "read_page":
        return read_page()
    elif name == "left_click":
        return click(tool_input["target"])
    elif name == "type":
        return type_text(tool_input["text"])
    elif name == "screenshot":
        return capture_screenshot()
    # Behandle weitere Aktionen nach Bedarf
    raise ValueError(f"Unknown or unimplemented member: {name}")

Der zweite Teil führt einen Batch der Reihe nach aus, leitet jeden Block an diese Handler weiter, wiederholt toolset_name auf jedem Ergebnis und wendet die Abbruchregel aus Batch-Aktionen an, wobei ein Handler-Fehler in ein Fehlerergebnis umgewandelt wird. Der Sampling-Loop, der ihn aufruft, ist der unter Den Agent-Loop verstehen gezeigte, mit dem Browser-Toolset in tools.

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # Nur das Browser-Toolset ist deklariert; leite andere Tools hierher, falls du sie hinzufügst
        if block.type != "tool_use" or block.toolset_name != "browser":
            continue
        result: ToolResultBlockParam = {
            "type": "tool_result",
            "tool_use_id": block.id,
            "toolset_name": "browser",
        }
        if failed:
            result["content"] = NOT_EXECUTED
            result["is_error"] = True
        else:
            try:
                # Ein String oder eine Liste von Inhaltsblöcken; ein echter Executor fügt außerdem einen
                # browser_state-Block zu Navigations- und Tab-Verwaltungsergebnissen hinzu
                result["content"] = handle_browser_action(block.name, block.input)
            except Exception as err:
                result["content"] = f"Error: {err}"
                result["is_error"] = True
                failed = True
        tool_results.append(result)
    return tool_results

Leite jeden Block anhand des Paars (toolset_name, name) weiter statt nur anhand von name, weil ein benutzerdefiniertes Tool in derselben Anfrage den Namen eines Members teilen kann; Client-Toolsets beschreibt die Teile dieses Vertrags, die beide Toolsets gemeinsam haben. Wenn Claude einen Member benennt, den dein Executor nicht implementiert, oder einen, den du deaktiviert hast, beantworte diesen Block mit einem Fehlerergebnis, statt ihn zu verwerfen.

Wenn du die Antwort per Streaming empfängst, kommt das input jedes Members als ein vollständiges input_json_delta statt als Fragmente an, warte also, bis der Zug beendet ist, bevor du den Batch ausführst.



Batch-Aktionen

Ein Zug mit mehreren Member-Aufrufen ist eine Batch-Aktion: Führe die Aufrufe in der Reihenfolge aus, in der sie erscheinen, stoppe beim ersten Fehlschlag und beantworte jeden späteren Aufruf mit is_error: true und dem exakten Text Not executed: an earlier action in this turn failed. Ein Batch verwendet dieselbe Antwortform wie parallele Tool-Nutzung; der Unterschied ist, dass du die Blöcke der Reihe nach statt gleichzeitig ausführst. Hier klickt Claude in einem Zug das zuvor gefundene Suchfeld an, tippt eine Abfrage und drückt Enter:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "left_click",
      "toolset_name": "browser",
      "input": { "target": { "type": "ref", "ref": "ref_3" } }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
      "name": "type",
      "toolset_name": "browser",
      "input": { "text": "install" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
      "name": "key",
      "toolset_name": "browser",
      "input": { "text": "Enter" }
    }
  ]
}

Deine Anwendung gibt drei tool_result-Blöcke in einer user-Nachricht zurück, die jeweils toolset_name und eine kurze Textbestätigung wie Clicked element ref_3. tragen. Das Drücken von Enter lädt eine Ergebnisseite, daher trägt das key-Ergebnis auch einen browser_state-Block mit der aktualisierten URL des Tabs (Tab-Kontext auf anderen Ergebnissen). Wäre der Klick stattdessen fehlgeschlagen, würde sein Ergebnis deinen Fehlertext tragen und die anderen beiden Ergebnisse den Abbruchtext, wie unter Fehler aus deinem Executor zurückgeben gezeigt.

Du musst nicht nach jedem Aufruf einen Screenshot zurückgeben. Claude beendet einen Batch typischerweise mit einem Beobachtungsaufruf (screenshot, read_page oder get_page_text), und deine Anwendung kann auch ihre eigene Beobachtung, etwa einen frischen Screenshot oder Accessibility-Tree, als zusätzlichen Content-Block an das letzte Ergebnis im Batch anhängen, um einen Roundtrip zu sparen. Weil ein Tab-Verwaltungsergebnis genau ein browser_state-Block sein muss, hänge sie an das letzte Ergebnis an, das kein Tab-Verwaltungsaufruf ist.

Wenn dein Executor nur einen Aufruf pro Roundtrip ausführen kann, setze disable_parallel_tool_use in tool_choice auf true, und Claude gibt höchstens einen Member-Aufruf pro Zug zurück, auf Kosten von mehr Roundtrips (Parallele Tool-Nutzung deaktivieren). Der Rest des Vertrags unter Batch-Aktionen für das Computer-Use-Tool gilt weiterhin, einschließlich eines tool_result für jedes tool_use in der nächsten user-Nachricht, mit zwei Ausnahmen: dem Abbruchtext und dem, was das content eines erfolgreichen Ergebnisses enthält. Der Ergebnisinhalt folgt stattdessen Member-Tools auf dieser Seite: Ein new_tab-, switch_tab-, close_tab- oder list_tabs-Ergebnis ist genau ein browser_state-Block ohne Text oder Bild (Tab-Verwaltungsergebnisse), und das Ergebnis jedes anderen Members darf seinem Text oder Bild einen browser_state-Block hinzufügen (Tab-Kontext auf anderen Ergebnissen). Wo Cache-Breakpoints innerhalb eines Batches wirksam werden, ist in der cache_control-Zeile der Tool-Parameter des Computer-Use-Tools beschrieben.



Ziele und Koordinaten

Member-Tools, die auf eine Position einwirken, nehmen ein target-Objekt entgegen, das entweder eine Viewport-Pixel-Koordinate oder eine Referenz auf ein Element ist, das read_page oder find zurückgegeben hat. Die Tabellen unter Member-Tools schreiben Target für einen Parameter, der beide Formen akzeptiert.

Koordinaten sind Viewport-Pixel, der Pixelraum eines screenshot des gesamten Viewports mit dem Ursprung oben links auf der gerenderten Seite; es gibt keinen umgebenden Desktop oder Fensterrahmen. Das Toolset deklariert keine Anzeigeabmessungen, und Claude leitet die Viewport-Größe aus den Screenshots ab, die du zurückgibst, halte sie also in einer einheitlichen Größe. Ein zoom ändert den Bezugsrahmen nicht, daher sind seine region und alle Koordinaten, die Claude nach dem Betrachten des gezoomten Bildes ausgibt, weiterhin Pixel des gesamten Viewports.

Screenshots müssen in die Bildlimits passen. Die API skaliert Toolset-Bilder nicht herunter: Ein Screenshot oder Zoom-Bild, das die Bildgrößenlimits deines Modells überschreitet oder das strengere Limit pro Bild, das gilt, sobald eine Anfrage mehr als 20 Bilder enthält, wird abgelehnt. Skaliere vor dem Zurückgeben und skaliere Claudes Koordinaten um den Kehrwert deines Faktors wieder hoch, bevor du sie weiterleitest (Screenshots passend zu den Bildlimits skalieren).

Elementreferenzen stammen aus read_page und find. Jedes Element in ihrer Ausgabe trägt ein Tag wie [ref_2], wie im Schnellstart-Ergebnis:

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]

Claude gibt eine Referenz als {"type": "ref", "ref": "ref_2"}-Ziel bei einem späteren Klick-, hover-, scroll_to-, form_input- oder file_upload-Aufruf zurück, oder als ref-Parameter bei read_page, um einen Teilbaum zu lesen. Dein Executor vergibt die Referenzen, hält die Zuordnung von jeder zum zugrunde liegenden Knoten (eine Accessibility-Knoten-ID, ein gespeicherter Selektor oder Gleichwertiges) und wirkt auf diesen Knoten ein, wenn eine Referenz zurückkommt.

Referenzen sind auf den Tab beschränkt, der sie erzeugt hat, und bleiben gültig, bis dieser Tab navigiert oder sich sein DOM wesentlich ändert. Die API kann eine veraltete oder unbekannte Referenz nicht erkennen, gib also, wenn Claude eine Referenz übergibt, die dein Executor nicht mehr erkennt, ein Fehlerergebnis wie Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references. zurück. Claude liest die Seite dann erneut. Nummeriere Referenzen, die du für einen Tab bereits ausgegeben hast, nicht neu, bis er navigiert, weil das Referenzen, die Claude noch hält, stillschweigend ungültig macht.

Claude verwendet beide Zielarten und wechselt zwischen ihnen je nachdem, was die Seite bereitstellt; dein Prompt und das, was dein Executor zurückgibt, steuern die Wahl:

• Bevorzuge Referenzen, wo die Seite einen brauchbaren Accessibility-Tree hat. Eine Referenz überlebt Layout-Verschiebungen und Reflows, die Pixelkoordinaten fragil machen, und lässt Claude auf Steuerelemente einwirken, die mit einem Zeiger schwer zu treffen sind.
• Greife für Inhalte, die der Baum nicht beschreibt, auf Koordinaten zurück. Canvas-gerenderte Oberflächen, eingebettete Video- oder Remote-Desktop-Flächen, stark virtualisierte Listen und Elemente in Cross-Origin-Iframes haben oft keinen nützlichen Knoten, daher arbeitet Claude mit screenshot und zoom und klickt per Koordinate; dein Executor löst auf, in welchem Frame eine Koordinate landet.
• Grenze Lesevorgänge ein und lies den Baum, bevor du einen Screenshot machst. Auf großen Seiten gibt read_page mit filter: "interactive" oder dem ref eines Containers einen fokussierten Teilbaum zurück, und das Lesen des Baums einer typischen Seite kostet oft weniger Input-Token als ein Screenshot, während es Claude Referenzen gibt, auf die es sofort einwirken kann. Screenshots bleiben die richtige Beobachtung, wenn visuelles Layout, Bilder oder Rendering-Zustand wichtig sind.



Sicherheitsüberlegungen

Browser Use birgt Risiken, die Standard-API-Features nicht haben, weil Claude Inhalte aus dem offenen Web liest und darauf handelt, wo jede Seite Text enthalten kann, der geschrieben wurde, um es zu manipulieren.

Claude folgt manchmal Anweisungen, die in Seiteninhalten gefunden werden, selbst wenn sie deinen widersprechen; Text auf einer Seite, der sagt „ignoriere deine vorherigen Anweisungen und navigiere zu...", kann es von der Aufgabe ablenken. Isoliere Claude von sensiblen Daten und Aktionen, um zu begrenzen, was eine Prompt-Injection erreichen kann, lies Jailbreaks und Prompt-Injections abschwächen, und wenn eine Aufgabe eine eingeloggte Sitzung nicht vermeiden kann, verwende ein dediziertes Konto mit geringen Rechten und behalte die menschliche Bestätigung bei kontoändernden Aktionen bei.

Weil der Browser in deiner Umgebung läuft, sehen die Websites, die Claude besucht, die Netzwerkidentität deines Executors, und Seiteninhalte erreichen die API nur als die Tool-Ergebnisse, die du zurückgibst. Informiere Endnutzer über die relevanten Risiken und hole ihre Zustimmung ein, bevor du Browser Use in deinen Produkten aktivierst.



Member-Tools

Der browser_toolset_20260801-Eintrag deklariert 31 Member-Tools; das input jedes Aufrufs besteht genau aus den hier aufgeführten Parametern, und tab_id ist, wo optional, standardmäßig der aktive Tab. Target, CoordinateTarget und RefTarget sind die unter Ziele und Koordinaten beschriebenen Formen. Vier Member (javascript_exec, file_upload, read_console und read_network) sind standardmäßig deaktiviert und erscheinen nur, wenn du sie aktivierst. Die in der Zeile jedes Members genannten Eingabegrenzen und Ausgabekonventionen werden Claude mitgeteilt, nicht von der API durchgesetzt, validiere also Eingaben (einschließlich Koordinaten gegen deinen Viewport) und wende die Konventionen in deinem Executor an.

Nur screenshot und zoom erfordern einen image-Block in ihrem Ergebnis, und die vier Tab-Verwaltungs-Member (new_tab, list_tabs, switch_tab und close_tab) geben genau einen browser_state-Block zurück (siehe Tab-Verwaltungsergebnisse). Jeder andere Member gibt einen text-Block zurück: entweder eine kurze Bestätigung wie Clicked element ref_2. oder die Ausgabe des Members. Jedes Ergebnis außer einem Tab-Verwaltungsergebnis darf auch einen image-Block tragen, typischerweise einen nach der Aktion aufgenommenen Screenshot, damit Claude das Resultat ohne separaten screenshot-Aufruf sieht; Batch-Aktionen zeigt, wo du einen in einem Batch anhängst. Ein Member-tool_result darf nur text-, image- und browser_state-Content-Blöcke enthalten.



Navigation und Aufnahme



Zeiger



Tastatur und Timing



Seiten lesen



Formulare und Dateien



Diagnose und Scripting



Tab-Verwaltung

Bei Erfolg gibt jeder davon genau einen browser_state-Block und keinen Text oder kein Bild zurück; siehe Tab-Verwaltungsergebnisse.



Das Toolset konfigurieren

Neben type akzeptiert der Toolset-Eintrag configs, cache_control und allowed_callers; die Regeln, die diese Felder mit dem Computer-Use-Toolset teilen, sind unter Client-Toolsets aufgeführt, und dieser Abschnitt behandelt die browserspezifischen Standardwerte. configs ist ein Objekt mit Member-Namen als Schlüsseln, und der Wert jedes Members akzeptiert zwei Felder:



Member-Tools aktivieren oder deaktivieren

Führe in configs nur die Member auf, die du ändern möchtest; jeder Member, den du weglässt, behält seinen Standard. Zum Beispiel schaltet ein Executor, der Konsolenlesevorgänge, aber keine Low-Level-Zeiger- oder Tastenhalte-Steuerung implementiert, read_console ein und hält drei Member zurück:

{
  "type": "browser_toolset_20260801",
  "configs": {
    "read_console": { "enabled": true },
    "left_mouse_down": { "enabled": false },
    "left_mouse_up": { "enabled": false },
    "hold_key": { "enabled": false }
  }
}

Ein deaktivierter Member verschwindet aus der Definition, die Claude sieht; das garantiert nicht, dass Claude ihn nie benennt, daher beantwortet dein Executor einen solchen Aufruf trotzdem mit einem Fehlerergebnis.



Mit anderen Tools kombinieren

Deklariere das Browser-Use-Tool neben deinen eigenen Tools und anderen von Anthropic bereitgestellten Tools im selben tools-Array. Ein benutzerdefiniertes Tool darf den Namen eines Members teilen (zum Beispiel dein eigenes navigate), weil toolset_name Claudes Aufrufe unterscheidet, aber kein anderer Eintrag darf browser heißen, und eine Anfrage darf nur einen Browser-Toolset-Eintrag enthalten.

Du kannst es auch neben dem Computer-Use-Tool deklarieren, entweder dem Toolset oder einer früheren Computer-Use-Tool-Version. Die beiden arbeiten unabhängig, jedes in seinem eigenen Koordinatenrahmen (hier Viewport-Pixel, dort Desktop-Screenshot-Pixel), und Claudes Aufrufe an Member, die einen Namen teilen, wie screenshot oder key, werden durch toolset_name unterschieden.



Optionale Member aktivieren

Vier Member-Tools sind standardmäßig deaktiviert: javascript_exec und file_upload, weil sie erweitern, wozu eine manipulierte Seite Claude bringen könnte, und read_console und read_network, weil nicht jeder Browser-Automatisierungs-Stack diese Logs liefern kann und sie erweitern, welche seitenkontrollierten Inhalte Claude erreichen. Aktiviere jedes davon mit configs (zum Beispiel "configs": {"file_upload": {"enabled": true}}) nur, wenn dein Executor es implementiert und die Aufgabe es benötigt.



Dateien hochladen

file_upload setzt die Dateien eines <input type="file">-Elements direkt, was zuverlässiger ist als das Bedienen eines nativen Dateiauswahldialogs. Sein target ist ausschließlich eine Referenz, weil der Aufruf die Identität des Elements benötigt, und es nimmt paths, document_ids oder beides entgegen:

• paths sind Dateipfade im Dateisystem des Executors, für Deployments, in denen der Executor die Dateien deiner Anwendung direkt lesen kann (dieselbe Bedingung, unter der du den path eines Downloads befüllst).
• document_ids sind Bezeichner für Dateien, die deine Anwendung für den Browser bereitgestellt hat, für Deployments, in denen er das nicht kann. Deine Anwendung definiert, was die Bezeichner bedeuten; beschränke ihre Auflösung so, wie du paths beschränkst, auf für diese Aufgabe bereitgestellte Dateien.

{
  "type": "tool_use",
  "id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
  "name": "file_upload",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "ref", "ref": "ref_12" },
    "paths": ["/home/user/uploads/summary.pdf"],
    "tab_id": "tab-2"
  }
}

Claude schreibt diese Pfade, während es nicht vertrauenswürdige Seiten liest, daher würde eine uneingeschränkte Implementierung einer bösartigen Seite erlauben, den Upload jeder Datei, die der Executor lesen kann, auf eine von der Seite kontrollierte Website zu lenken. Aktiviere den Member nur, wenn dein Executor jeden Pfad auflöst (Symlinks und ..-Segmenten folgend) und nichts außerhalb eines dedizierten, per Allowlist freigegebenen Upload-Verzeichnisses akzeptiert, das nur für die Aufgabe bestimmte Dateien enthält. Verwende dafür nicht das Download-Verzeichnis des Browsers wieder; wenn du das tust, wird jede Datei, die eine Seite den Browser herunterladen lässt, hochladbar.



JavaScript in der Seite ausführen

javascript_exec führt den Ausdruck, den Claude schreibt, im Kontext der Seite aus und gibt den Wert des letzten Ausdrucks als Text zurück; Claude schreibt einen Ausdruck, keine return-Anweisung. Der Code läuft mit den vollen Rechten der Seite, einschließlich ihrer Cookies, ihres Storage und ihrer Same-Origin-Anfragen. Aktiviere den Member nur in Sitzungen, die keine Zugangsdaten enthalten, halte die Domain-Allowlist aus Sicherheitsüberlegungen in Kraft, behandle den zurückgegebenen Wert als nicht vertrauenswürdige Eingabe und protokolliere den Code, den Claude ausgibt.



Konsolen- und Netzwerkaktivität lesen

read_console gibt die Konsoleneinträge des Tabs zurück und read_network seine Netzwerkanfragen, jeweils als Text mit einer Zeile pro Eintrag, angesammelt seit dem vorherigen Lesen dieses Tabs. Eine Konsolenzeile trägt einen Log-, Warn- oder Fehlereintrag; eine Netzwerkzeile trägt Methode, URL, Status, MIME-Typ und Timing. Einträge existieren erst ab dem Moment, in dem sich deine Browser-Automatisierung an den Tab angehängt hat, daher bedeutet ein leeres Ergebnis nicht, dass ein bereits geöffneter Tab keinen Traffic hatte.

Diese Member lassen Claude eine fehlerhaft funktionierende Seite diagnostizieren (eine fehlgeschlagene Anfrage hinter einem Spinner, ein Skriptfehler hinter einem toten Button), ohne wiederholte Screenshots. Konsolen- und Netzwerkeinträge sind seitenkontrolliert und enthalten oft Geheimnisse wie Token in Anfrage-URLs, schwärze also zugangsdatenähnliche Werte, die du nicht in Claudes Kontext haben möchtest, und kürze sehr lange Einträge, bevor du sie zurückgibst.



Tabs mit browser_state verfolgen

Claude adressiert Tabs über tab_id, deine Anwendung ist die maßgebliche Quelle dafür, welche Tabs existieren, und du meldest diesen Zustand in einem browser_state-Inhaltsblock, den Claude nie direkt sieht: Die API rendert den Text, den Claude daraus liest.

{
  "type": "browser_state",
  "tabs": [
    {
      "tab_id": "tab-1",
      "title": "Documentation",
      "url": "https://example.com/docs",
      "active": true
    },
    { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
  ]
}

• tabs ist das vollständige Inventar der nach dem Aufruf geöffneten Tabs, kein Delta. Es darf leer sein; wann immer es das nicht ist, trägt genau ein Eintrag "active": true.
• state_changes (hier nicht gezeigt) meldet Nebeneffekte des Aufrufs: einen tab_opened-Eintrag für jeden Tab, den der Aufruf geöffnet hat und der bei dessen Abschluss noch geöffnet ist, dessen tab_id auch in tabs erscheinen muss, sowie Download-Ereignisse. Lass das Feld weg, wenn es nichts zu melden gibt; ein leeres Array wird abgelehnt.
• Sende den Block nur bei Ergebnissen, die einen Browser-Member-Aufruf beantworten, höchstens einmal pro tool_result und niemals bei einem Ergebnis mit is_error: true. „Kein Tab-Zustand zu melden" drückst du aus, indem du den Block weglässt.
• Die API rendert tabs in Text für Claude, wie die nächsten beiden Abschnitte beschreiben; Download-Einträge in state_changes werden validiert, aber nicht gerendert.

Du vergibst die tab_id-Werte. Jeder stabile String funktioniert, etwa die Seitenkennung deiner Automatisierungsbibliothek oder dein eigener Zähler, solange du eine tab_id nicht wiederverwendest, während ein Tab mit dieser Kennung in einem früheren Ergebnis noch als geöffnet aufgeführt ist. Die API erzwingt diese Limits für den Block:

• Jede tab_id, jeder title und jede url darf höchstens 4.096 Zeichen lang sein, tab_id darf nicht leer sein, und keines davon darf Steuerzeichen (einschließlich Zeilenumbrüchen) oder Unicode-Zeilen- oder Absatztrennzeichen enthalten.
• Ein Block darf höchstens 100 Tabs und 200 Zustandsänderungen auflisten.
• Dieselben Limits gelten für die tab_id, die Claude an switch_tab und close_tab übergibt, weil die API sie in den Ergebnistext rendert; beantworte daher einen Aufruf, dessen tab_id sie verletzt, mit einem Fehlerergebnis statt mit einem browser_state-Block.



Ergebnisse der Tab-Verwaltung

Bei new_tab, switch_tab, close_tab und list_tabs ist der content eines erfolgreichen Ergebnisses genau ein browser_state-Block ohne Text oder Bild, und die API schreibt den Text, den Claude sieht. Der Block eines new_tab-Ergebnisses muss außerdem genau eine tab_opened-Zustandsänderung tragen, deren tab_id mit dem als active: true markierten Eintrag übereinstimmt.

Ein list_tabs-Ergebnis, dessen Block zwei Tabs auflistet, von denen der erste aktiv ist, wird wie folgt gerendert, wobei jede Zeile um zwei Leerzeichen eingerückt ist und (current) nur an den aktiven Tab angehängt wird:

Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs) (current)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Ein Fehlerergebnis für einen dieser Member ist das Gegenteil: gewöhnlicher Fehlertext in content, is_error: true und kein browser_state-Block.

Wenn Claude beispielsweise new_tab aufruft (sein input ist leer), öffnet dein Executor den Tab, macht ihn aktiv und gibt das Inventar mit einem tab_opened-Eintrag zurück:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
      "toolset_name": "browser",
      "content": [
        {
          "type": "browser_state",
          "tabs": [
            { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
            { "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
        }
      ]
    }
  ]
}

Claude sieht Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab. Melde die URL, unter der der Tab geöffnet wurde, wie hier, nicht eine, zu der er später weiterleitet; spätere Ergebnisse melden die dann aktuelle URL des Tabs.



Tab-Kontext bei anderen Ergebnissen

Bei jedem anderen Member ist der Block optional: Sende ihn, wenn sich die Menge der geöffneten Tabs, der aktive Tab oder der Titel oder die URL eines Tabs geändert hat oder wenn es state_changes zu melden gibt, und füge immer das vollständige tabs-Inventar bei. Wenn ein Ergebnis sowohl Text als auch einen browser_state-Block trägt, hängt die API eine Tab Context-Fußzeile an den Text dieses Ergebnisses an, durch eine Leerzeile von deinem Text getrennt, sodass Claude den neuen Zustand ohne separaten list_tabs-Aufruf erhält:

Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Executed on benennt den Tab, auf dem der Aufruf lief, also dessen tab_id-Eingabe, falls vorhanden, und andernfalls den aktiven Tab, und die Tab-Zeilen der Fußzeile tragen keine (current)-Markierung. Hänge diesen Text nicht selbst an; sende den strukturierten Block und lass die API ihn rendern. Die Fußzeile wird dedupliziert, sodass identischer Tab-Zustand bei späteren Ergebnissen nicht erneut gerendert wird und großzügiges Befüllen des Blocks nichts kostet.

In drei Fällen wird keine Fußzeile gerendert, selbst wenn der Block vorhanden ist:

• Jedes zoom-Ergebnis.
• Ein Ergebnis ohne text-Block (zum Beispiel ein screenshot-Ergebnis nur mit Bild). Für dieses Ergebnis wird nichts gerendert oder gemerkt; der Tab-Kontext erscheint beim nächsten Ergebnis, das sowohl Text als auch einen browser_state-Block trägt, füge also einen kurzen Textblock neben dem Bild hinzu, wenn Claude eine Tab-Änderung bei genau diesem Ergebnis sehen soll.
• Ein Ergebnis, dessen tabs-Liste leer ist, bei einem Aufruf, der keine tab_id trug, weil es keinen Tab zu benennen gibt.

Als Claude beispielsweise früher in dieser Sitzung auf den Link „Pricing" (ref_5) klickte, öffnete die Seite ihn in einem neuen Tab, den Claude nicht angefordert hatte, und ohne Meldung müsste Claude list_tabs aufrufen, um ihn zu entdecken. Gib die Bestätigung des Klicks plus einen Block zurück, dessen state_changes den geöffneten Tab benennt, und markiere den Tab, den dein Executor aktiv gelassen hat:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Clicked element ref_5." },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
        }
      ]
    }
  ]
}

Claude sieht Clicked element ref_5. gefolgt von der zuvor gezeigten Tab-Context-Fußzeile. Ein Tab, der während eines fehlgeschlagenen Aufrufs geöffnet wurde, erhält keinen tab_opened-Eintrag, weil Fehlerergebnisse kein browser_state tragen; er erscheint stattdessen im tabs-Inventar des nächsten erfolgreichen Ergebnisses. In einem Batch hängst du den Block an das Ergebnis des Aufrufs, während dessen die Änderung geschah, und gibst jedem erfolgreichen Tab-Verwaltungsergebnis seinen eigenen Block, selbst wenn ein früheres Ergebnis im selben Zug denselben Zustand gemeldet hat.



Downloads melden

Wenn ein Klick oder eine Navigation einen Datei-Download startet, melde ihn in state_changes beim Ergebnis des Aufrufs, während dessen er geschah, über Ergebnisse hinweg korreliert durch eine download_id, die du vergibst. Downloads laufen asynchron und können sich über mehrere Ergebnisse erstrecken, daher gibt es drei Ereignistypen:

Die API validiert diese Einträge, rendert sie aber nicht in Text, den Claude sieht; wenn Claude also mit der Datei arbeiten muss, erwähne den Dateinamen oder path zusätzlich im text-Block desselben Ergebnisses.

Ein Klick auf „Download price list (CSV)" (ref_8) im Pricing-Tab startet beispielsweise einen Download, sodass das Ergebnis des Klicks einen download_started-Eintrag mit der download_id "dl-1" und der URL der Datei trägt. Der Download wird abgeschlossen, während ein späterer screenshot-Aufruf läuft, sodass der content dieses Ergebnisses das Bild, einen Textblock wie Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes). und diesen browser_state-Block enthält, der den Abschluss unter derselben download_id meldet:

{
  "type": "browser_state",
  "tabs": [
    { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
    {
      "tab_id": "tab-2",
      "title": "Pricing",
      "url": "https://example.com/pricing",
      "active": true
    }
  ],
  "state_changes": [
    {
      "type": "download_completed",
      "download_id": "dl-1",
      "url": "https://example.com/pricing/price-list.csv",
      "path": "/home/user/downloads/price-list.csv",
      "size_bytes": 48213
    }
  ]
}

Download-Meldungen folgen diesen Regeln:

• Höchstens ein Eintrag pro download_id in einem einzelnen Block, sodass ein Download, der während desselben Aufrufs startet und endet, nur download_completed meldet.
• Sende niemals state_changes bei einem Ergebnis mit is_error: true; melde ein Download-Ereignis, das während eines fehlgeschlagenen Aufrufs auftrat, beim nächsten erfolgreichen Ergebnis.
• state_changes ist kein Inventar laufender Downloads; melde jedes Ereignis einmal.
• Jeder Eintrag trägt nur die Felder, die sein type deklariert. size_bytes ist eine nicht negative Ganzzahl, download_id ist nicht leer, und download_id, url, path und error sind jeweils höchstens 4.096 Zeichen lang, ohne Steuerzeichen oder Unicode-Zeilen- oder Absatztrennzeichen. Die url stammt vom entfernten Server und trägt nach Weiterleitungen oft signierte Query-String-Anmeldedaten, entferne also Query-Parameter, die du nicht in Claudes Kontext haben möchtest, und bereinige sie, bevor du sie meldest oder in einem Dateisystempfad verwendest.



Fehler behandeln

Melde Claude einen fehlgeschlagenen Aufruf als gewöhnliches Fehlerergebnis: is_error: true, Textinhalt, der sagt, was schiefging, toolset_name zurückgegeben und kein browser_state-Block.



Fehler aus deinem Executor zurückgeben

Formuliere Fehlertext spezifisch, denn Claude liest ihn und passt sich an: Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable. gibt Claude etwas, worauf es reagieren kann, wo ein bloßes Error: navigation failed das nicht tut. Weitere häufige Fälle:



Anfragefehler

Die API validiert den Toolset-Eintrag und jeden Member-tool_use- und tool_result-Block in der Konversation. Wenn einer fehlerhaft ist, gibt die API einen invalid_request_error zurück, bevor Claude läuft. In der folgenden Tabelle benennt die linke Spalte, was du gesendet hast.



Einschränkungen

• Plattformverfügbarkeit: Browser-Nutzung ist nur auf der Claude API verfügbar.
• Nur Streaming ganzer Eingaben: Wenn du streamst, kommt das input jedes Members als ein vollständiges input_json_delta an (Client-Toolsets).
• Elementreferenzen sind Best-Effort: Hochdynamische Seiten (virtualisierte Listen, Canvas-gerenderte Oberflächen, Seiten, die beim Scrollen neu rendern) stellen möglicherweise keine stabilen Referenzen bereit, und Claude greift dort auf Screenshots und Koordinatenklicks zurück.
• read_console und read_network hängen von deiner Browser-Automatisierung ab: Sie melden nur, was diese erfassen kann, und nur ab dem Moment, in dem sie sich an einen Tab angehängt hat.
• Allgemeine Agenten-Einschränkungen gelten: Latenz, Vision-Genauigkeit und Prompt-Injection-Risiken übertragen sich von der Computer-Nutzung (siehe die Einschränkungen des Computer-Use-Tools), und dessen Hinweise unter Modellleistung mit Prompting optimieren, Screenshot-Verlauf verwalten und Best Practices für die Implementierung befolgen (Aktionsverzögerungen, Aktionsvalidierung und Logging) gelten auch für Browser-Executors.



Preise und Datenaufbewahrung

„Browser use" (Browser-Nutzung) folgt der standardmäßigen Preisgestaltung für Tool-Nutzung. Bei Verwendung des Browser-Use-Tools gilt:

Overhead der Toolset-Definition: Die Deklaration von browser_toolset_20260801 mit seinen Standardmitgliedern fügt einer Anfrage etwa 6.600 Input-Token hinzu (etwa 6.610 bei Claude Fable 5, Claude Mythos 5, Claude Opus 5 und Claude Opus 4.8 sowie etwa 6.670 bei Claude Sonnet 5). Dies umfasst die Definitionen der Mitglieds-Tools und den System-Prompt für die Tool-Nutzung. Das Aktivieren aller vier optionalen Mitglieder fügt etwa 880 Token hinzu, und das Deaktivieren von Mitgliedern über configs verringert die Anzahl. Die genaue Anzahl für eine Anfrage wird im usage-Feld der Antwort ausgewiesen, und du kannst sie vorab mit dem Token-Counting-Endpunkt schätzen.

Zusätzlicher Token-Verbrauch:

• Screenshot- und Zoom-Bilder, die in Tool-Ergebnissen zurückgegeben werden, abgerechnet als Bild-Input (siehe Vision-Preisgestaltung)
• Text-Tool-Ergebnisse, die an Claude zurückgegeben werden, wie etwa Accessibility-Trees, Seitentext sowie Konsolen- oder Netzwerkeinträge

Die Browser-Sitzung, Downloads und hochgeladene Dateien bleiben in deiner Umgebung; die Screenshots, der Seitentext und der Tab-Zustand, die du zurückgibst, sind Teil des Inhalts deiner API-Anfrage und folgen der Standard-Aufbewahrungsrichtlinie oder deiner ZDR-Vereinbarung, falls du eine hast. Das Browser-Use-Tool ist ZDR-berechtigt; siehe API und Datenaufbewahrung für Aufbewahrungsfristen und Berechtigung über alle Funktionen hinweg.



Nächste Schritte