Computer-Use-Tool

Claude kann über das „computer use tool“ (Computer-Use-Tool) mit Computerumgebungen interagieren. Es bietet Screenshot-Funktionen sowie Maus- und Tastatursteuerung für die autonome Desktop-Interaktion.

Das Computer-Use-Tool ist ein von Anthropic definiertes „client toolset“ (Client-Toolset): Ein einziger Eintrag {"type": "computer_toolset_20260801"} in tools gibt Claude 17 Member-Tools wie screenshot, left_click, type und zoom, und deine Anwendung führt jeden Aufruf in einer Umgebung aus, die du kontrollierst. Es ist derzeit nicht in Claude Managed Agents verfügbar. Claudes Aufrufe sind tool_use-Blöcke, deren name das Member ist und die "toolset_name": "computer" tragen, oft mehrere pro Zug (eine „batch action“ bzw. Batch-Aktion).

Für Aufgaben, die innerhalb von Webseiten bleiben, passt das Browser-Use-Tool besser: Seine Member-Tools lesen die Seite selbst und agieren darauf, und es benötigt keine vollständige Desktop-Umgebung.

Sicherheitsüberlegungen

Computer Use birgt besondere Risiken, die sich von denen der Standard-API-Funktionen unterscheiden. Diese Risiken sind bei der Interaktion mit dem Internet erhöht.

Unter bestimmten Umständen folgt Claude Befehlen, die in Inhalten gefunden werden, selbst wenn sie deinen Anweisungen widersprechen. Beispielsweise könnten Anweisungen auf Webseiten oder in Bildern deine Anweisungen überschreiben oder Claude zu Fehlern verleiten. Triff Vorsichtsmaßnahmen, um Claude von sensiblen Daten und Aktionen zu isolieren, um Risiken im Zusammenhang mit Prompt-Injection zu vermeiden.

Anthropic hat das Modell darauf trainiert, diesen Prompt-Injections zu widerstehen, und eine zusätzliche Verteidigungsebene hinzugefügt. Wenn du die Computer-Use-Tools verwendest, scannen Klassifikatoren automatisch, was die Tools zurückgeben, etwa Screenshots, um potenzielle Prompt-Injections zu markieren. Wenn diese Klassifikatoren eine potenzielle Prompt-Injection erkennen, lenken sie das Modell automatisch dazu, zu prüfen, ob die Anweisung wirklich von dir stammt, bevor es danach handelt.

Dieser zusätzliche Schutz ist nicht für jeden Anwendungsfall ideal (zum Beispiel für Anwendungsfälle ohne einen Menschen im Prozess). Wenn du ihn deaktivieren möchtest, kontaktiere den Support. Die oben genannten Vorsichtsmaßnahmen bleiben auch mit diesen Klassifikatoren wichtig.

Informiere Endnutzer über relevante Risiken und hole ihre Zustimmung ein, bevor du Computer Use in deinen eigenen Produkten aktivierst.

Schnellstart

Füge das Computer-Use-Toolset als {"type": "computer_toolset_20260801"} zum tools-Array einer Messages API-Anfrage hinzu. Die Anfrage benötigt keinen Beta-Header. Dieses Beispiel deklariert außerdem das Text-Editor-Tool und das Bash-Tool, die Claude typischerweise zusammen mit Computer Use verwendet:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)

Wenn Claude auf dem Desktop agiert, hat die Antwort einen stop_reason von tool_use und enthält einen oder mehrere Member-tool_use-Blöcke, die jeweils ein Member-Tool benennen und "toolset_name": "computer" tragen. Mitten in dieser Aufgabe, nachdem Claude einen Screenshot des Desktops gesehen hat, könnte eine Antwort so aussehen:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Deine Anwendung führt jeden Aufruf der Reihe nach in deiner eigenen Umgebung aus, gibt einen tool_result-Block pro tool_use-Block zurück und ruft die API erneut auf; So funktioniert Computer Use beschreibt diese Schleife, und der Rest dieser Seite zeigt, wie du sie implementierst.

So funktioniert Computer Use

1. 1

   Stelle Claude das Computer-Use-Tool und einen Nutzer-Prompt bereit

   • Füge das Computer-Use-Toolset (und optional weitere Tools) zum tools-Array deiner API-Anfrage hinzu.
   • Füge einen Nutzer-Prompt hinzu, der Desktop-Interaktion erfordert, zum Beispiel „Speichere ein Bild einer Katze auf meinem Desktop.“
2. 2

   Claude antwortet mit Member-Tool-Aufrufen

   • Claude beurteilt, ob das Agieren auf dem Desktop bei der Anfrage des Nutzers helfen kann.
   • Falls ja, antwortet Claude mit einem oder mehreren Member-tool_use-Blöcken wie screenshot, left_click oder type, die jeweils "toolset_name": "computer" tragen. Eine Antwort mit mehreren dieser Blöcke ist eine Batch-Aktion.
   • Die API-Antwort hat einen stop_reason von tool_use, was eine Tool-Nutzungsanfrage signalisiert.
3. 3

   Führe die Aufrufe der Reihe nach aus und gib Ergebnisse zurück

   • Iteriere der Reihe nach über jeden tool_use-Block in der Antwort. Verzweige für jeden anhand des Member-name zusammen mit toolset_name und führe diese Aktion mit dem input des Blocks auf deinem Container oder deiner virtuellen Maschine aus.
   • Setze die Konversation mit einer neuen user-Nachricht fort, die einen tool_result-Block pro tool_use-Block enthält, zugeordnet über tool_use_id und jeweils mit "toolset_name": "computer". Gib für screenshot und zoom ein Bild zurück; für die anderen Aktionen genügt ein kurzer Text wie OK.
   • Wenn eine Aktion fehlschlägt, gib für diesen Block is_error: true zurück und beantworte den Rest des Batches wie unter Batch-Aktionen beschrieben.
4. 4

   Claude fährt fort, bis die Aufgabe abgeschlossen ist

   • Claude analysiert die Tool-Ergebnisse, um festzustellen, ob weitere Aktionen nötig sind oder die Aufgabe abgeschlossen ist.
   • Wenn Claude feststellt, dass weitere Aktionen nötig sind, antwortet es mit einem weiteren tool_use-stop_reason, und du solltest zu Schritt 3 zurückkehren.
   • Andernfalls gibt es eine Textantwort an den Nutzer zurück.

Die Wiederholung der Schritte 3 und 4 ohne Nutzereingabe wird als „agent loop“ (Agentenschleife) bezeichnet (das heißt, Claude antwortet mit einer Tool-Nutzungsanfrage und deine Anwendung antwortet Claude mit den Ergebnissen der Auswertung dieser Anfrage).

Batch-Aktionen

Claude kann eine kurze Abfolge von Aktionen planen, etwa klicken, tippen und dann einen Screenshot aufnehmen, und sie zusammen in einer Antwort zurückgeben. Dies wird als Batch-Aktion bezeichnet; sie verwendet dieselbe Antwortform wie die parallele Tool-Nutzung, mit einem Unterschied: Du führst die Blöcke der Reihe nach statt gleichzeitig aus.

Eine Antwort mit einem Batch aus drei Aktionen sieht so aus:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Gib für jeden tool_use-Block einen tool_result-Block zurück, zugeordnet über tool_use_id, alle in der nächsten user-Nachricht. Jedes Ergebnis für ein Member-Tool muss "toolset_name": "computer" tragen; ein Ergebnis, das es weglässt oder ein anderes Toolset als sein tool_use-Block benennt, wird abgelehnt. Nur screenshot- und zoom-Ergebnisse benötigen ein Bild; für die anderen Member genügt eine kurze Textbestätigung wie OK (cursor_position gibt die Koordinaten als Text zurück):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Führe Blöcke der Reihe nach aus und stoppe beim ersten Fehler. Spätere Aktionen in einem Batch hängen meist von früheren ab: Das type in diesem Beispiel gibt Text in das ein, was der vorangehende Klick fokussiert hat. Führe die Blöcke sequenziell in der Reihenfolge aus, in der sie in content erscheinen, und wenn einer fehlschlägt, führe den Rest nicht aus. Jeder tool_use-Block benötigt dennoch ein tool_result, beantworte den Batch also wie folgt:

• Gib für jede erfolgreiche Aktion ihr normales Ergebnis zurück.
• Gib für die fehlgeschlagene Aktion is_error: true mit einer Textbeschreibung dessen zurück, was schiefgelaufen ist.
• Gib für jede spätere Aktion im Batch is_error: true mit genau diesem Text zurück (das Browser-Use-Tool verwendet seinen eigenen Halt-Text):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

Claude sieht dann, welche Aktionen erfolgreich waren, welche fehlgeschlagen ist und welche übersprungen wurden, und plant in seinem nächsten Zug neu. Eine Anfrage, die irgendeinen tool_use-Block im Batch unbeantwortet lässt, wird mit einem invalid_request_error abgelehnt, sodass eine Agentenschleife, die nur den ersten Block liest, bei ihrem nächsten Aufruf fehlschlägt. Wenn deine Anwendung einen Menschen bittet, folgenreiche Aktionen zu bestätigen, führe diese Prüfung vor der Ausführung jedes Blocks durch, da ein Batch eine mehrstufige Aktion innerhalb eines Zugs abschließen kann.

Claude beendet einen Batch typischerweise mit screenshot, damit es das Ergebnis beobachten kann, bevor es entscheidet, was als Nächstes zu tun ist. Wenn ein Batch nicht damit endet, kann deine Anwendung einen Screenshot als zusätzlichen image-Block an das letzte Ergebnis im Batch anhängen, sodass Claude immer den aktuellen Zustand des Bildschirms sieht. Das spart einen Roundtrip im Vergleich dazu, darauf zu warten, dass Claude danach fragt. Du kannst Claude auch per Prompt anweisen, jeden Batch mit einem Screenshot zu beenden (siehe Modellleistung durch Prompting optimieren).

Die Computerumgebung

Computer Use erfordert eine Sandbox-Computerumgebung, in der Claude sicher mit Anwendungen und dem Web interagieren kann. Diese Umgebung umfasst:

1. Virtuelles Display: Ein virtueller X11-Display-Server (mit Xvfb), der die Desktop-Oberfläche rendert, die Claude über Screenshots sieht und mit Maus-/Tastaturaktionen steuert.

2. Desktop-Umgebung: Eine leichtgewichtige UI mit Fenstermanager (Mutter) und Panel (Tint2) unter Linux, die Claude eine konsistente grafische Oberfläche zur Interaktion bietet.

3. Anwendungen: Vorinstallierte Linux-Anwendungen wie Firefox, LibreOffice, Texteditoren und Dateimanager, die Claude zur Erledigung von Aufgaben nutzen kann.

4. Tool-Implementierungen: Integrationscode, der Claudes abstrakte Tool-Anfragen (wie „Maus bewegen“ oder „Screenshot aufnehmen“) in tatsächliche Operationen in der virtuellen Umgebung übersetzt.

5. Agentenschleife: Ein Programm, das die Kommunikation zwischen Claude und der Umgebung abwickelt, Claudes Aktionen an die Umgebung sendet und die Ergebnisse (Screenshots, Befehlsausgaben) an Claude zurückgibt.

Wenn du Computer Use verwendest, verbindet sich Claude nicht direkt mit dieser Umgebung. Stattdessen übernimmt deine Anwendung Folgendes:

1. Sie empfängt Claudes Tool-Nutzungsanfragen
2. Sie übersetzt sie in Aktionen in deiner Computerumgebung
3. Sie erfasst die Ergebnisse (wie Screenshots und Befehlsausgaben)
4. Sie gibt diese Ergebnisse an Claude zurück

Aus Gründen der Sicherheit und Isolation führt die Referenzimplementierung all dies in einem Docker-Container mit geeigneten Port-Mappings zum Betrachten der Umgebung und zur Interaktion mit ihr aus.

So implementierst du Computer Use

Du aktualisierst eine bestehende computer_20251124-Integration? Beginne mit Migration von computer_20251124; der Rest dieses Abschnitts gilt sowohl für neue als auch für migrierte Integrationen.

Die Agentenschleife verstehen

Der Kern von Computer Use ist die „Agentenschleife“: ein Zyklus, in dem Claude Tool-Aktionen anfordert, deine Anwendung sie ausführt und die Ergebnisse an Claude zurückgibt. Die Schleife verwendet den Client, den du im Schnellstart erstellt hast, ein tools-Array, das nur das Computer-Use-Toolset deklariert, und den Helfer zur Verarbeitung von Tool-Aufrufen unter Das Computer-Use-Tool implementieren. Wenn du auch andere Tools deklarierst, etwa die Bash- und Text-Editor-Tools aus dem Schnellstart, verarbeite deren tool_use-Blöcke im selben Durchlauf; der Helfer beantwortet nur Computer-Use-Member-Aufrufe, und die Schleife behandelt einen Zug ohne beantwortete Aufrufe als abgeschlossen. Hier ist ein vereinfachtes Beispiel:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Füge Claudes Antwort zum Gesprächsverlauf hinzu
        messages.append({"role": "assistant", "content": response.content})

        # Führe die von Claude angeforderten Aktionen der Reihe nach aus und sammle die Ergebnisse
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Sende alle Ergebnisse in einer einzigen User-Nachricht an Claude zurück
        messages.append({"role": "user", "content": tool_results})

    return messages

Die Schleife läuft weiter, bis entweder Claude antwortet, ohne Tools anzufordern (Aufgabe abgeschlossen), oder das maximale Iterationslimit erreicht ist. Diese Schutzmaßnahme verhindert potenzielle Endlosschleifen, die zu unerwarteten API-Kosten führen könnten.

Modellleistung durch Prompting optimieren

1. Gib einfache, klar definierte Aufgaben vor und liefere explizite Anweisungen für jeden Schritt.
2. Claude nimmt manchmal Ergebnisse seiner Aktionen an, ohne sie explizit zu überprüfen. Um dies zu verhindern, kannst du Claude mit folgendem Prompt anweisen: After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. Manche UI-Elemente (wie Dropdowns und Scrollbalken) können für Claude mit Mausbewegungen schwierig zu bedienen sein. Wenn du das erlebst, versuche, das Modell per Prompt zur Verwendung von Tastenkürzeln anzuweisen.
4. Füge für wiederholbare Aufgaben oder UI-Interaktionen Beispiel-Screenshots und Tool-Aufrufe erfolgreicher Ergebnisse in deinen Prompt ein.
5. Wenn sich das Modell anmelden muss, gib ihm Benutzername und Passwort in deinem Prompt innerhalb von XML-Tags wie <robot_credentials>. Die Verwendung von Computer Use in Anwendungen, die eine Anmeldung erfordern, erhöht das Risiko schlechter Ergebnisse infolge von Prompt-Injection. Lies Jailbreaks und Prompt-Injections abschwächen, bevor du dem Modell Anmeldedaten gibst.
6. Platziere beim Aufbau des content-Arrays eines Nutzerzugs den Anweisungstext vor dem Screenshot-Bild. Die Zielbeschreibung bereitzustellen, bevor das Bild verarbeitet wird, verbessert die Klickgenauigkeit.
7. Claude verwendet die zoom-Aktion, um einen Bereich in voller Auflösung zu untersuchen, wenn es nach kleinem Text oder bestimmten UI-Elementen gefragt wird, die in der Standardauflösung des Screenshots nicht lesbar sind, etwa Dateinamen in einer Seitenleiste, Tab-Titel, Statusleistentext, Zeilennummern oder Button-Beschriftungen. Wenn Claude nicht zoomt, obwohl du es erwartest, frage nach einem bestimmten Bereich oder Element statt nach dem Bildschirm als Ganzem.
8. Wenn du möchtest, dass jede Batch-Aktion mit einem Screenshot endet, sage das im System-Prompt, zum Beispiel: End each group of actions with a screenshot so you can verify the result before continuing.

System-Prompts

Wenn du das Computer-Use-Tool in eine Anfrage aufnimmst, generiert die API einen Computer-Use-spezifischen System-Prompt. Er ähnelt dem System-Prompt für Tool-Nutzung, beginnt aber mit:

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

Wie bei der regulären Tool-Nutzung wird der vom Nutzer bereitgestellte system-Parameter weiterhin berücksichtigt und beim Aufbau des kombinierten System-Prompts verwendet.

Verfügbare Aktionen

Jede Aktion ist ein Member-Tool des Computer-Use-Toolsets: Claude benennt das Member in einem tool_use-Block, der "toolset_name": "computer" trägt, und das input des Blocks enthält nur die Parameter dieses Members, ohne action-Feld. Das Toolset hat 17 Member-Tools:

Beachte bei der Implementierung der Member Folgendes:

• Koordinaten sind in Screenshot-Pixeln. Jeder coordinate-, start_coordinate- und region-Wert sowie die Position, die cursor_position meldet, liegt im Pixelraum der Vollbild-Screenshots, die du zurückgibst, mit dem Ursprung oben links. Zoom-Bilder ändern das nicht: Nach einem zoom drückt Claude Koordinaten weiterhin im Raum des vollständigen Screenshots aus, nie relativ zum gezoomten Bild. Wenn du Screenshots vor der Rückgabe herunterskalierst, skaliere Claudes Koordinaten wieder hoch, bevor du sie auf das echte Display anwendest (siehe Screenshots an Bildlimits anpassen).
• Alle Member sind standardmäßig aktiviert, einschließlich zoom. Wenn deine Umgebung keine Zoom-Bilder erzeugen kann, halte das Member mit configs zurück (siehe Tool-Parameter), statt es aktiviert zu lassen und Fehler zurückzugeben. Wenn Claude ein Member aufruft, das du zurückgehalten hast oder nicht implementierst, gib für diesen Block ein tool_result mit is_error: true zurück.
• Verzweige anhand des Paars (toolset_name, name). toolset_name ist das, was einen Block als Computer-Aktion kennzeichnet: Ein benutzerdefiniertes Tool in derselben Anfrage kann den Namen eines Members teilen, und eine spätere Toolset-Version kann Member hinzufügen (siehe Client-Toolsets).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

Tool-Parameter

Der Toolset-Eintrag im tools-Array akzeptiert vier Parameter; die Regeln, die er mit dem Browser-Use-Toolset teilt, sind unter Client-Toolsets aufgeführt.

Dieser Eintrag hält zum Beispiel zoom für eine Umgebung zurück, die es nicht implementiert, und setzt einen Cache-Breakpoint an der Toolset-Definition:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Wenn deine Agentenschleife nur eine Aktion pro Roundtrip ausführen kann, setze disable_parallel_tool_use in tool_choice auf true; Claude gibt dann höchstens einen Member-tool_use-Block pro Zug zurück (siehe Parallele Tool-Nutzung deaktivieren).

Der Eintrag lehnt diese Parameter aus früheren Tool-Versionen ab, und eine Anfrage, die einen davon enthält, gibt einen invalid_request_error zurück:

• name: Member-Namen sind durch die Toolset-Version festgelegt.
• display_width_px, display_height_px und display_number: Koordinaten liegen immer im Pixelraum der Screenshots, die du zurückgibst.
• enable_zoom: Zoom ist ein Member-Tool, das du über configs steuerst.

Der Eintrag kann außerdem nicht in derselben Anfrage wie ein computer_20251124-Eintrag oder ein anderes Tool namens computer deklariert werden. Zu strict, input_examples, der Platzierung von defer_loading, tool_choice, Streaming und Aufrufer-Einschränkungen siehe Client-Toolsets.

Kombination mit Nachdenken

Um Computer Use mit Nachdenken zu kombinieren, siehe Nachdenken.

Computer Use mit anderen Tools erweitern

Um andere Tools neben Computer Use hinzuzufügen, nimm sie in dasselbe tools-Array auf. Der Abschnitt Schnellstart zeigt dieses Muster mit dem Bash-Tool und dem Text-Editor-Tool. Du kannst deine eigenen benutzerdefinierten Tool-Definitionen auf dieselbe Weise hinzufügen.

Für Aufgaben, die innerhalb von Webseiten bleiben, kannst du auch das Browser-Use-Tool in derselben Anfrage deklarieren: Die beiden Toolsets arbeiten unabhängig, jedes in seinem eigenen Koordinatensystem, und Aufrufe an Member, die einen Namen teilen, wie screenshot oder key, werden über toolset_name unterschieden.

Eine eigene Computer-Use-Umgebung bauen

Die Referenzimplementierung soll dir den Einstieg in Computer Use erleichtern. Sie enthält alle Komponenten, die nötig sind, damit Claude einen Computer verwenden kann. Du kannst jedoch deine eigene Umgebung für Computer Use nach deinen Bedürfnissen bauen. Du benötigst:

• Eine virtualisierte oder containerisierte Umgebung, die für Computer Use mit Claude geeignet ist
• Eine Implementierung der Aktionen des Computer-Use-Tools
• Eine Agentenschleife, die mit der Claude API interagiert und die tool_use-Ergebnisse mit deinen Tool-Implementierungen ausführt
• Eine API oder UI, die Nutzereingaben zum Starten der Agentenschleife ermöglicht

Das Computer-Use-Tool implementieren

Das Computer-Use-Tool ist als schemaloses Tool implementiert. Bei der Verwendung dieses Tools musst du kein Eingabeschema wie bei anderen Tools bereitstellen; das Schema ist in Claudes Modell eingebaut und kann nicht geändert werden.

1. 1

   Richte deine Computerumgebung ein

   Erstelle ein virtuelles Display oder verbinde dich mit einem bestehenden Display, mit dem Claude interagieren wird. Dies umfasst typischerweise die Einrichtung von Xvfb (X Virtual Framebuffer) oder einer ähnlichen Technologie.

2. 2

   Implementiere Aktions-Handler

   Erstelle Funktionen zur Behandlung jedes Aktionstyps, den Claude anfordern könnte:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Platzhalter-Bilddaten; ein echter Executor erfasst den Bildschirm und gibt die PNG-Bytes zurück
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot antwortet mit einem Bildblock statt Text: gib die Ergebnis-Content-Liste zurück
       return [
           {
               "type": "image",
               "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate ist optional; ohne Angabe wird dort geklickt, wo sich der Cursor bereits befindet
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Behandle weitere Aktionen nach Bedarf
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Verarbeite Claudes Tool-Aufrufe

   Extrahiere Tool-Aufrufe aus Claudes Antworten und führe sie aus:

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer 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 Computer-Toolset ist deklariert; leite andere Tools hierher, falls du sie hinzufügst
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # Ein String oder eine Liste von Content-Blöcken wie das Screenshot-Bild
                   result["content"] = handle_computer_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

4. 4

   Implementiere die Agentenschleife

   Verpacke die beiden vorherigen Schritte in eine Schleife, die die Ergebnisse zurücksendet und sich wiederholt, bis Claude keine Member-Tool-Aufrufe mehr zurückgibt; Die Agentenschleife verstehen zeigt diese Schleife in jeder Sprache.

Fehler behandeln

Melde eine fehlgeschlagene Aktion an Claude als tool_result mit is_error: true und einer kurzen Beschreibung, und füge "toolset_name": "computer" wie bei jedem anderen Member-Ergebnis hinzu. Wenn die fehlgeschlagene Aktion Teil einer Batch-Aktion war, beantworte die verbleibenden Blöcke im Batch mit dem dort gezeigten Halt-Text, statt sie auszuführen.

Zum Beispiel, wenn die Screenshot-Erfassung fehlschlägt:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

Verwende dieselbe Form für Koordinaten außerhalb der Display-Grenzen und für Aktionen, deren Ausführung fehlschlägt, mit einer Nachricht, die sagt, was schiefgelaufen ist.

Screenshots an Bildlimits anpassen

Screenshots und Zoom-Bilder, die du an das Computer-Use-Toolset zurückgibst, müssen bereits in die Bildgrößenlimits deines Modells passen: Das Toolset nimmt keine Display-Abmessungen entgegen und die API skaliert nicht für dich herunter, sodass ein übergroßes tool_result-Bild mit einem Validierungsfehler abgelehnt wird. Da Claude Koordinaten im Pixelraum des Bildes zurückgibt, das es sieht, behalte den verwendeten Skalierungsfaktor, damit du diese Koordinaten auf deinen Bildschirm zurückrechnen kannst.

Wenn dein Bildschirm größer als das Limit ist, skaliere jeden Screenshot vor der Rückgabe und rechne Claudes zurückgegebene Koordinaten in den ursprünglichen Bildschirmraum zurück. Da das Toolset keine Display-Abmessungen entgegennimmt, sind die Skalierung und die Koordinatenumrechnung in deinem Anwendungscode alles, was du brauchst:

import math

screen_width, screen_height = 1512, 982


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# Beim Aufnehmen eines Screenshots
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
screenshot = capture_and_resize(scaled_width, scaled_height)


# Beim Verarbeiten der Koordinaten von Claude diese wieder hochskalieren
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Wenn du eine Display-Auflösung wählst und Screenshots zurückgibst:

• Verwende für allgemeine Desktop-Aufgaben 1024x768 oder 1280x720; für Webanwendungen 1280x800 oder 1366x768.
• Vermeide Auflösungen über 1920x1080, um Leistungsprobleme zu verhindern.
• Kodiere Screenshots als base64-PNG oder -JPEG und erwäge, große Screenshots zu komprimieren, um die Leistung zu verbessern.
• Füge relevante Metadaten wie Zeitstempel oder Display-Zustand hinzu.
• Wenn du höhere Auflösungen verwendest, stelle sicher, dass Koordinaten genau skaliert werden.

Screenshot-Verlauf verwalten

Lange Agentenschleifen sammeln schnell Screenshots an (jeweils etwa 1.000–1.800 Eingabe-Token). Die Anfragelimits der API gelten ebenfalls. Sobald eine einzelne Anfrage mehr als 20 Bilder enthält, unterliegt jedes Bild darin einem strengeren Limit pro Seite. Eine Schleife, die ihren Screenshot-Verlauf behält, erreicht diese Anzahl innerhalb weniger Dutzend Züge. Skaliere daher entweder jeden Screenshot so, dass keine Seite 2000 px überschreitet, oder entferne ältere Screenshots, um 20 oder weniger in der Anfrage zu behalten.

Um Prompt-Caching wirksam zu halten und gleichzeitig den Kontext zu begrenzen:

• Setze einen cache_control-Breakpoint nach dem System-Prompt und den Tool-Definitionen sowie bis zu drei weitere auf den letzten tool_result-Block jedes der jüngsten Turns, und verschiebe sie mit jedem Turn weiter. Innerhalb einer Batch-Aktion wirken Markierungen auf mehreren Blöcken als ein einziger Breakpoint, zählen aber jeweils trotzdem zum Limit von vier. Verwende daher einen pro Turn.
• Entferne alte Screenshots in Batches und nicht einzeln in jedem Turn. Wenn du in jedem Turn einen Screenshot entfernst, ändert sich das Präfix in jedem Turn, und der Cache wird ungültig. Ein sinnvoller Standard ist, die letzten drei Screenshots zu behalten und alle 25 Turns auszudünnen, sodass das Präfix zwischen den Ausdünnungen byte-identisch bleibt. Wenn deine Screenshots auf einer Seite 2000 px überschreiten, wähle ein Intervall, bei dem jede Anfrage höchstens 20 Bilder enthält.
• Bei Claude Fable 5.1, Claude Opus 5.5 und Claude Sonnet 5.5 solltest du Screenshots nicht auf dem Client entfernen: Das Entfernen eines früheren Screenshots macht jeden späteren Thinking-Block ungültig, und zwar in jeder Anfrage, die diese Turns noch enthält. Skaliere Screenshots stattdessen auf höchstens 2000 px pro Seite und verwende serverseitiges Tool-Result-Clearing, um alte Screenshots aus dem Kontext zu entfernen. Wenn du dennoch ausdünnen musst, lass ab diesem Zeitpunkt prefix_mismatch_behavior: "drop_block" gesetzt. Nach jeder Ausdünnung setzt Claude ohne das seit dem entfernten Screenshot erzeugte Nachdenken fort, und zwar in dieser Anfrage und in jeder späteren. Bei Claude Sonnet 5.5 funktioniert block_binding nur mit thinking: {"type": "adaptive"}. Halte den Verlauf bei between_tools rein anhängend (append-only), oder entferne die Thinking-Blöcke ab dem bearbeiteten Turn.

Klickprobleme diagnostizieren

Wenn Klicks ihr Ziel verfehlen, ist die Ursache meist eine der folgenden:

Best Practices für die Implementierung befolgen

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

Von computer_20251124 migrieren

Das Upgrade von computer_20251124 auf das Toolset ist optional: Die unter Frühere Tool-Versionen für computer_20251124 aufgeführten Modelle akzeptieren es weiterhin mit seinem Beta-Header, sodass eine bestehende Integration funktioniert, bis du sie änderst. Claude 5.5 und neuere Modelle sind auf der Claude API und Google Cloud die Ausnahme: Dort akzeptieren sie nur das Toolset. Führe das Upgrade einer Integration durch, bevor du sie auf eines dieser Modelle umstellst. Auf Amazon Bedrock akzeptieren Claude Opus 5.5 und Claude Sonnet 5.5 weiterhin computer_20251124. Nimm für das Upgrade die folgenden Änderungen gemeinsam vor:

1. Entferne den Beta-Header. Streiche anthropic-beta: computer-use-2025-11-24 aus deinen Anfragen. Entferne in den SDKs den Parameter betas und rufe die Messages API über den Standard-Client statt über den Beta-Namespace auf.
2. Ändere den tools-Eintrag. Setze type auf computer_toolset_20260801 und lösche name, display_width_px, display_height_px, display_number und enable_zoom. Das Toolset lehnt jedes dieser Felder ab.
3. Entscheide, ob Zoom aktiviert bleiben soll. Zoom ist im Toolset standardmäßig aktiviert, während enable_zoom standardmäßig false ist. Wenn deine Umgebung Zoom nicht implementiert, füge "configs": {"zoom": {"enabled": false}} hinzu, um das bisherige Verhalten beizubehalten; andernfalls implementiere es (siehe Verfügbare Aktionen).
4. Verarbeite jeden Block in einem Zug. Aktualisiere deine Agentenschleife so, dass sie über jeden tool_use-Block in einer Antwort iteriert, statt nur den ersten zu lesen, und anhand des name des Blocks zusammen mit toolset_name statt anhand von input.action verzweigt. Member-Eingaben enthalten kein action-Feld mehr; die übrigen Felder sind unverändert.
5. Führe Blöcke der Reihe nach aus und verwende den Halt-Text. Führe die Blöcke sequenziell aus, stoppe beim ersten Fehler und beantworte die verbleibenden Blöcke mit Not executed: an earlier computer action in this turn failed., wie unter Batch-Aktionen beschrieben. Wenn deine Schleife noch keine Batches ausführen kann, erklärt Tool-Parameter, wie du Claude auf eine Aktion pro Zug beschränkst.
6. Gib toolset_name in Ergebnissen zurück. Füge "toolset_name": "computer" zu jedem tool_result hinzu, das einen Member-Aufruf beantwortet. Ergebnisse dürfen nur text- und image-Inhalte enthalten.
7. Unterstütze repeat bei key. Das key-Member akzeptiert eine optionale repeat-Anzahl von 1 bis 100. Ein Handler, der unbekannte Felder ignoriert, würde die Taste nur einmal drücken, sorge also dafür, dass dein key-Handler repeat berücksichtigt.
8. Skaliere Screenshots selbst. Das Toolset lehnt einen Screenshot oder ein Zoom-Bild, das die Bildlimits des Modells überschreitet, ab, statt es herunterzuskalieren. Skaliere vor der Rückgabe des Bildes und skaliere Koordinaten weiterhin wie unter Screenshots an Bildlimits anpassen beschrieben.
9. Entferne nicht unterstützte Optionen. Verschiebe ein etwaiges defer_loading aus dem Eintrag in configs, mit demselben Wert bei jedem aktivierten Member. Die übrigen bei Toolset-Einträgen nicht unterstützten Optionen sind unter Client-Toolsets aufgeführt.

Dies ist der tools-Eintrag vor der Änderung, gesendet mit dem Header anthropic-beta: computer-use-2025-11-24:

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Dies ist der tools-Eintrag nach der Änderung, gesendet ohne Beta-Header. Das configs-Objekt lässt Zoom deaktiviert, um dem früheren Eintrag zu entsprechen, der enable_zoom nicht setzt; lasse configs ganz weg, um den Standard zu übernehmen und Claude zoomen zu lassen:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

Das folgende Paar zeigt einen tool_use-Block vor und nach der Änderung. Der Aktionsname wandert von input.action nach name, und der Block erhält toolset_name:

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Frühere Tool-Versionen

Zwei frühere Versionen des Computer-Use-Tools bleiben in der Beta verfügbar: für bestehende Integrationen, für Modelle, die das Toolset nicht unterstützen, und auf Plattformen, auf denen das Toolset derzeit nicht verfügbar ist. Jede erfordert ihren Beta-Header bei jeder Anfrage, und ihre Parameter sind in der Beta-Messages-API-Referenz dokumentiert. Übergib den Header in den SDKs über den Parameter betas und verwende den Beta-Namespace; nur das Computer-Use-Tool benötigt den Header, nicht die Bash- oder Texteditor-Tools in derselben Anfrage.

Einschränkungen

1. Latenz: Die aktuelle „latency“ (Latenz) von Computer Use bei Mensch-KI-Interaktionen ist möglicherweise zu langsam im Vergleich zu regulären, von Menschen gesteuerten Computeraktionen. Konzentriere dich auf Anwendungsfälle, bei denen Geschwindigkeit nicht entscheidend ist (zum Beispiel Informationsbeschaffung im Hintergrund, automatisierte Softwaretests), in vertrauenswürdigen Umgebungen.
2. Genauigkeit und Zuverlässigkeit der Computer Vision: Claude kann Fehler machen oder halluzinieren, wenn es beim Generieren von Aktionen konkrete Koordinaten ausgibt. Claudes Ausgabe des zusammengefassten Nachdenkens kann dir helfen, die Überlegungen des Modells zu verstehen und mögliche Probleme zu erkennen; setze display: "summarized" in der Thinking-Konfiguration, da die Modelle, die das Toolset unterstützen, den Denktext standardmäßig weglassen.
3. Genauigkeit und Zuverlässigkeit der Tool-Auswahl: Claude kann beim Auswählen von Tools während der Generierung von Aktionen Fehler machen oder halluzinieren oder unerwartete Aktionen zur Problemlösung ausführen. Außerdem kann die Zuverlässigkeit geringer sein, wenn mit Nischenanwendungen oder mehreren Anwendungen gleichzeitig interagiert wird. Formuliere Prompts an das Modell sorgfältig, wenn du komplexe Aufgaben anforderst.
4. Zuverlässigkeit beim Scrollen: Die Scroll-Aktion unterstützt Richtungssteuerung (hoch, runter, links, rechts) und eine angegebene Menge. In Anwendungen, in denen Scrollen nicht wirkt, können Tastaturalternativen wie Page Down helfen.
5. Interaktion mit Tabellenkalkulationen: Verwende die feingranularen Maussteuerungsaktionen (left_mouse_down, left_mouse_up) und Kombinationen mit Modifikatortasten, um einzelne Zellen auszuwählen. Komplexe Tabellenoperationen können dennoch mehrere Versuche erfordern.
6. Kontoerstellung und Inhaltsgenerierung auf sozialen und Kommunikationsplattformen: Obwohl Claude Websites besucht, ist seine Fähigkeit, Konten zu erstellen, Inhalte zu generieren und zu teilen oder sich anderweitig auf Social-Media-Websites und -Plattformen als Mensch auszugeben, eingeschränkt.
7. Schwachstellen: Jailbreaks und Prompt-Injection können Computer Use wie jedes Frontier-KI-System beeinträchtigen, auch durch in Webseiten oder Bildern eingebettete Anweisungen; wende die Vorsichtsmaßnahmen unter Sicherheitsüberlegungen an.
8. Unangemessene oder illegale Aktionen: Gemäß den Nutzungsbedingungen von Anthropic darfst du Computer Use nicht einsetzen, um gegen Gesetze oder die Acceptable Use Policy zu verstoßen.

Überprüfe und verifiziere Claudes Computer-Use-Aktionen und -Protokolle stets sorgfältig. Verwende Claude nicht ohne menschliche Aufsicht für Aufgaben, die perfekte Präzision oder sensible Nutzerinformationen erfordern.

Datenaufbewahrung

Computer Use ist ein clientseitiges Tool. Alle Screenshots, Mausaktionen, Tastatureingaben und alle an einer Sitzung beteiligten Dateien werden in deiner Umgebung erfasst und gespeichert, nicht von Anthropic. Anthropic verarbeitet die Screenshot-Bilder und Aktionsanfragen in Echtzeit als Teil des API-Aufrufs. Die Aufbewahrung dieser API-Anfragen richtet sich nach API und Datenaufbewahrung.

Da deine Anwendung steuert, wo und wie Computer-Use-Daten gespeichert werden, ist Computer Use ZDR-fähig. Zur ZDR-Fähigkeit aller Funktionen siehe API und Datenaufbewahrung.

Preise

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

Overhead der Toolset-Definition: Die Deklaration von computer_toolset_20260801 mit seinen Standardmitgliedern fügt einer Anfrage etwa 4.500 Input-Token hinzu (etwa 4.520 bei Claude Fable 5, Claude Mythos 5, Claude Opus 5 und Claude Opus 4.8 sowie etwa 4.590 bei Claude Sonnet 5). Dies umfasst die Definitionen der Mitglieds-Tools und den System-Prompt für die Tool-Nutzung. Das Deaktivieren von zoom über configs entfernt etwa 410 dieser Token. Die genaue Anzahl für eine Anfrage wird in der Antwort unter usage ausgewiesen, und du kannst sie im Voraus mit dem Token-Counting-Endpunkt schätzen.

Frühere Tool-Versionen: Die folgenden Zahlen gelten für die Tool-Versionen computer_20251124 und computer_20250124, nicht für computer_toolset_20260801:

• System-Prompt-Overhead: 466–499 Token, die dem System-Prompt hinzugefügt werden
• Tool-Definition: etwa 735 Input-Token pro Tool-Definition (gemessen mit computer_20250124)

Zusätzlicher Token-Verbrauch:

• Screenshot- und Zoom-Bilder, die in Tool-Ergebnissen zurückgegeben werden, abgerechnet als Bild-Input (siehe Vision-Preisgestaltung)
• Ergebnisse der Tool-Ausführung, die an Claude zurückgegeben werden

Nächste Schritte

Compatibility