---
title: Computer-Use-Tool
url: https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool
description: Gib Claude mit dem Computer-Use-Tool, dem Client-Toolset computer_toolset_20260801, die Kontrolle über Screenshots, Maus und Tastatur einer Desktop-Umgebung.
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Claude Platform on AWS: beta
Amazon Bedrock: beta
Google Cloud: ga
Microsoft Foundry: beta
details:
- Auf der Claude API und Google Cloud unterstützen Claude 5.5 und neuere Modelle Computer Use nur über das Toolset `computer_toolset_20260801` und geben für die früheren Tool-Versionen `computer_20251124` und `computer_20250124` einen Fehler zurück. Wie du eine bestehende Integration umstellst, erfährst du unter [Migration von `computer_20251124`](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Für die Umstellung von `computer_20250124` siehe [Computer Use auf das Toolset umstellen](https://platform.claude.com/docs/de/models/haiku-5-5/migration-guide#computer-use-toolset) im Migrationsleitfaden für Claude Haiku 5.5.
- Auf Amazon Bedrock akzeptieren Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 die frühere Tool-Version `computer_20251124`, so wie es Claude Opus 5 und Claude Sonnet 5 tun.
- Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 und Claude Opus 4.5 unterstützen Computer Use nur über die frühere Tool-Version `computer_20251124`, die einen Beta-Header erfordert; siehe [Frühere Tool-Versionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
- Andere Plattformen als die Claude API und Google Cloud bieten derzeit nur die [früheren Beta-Tool-Versionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) an.
---
**Beginne mit den SDK-Toolsets:** Für `computer_toolset_20260801` haben die Python- und TypeScript-SDKs eine Computer-Toolset-Klasse, die sich in der Beta befindet. Beginne mit [einer Partner-Integration](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-sdk#partner-integrations) oder sieh dir den Abschnitt [Computer-Toolset](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-sdk#computer-toolset) auf der Seite zu den SDK-Toolsets an. Verwende diese Seite als Tool-Referenz oder wenn du die Tool-Aufrufe selbst verarbeitest.
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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets)): 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](https://platform.claude.com/docs/de/managed-agents/tools) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions)).
Für Aufgaben, die innerhalb von Webseiten bleiben, passt das [Browser-Use-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool) besser: Seine Member-Tools lesen die Seite selbst und agieren darauf, und es benötigt keine vollständige Desktop-Umgebung.
Computer Use ist auf der Claude API und [Google Cloud](https://platform.claude.com/docs/de/build-with-claude/claude-on-vertex-ai) als Toolset `computer_toolset_20260801` verfügbar; siehe [Kompatibilität](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#compatibility) für die unterstützten Modelle.
Bestehende `computer_20251124`-Integrationen funktionieren weiterhin auf den Modellen, die dafür unter [Frühere Tool-Versionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) aufgeführt sind, und frühere Tool-Versionen bleiben für Modelle und Plattformen, die das Toolset nicht unterstützen, in der Beta verfügbar. Informationen zum Upgrade findest du unter [Migration von `computer_20251124`](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124), die Beta-Header unter [Frühere Tool-Versionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
## 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.
Um Risiken zu minimieren, solltest du Vorsichtsmaßnahmen wie die folgenden in Betracht ziehen:
1. Verwende eine dedizierte virtuelle Maschine oder einen Container mit minimalen Berechtigungen, um direkte Systemangriffe oder Unfälle zu verhindern.
2. Vermeide es, dem Modell Zugriff auf sensible Daten wie Konto-Anmeldeinformationen zu geben, um Informationsdiebstahl zu verhindern.
3. Beschränke den Internetzugriff auf eine Allowlist von Domains, um die Exposition gegenüber bösartigen Inhalten zu reduzieren.
4. Bitte einen Menschen, Entscheidungen zu bestätigen, die bedeutsame Konsequenzen in der realen Welt haben könnten, sowie alle Aufgaben, die eine ausdrückliche Zustimmung erfordern, wie das Akzeptieren von Cookies, das Abschließen von Finanztransaktionen oder das Zustimmen zu Nutzungsbedingungen.
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](https://support.claude.com/en/). 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](https://platform.claude.com/docs/de/api/messages/create)-Anfrage hinzu. Die Anfrage benötigt keinen Beta-Header. Dieses Beispiel deklariert außerdem das [Text-Editor-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/text-editor-tool) und das [Bash-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/bash-tool), die Claude typischerweise zusammen mit Computer Use verwendet:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"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."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
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.
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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." }]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ComputerToolset20260801(),
new ToolTextEditor20250728(),
new ToolBash20250124(),
],
Messages =
[
new MessageParam
{
Role = Role.User,
Content = "Save a picture of a cat to my desktop.",
},
],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Save a picture of a cat to my desktop.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.ComputerToolset20260801;
// ...
import com.anthropic.models.messages.ToolBash20250124;
import com.anthropic.models.messages.ToolTextEditor20250728;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(ComputerToolset20260801.builder().build())
.addTool(ToolTextEditor20250728.builder().build())
.addTool(ToolBash20250124.builder().build())
.addUserMessage("Save a picture of a cat to my desktop.")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Save a picture of a cat to my desktop.'],
],
model: 'claude-opus-5-5',
tools: [
['type' => 'computer_toolset_20260801'],
[
'type' => 'text_editor_20250728',
'name' => 'str_replace_based_edit_tool',
],
[
'type' => 'bash_20250124',
'name' => 'bash',
],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
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." }
]
)
puts 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:
```json Output
{
"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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#how-computer-use-works) beschreibt diese Schleife, und der Rest dieser Seite zeigt, wie du sie implementierst.
***
## So funktioniert Computer Use
* Füge das Computer-Use-Toolset (und optional weitere Tools) zum `tools`-Array deiner API-Anfrage hinzu.
* Füge einen Benutzer-Prompt hinzu, der eine Desktop-Interaktion erfordert, zum Beispiel „Speichere ein Bild einer Katze auf meinem Desktop."
* Claude beurteilt, ob Aktionen auf dem Desktop bei der Anfrage des Benutzers helfen können.
* Falls ja, antwortet Claude mit einem oder mehreren Member-`tool_use`-Blöcken wie `screenshot`, `left_click` oder `type`, die jeweils `"toolset_name": "computer"` enthalten. Eine Antwort mit mehreren dieser Blöcke ist eine [Batch-Aktion](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions).
* Die API-Antwort hat einen `stop_reason` von `tool_use`, was eine Anfrage zur Tool-Nutzung signalisiert.
* Iteriere der Reihe nach über jeden `tool_use`-Block in der Antwort. Verteile 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions) beschrieben.
* Claude analysiert die Tool-Ergebnisse, um festzustellen, ob weitere Aktionen erforderlich sind oder die Aufgabe abgeschlossen wurde.
* Wenn Claude feststellt, dass weitere Aktionen erforderlich 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 Benutzer 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/parallel-tool-use), 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:
```json
{
"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):
```json
{
"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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool#batch-actions)):
```json
{
"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 mit einem Screenshot endet, kann deine Anwendung einen Screenshot als zusätzlichen `image`-Block an das letzte Ergebnis im Batch anhängen, damit 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting)).
### 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`](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124); der Rest dieses Abschnitts gilt sowohl für neue als auch für migrierte Integrationen.
Die [Computer-Use-Referenzimplementierung](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) ist ein vollständiges, funktionierendes Beispiel: eine für Computer Use geeignete [containerisierte Umgebung](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/Dockerfile), Implementierungen [der Computer-Use-Tools](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), eine [Agentenschleife](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py), die die Claude API aufruft und die Tools ausführt, sowie eine Weboberfläche für Container, Schleife und Tools.
### 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#quick-start) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#implement-the-computer-use-tool). 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:
```python Python
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
```
```typescript TypeScript
async function samplingLoop(
model: string,
messages: Anthropic.MessageParam[],
maxIterations = 10,
): Promise {
// Führe die Computer-Use-Agentenschleife aus, bis Claude keine Tools mehr anfordert
// oder das Iterationslimit erreicht ist.
for (let i = 0; i < maxIterations; i++) {
const response = await client.messages.create({
model,
max_tokens: 4096,
messages,
tools,
});
// Füge Claudes Antwort zum Gesprächsverlauf hinzu
messages.push({ role: "assistant", content: response.content });
// Führe alle von Claude angeforderten Tools aus und sammle die Ergebnisse
const toolResults = processToolCalls(response);
if (toolResults.length === 0) {
return messages; // No more tool use; task complete
}
// Sende die Tool-Ergebnisse für die nächste Iteration an Claude zurück
messages.push({ role: "user", content: toolResults });
}
return messages;
}
```
```csharp C#
async Task> SamplingLoop(
Model model,
List messages,
int maxIterations = 10
)
{
// Führe die Computer-Use-Agentenschleife aus, bis Claude keine Tools mehr anfordert
// oder das Iterationslimit erreicht ist.
for (var i = 0; i < maxIterations; i++)
{
var response = await client.Messages.Create(
new MessageCreateParams
{
Model = model,
MaxTokens = 4096,
Messages = messages,
Tools = tools,
}
);
// Füge Claudes Antwort zum Gesprächsverlauf hinzu
messages.Add(
new()
{
Role = Role.Assistant,
Content = response
.Content.Select(block => new ContentBlockParam(block.Json))
.ToList(),
}
);
// Führe alle von Claude angeforderten Tools aus und sammle die Ergebnisse
var toolResults = ProcessToolCalls(response);
if (toolResults.Count == 0)
{
return messages; // No more tool use; task complete
}
// Sende die Tool-Ergebnisse für die nächste Iteration an Claude zurück
messages.Add(new() { Role = Role.User, Content = toolResults });
}
return messages;
}
```
```go Go
// samplingLoop führt die Computer-Use-Agentenschleife aus, bis Claude keine
// Tools mehr anfordert oder das Iterationslimit erreicht ist.
func samplingLoop(ctx context.Context, model anthropic.Model, messages []anthropic.MessageParam, maxIterations int) ([]anthropic.MessageParam, error) {
for range maxIterations {
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: model,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
// Füge Claudes Antwort zum Gesprächsverlauf hinzu
messages = append(messages, response.ToParam())
// Führe die von Claude angeforderten Aktionen der Reihe nach aus und sammle die Ergebnisse
toolResults := processToolCalls(response)
if len(toolResults) == 0 {
return messages, nil // No more tool use; task complete
}
// Sende alle Ergebnisse in einer einzigen User-Nachricht an Claude zurück
messages = append(messages, anthropic.NewUserMessage(toolResults...))
}
return messages, nil
}
```
```java Java
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
List samplingLoop(Model model, List messages, int maxIterations) {
for (int i = 0; i < maxIterations; i++) {
Message response = client.messages().create(MessageCreateParams.builder()
.model(model)
.maxTokens(4096)
.messages(messages)
.addTool(COMPUTER_TOOLSET)
.build());
// Claudes Antwort zum Gesprächsverlauf hinzufügen
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(response.content().stream().map(ContentBlock::toParam).toList())
.build());
// Von Claude angeforderte Tools ausführen und Ergebnisse sammeln
List toolResults = processToolCalls(response);
if (toolResults.isEmpty()) {
return messages; // No more tool use; task complete
}
// Tool-Ergebnisse für die nächste Iteration an Claude zurücksenden
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults)
.build());
}
return messages;
}
```
```php PHP
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
function samplingLoop(string $model, array $messages, int $maxIterations = 10): array
{
global $client, $tools;
for ($i = 0; $i < $maxIterations; $i++) {
$response = $client->messages->create(
model: $model,
maxTokens: 4096,
messages: $messages,
tools: $tools,
);
// Füge Claudes Antwort zum Gesprächsverlauf hinzu
$messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);
// Führe alle von Claude angeforderten Tools aus und sammle die Ergebnisse
$toolResults = processToolCalls($response);
if ($toolResults === []) {
return $messages; // No more tool use; task complete
}
// Sende die Tool-Ergebnisse für die nächste Iteration an Claude zurück
$messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
}
return $messages;
}
```
```ruby Ruby
# Führe die Computer-Use-Agentenschleife aus, bis Claude keine Tools mehr anfordert
# oder das Iterationslimit erreicht ist.
def sampling_loop(model, messages, max_iterations: 10)
max_iterations.times do
response = CLIENT.messages.create(
model: model,
max_tokens: 4096,
messages: messages,
tools: TOOLS
)
# Füge Claudes Antwort zum Gesprächsverlauf hinzu
messages << { 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)
return messages if tool_results.empty? # No more tool use; task complete
# Sende alle Ergebnisse in einer einzigen User-Nachricht an Claude zurück
messages << { role: "user", content: tool_results }
end
messages
end
```
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 die 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. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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 ``. 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](https://platform.claude.com/docs/de/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks), 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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.`
Wenn du wiederholt auf eine klare Reihe von Problemen stößt oder im Voraus weißt, welche Aufgaben Claude erledigen muss, nutze den System-Prompt, um Claude explizite Tipps oder Anweisungen zu geben, wie die Aufgaben erfolgreich zu erledigen sind.
Führe bei Agenten, die sich über mehrere Sitzungen erstrecken, zu Beginn jeder Sitzung eine End-to-End-Verifizierung durch, nicht nur nach der Implementierung. Browserbasierte Prüfungen fangen Regressionen aus früheren Sitzungen ab, die eine reine Code-Review übersieht. Siehe [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) für Details.
### 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/define-tools#tool-use-system-prompt), 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:
| Member | Eingabe | Beschreibung |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screenshot` | Keine (`{}`) | Erfasst das gesamte Display und gibt es als Bild zurück. |
| `zoom` | `region`: `[x0, y0, x1, y1]`, die obere linke und untere rechte Ecke des zu untersuchenden Bereichs | Erfasst nur diesen Bereich des Displays in voller Auflösung und gibt ihn als Bild zurück, skaliert, sodass er in deine üblichen Screenshot-Abmessungen passt, bei erhaltenem Seitenverhältnis. So kann Claude kleinen Text oder dichte UI lesen, die in einem herunterskalierten Vollbild-Screenshot nicht lesbar sind. |
| `left_click` | `coordinate` (optional): `[x, y]`; `text` (optional): Modifikatortasten, die während des Klicks gehalten werden: `shift`, `ctrl`, `alt`, `super` (die Command- oder Windows-Taste) oder eine mit `+` verbundene Kombination wie `ctrl+shift` | Klickt die linke Maustaste bei `coordinate` oder an der aktuellen Cursorposition, wenn `coordinate` weggelassen wird. |
| `right_click`, `middle_click`, `double_click`, `triple_click` | Wie `left_click` | Andere Maustasten und Mehrfachklicks. |
| `left_click_drag` | `start_coordinate`: `[x, y]`; `coordinate`: `[x, y]`; `text` (optional): Modifikatortasten | Drückt bei `start_coordinate`, zieht zu `coordinate` und lässt los. |
| `mouse_move` | `coordinate`: `[x, y]` | Bewegt den Cursor ohne zu klicken, zum Beispiel zum Hovern. |
| `left_mouse_down`, `left_mouse_up` | Keine (`{}`) | Drückt oder löst die linke Maustaste an der aktuellen Cursorposition, für Ziehvorgänge, die `left_click_drag` nicht ausdrücken kann. Bewege den Cursor zuerst mit `mouse_move`. |
| `cursor_position` | Keine (`{}`) | Meldet die aktuelle `[x, y]`-Position des Cursors als Text. |
| `scroll` | `scroll_direction`: `"up"`, `"down"`, `"left"` oder `"right"`; `scroll_amount`: Anzahl der Scrollrad-Klicks; `coordinate` (optional): `[x, y]`; `text` (optional): Modifikatortasten | Scrollt bei `coordinate` oder an der aktuellen Cursorposition. |
| `type` | `text`: die zu tippende Zeichenkette | Tippt wörtlichen Text am aktuellen Tastaturfokus. |
| `key` | `text`: eine Taste oder eine mit `+` verbundene Kombination wie `"Return"`, `"ctrl+s"` oder `"alt+Tab"`; `repeat` (optional): 1 bis 100, Standard 1 | Drückt eine Taste oder Tastenkombination `repeat`-mal. |
| `hold_key` | `text`: eine Taste oder Kombination; `duration`: Sekunden, bis zu 300 | Hält eine Taste für die angegebene Dauer gedrückt. |
| `wait` | `duration`: Sekunden, bis zu 300 | Pausiert vor der nächsten Aktion, zum Beispiel während eine Anwendung lädt. |
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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
* **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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#tool-parameters)), 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets)).
Jedes Beispiel ist ein vollständiger `tool_use`-Block, wie er in Claudes Antwort erscheint.
Shift+Klick an einer Position, zum Beispiel um eine Auswahl zu erweitern. Anders als bei `hold_key` hält `text` die Modifikatoren nur für die Dauer dieses Klicks oder Scrollens:
```json
{
"type": "tool_use",
"id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [500, 300], "text": "shift" }
}
```
Von einem Punkt zu einem anderen ziehen:
```json
{
"type": "tool_use",
"id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
"name": "left_click_drag",
"toolset_name": "computer",
"input": {
"start_coordinate": [200, 300],
"coordinate": [600, 300]
}
}
```
Drei Klicks des Rads nach unten scrollen:
```json
{
"type": "tool_use",
"id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
"name": "scroll",
"toolset_name": "computer",
"input": {
"coordinate": [500, 400],
"scroll_direction": "down",
"scroll_amount": 3
}
}
```
Tab viermal drücken:
```json
{
"type": "tool_use",
"id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
"name": "key",
"toolset_name": "computer",
"input": { "text": "Tab", "repeat": 4 }
}
```
Hineinzoomen, um einen Bereich in voller Auflösung zu untersuchen:
```json
{
"type": "tool_use",
"id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
"name": "zoom",
"toolset_name": "computer",
"input": { "region": [100, 200, 400, 350] }
}
```
Die Cursorposition melden. Beantworte diesen Aufruf mit einem kurzen Textergebnis, das die Position in Screenshot-Pixeln angibt, zum Beispiel `X=512, Y=384`:
```json
{
"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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets) aufgeführt.
| Parameter | Erforderlich | Beschreibung |
| ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | Ja | `computer_toolset_20260801` |
| `configs` | Nein | Einstellungen pro Member, nach Member-Name geschlüsselt; jedes Member akzeptiert `enabled` (Standard `true` für alle 17, einschließlich `zoom`) und `defer_loading` (Standard `false`, für die [Tool-Suche](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading)), und Member, die du weglässt, behalten ihre Standardwerte. |
| `cache_control` | Nein | [Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching)-Breakpoint an der Toolset-Definition; nur am Eintrag. Ein Breakpoint an einem beliebigen `tool_use`- oder `tool_result`-Block in einem Batch wird am Ende dieses Batches wirksam; siehe [Tool-Nutzung mit Prompt-Caching](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions). |
| `allowed_callers` | Nein | Nur `["direct"]`. |
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:
```json
{
"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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)).
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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets).
### Kombination mit Nachdenken
Um Computer Use mit Nachdenken zu kombinieren, siehe [Nachdenken](https://platform.claude.com/docs/de/build-with-claude/thinking).
Für das frühere Tool `computer_20251124` legt internes Benchmarking auf den Modellen, die es verwenden, diese `effort`-Einstellungen nahe:
* **Claude Opus 4.7:** Verwende `high` als Standard; verwende `low` für Workloads mit hohem Durchsatz oder Kostensensibilität.
* **Claude Sonnet 4.6 und Claude Opus 4.6:** Verwende `medium` als Standard (bestes Verhältnis von Genauigkeit zu Kosten). Vermeide `max`, das Token-Kosten hinzufügt, ohne die Genauigkeit bei UI-Aufgaben zu verbessern. Auf diesen Modellen verbraucht `low` *weniger* Ausgabe-Token als das vollständige Deaktivieren des Nachdenkens (weniger Fehler bedeuten weniger Wiederholungen), was es zu einer starken Option für kostensensible Schleifen macht.
### Computer Use mit anderen Tools erweitern
Um andere Tools neben Computer Use hinzuzufügen, nimm sie in dasselbe `tools`-Array auf. Der Abschnitt [Schnellstart](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#quick-start) zeigt dieses Muster mit dem [Bash-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/bash-tool) und dem [Text-Editor-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/text-editor-tool). Du kannst deine eigenen [benutzerdefinierten Tool-Definitionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/define-tools) auf dieselbe Weise hinzufügen.
Für Aufgaben, die innerhalb von Webseiten bleiben, kannst du auch [das Browser-Use-Tool in derselben Anfrage deklarieren](https://platform.claude.com/docs/de/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools): 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](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) 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.
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.
Erstelle Funktionen zur Behandlung jedes Aktionstyps, den Claude anfordern könnte:
```python Python
# 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}")
```
```typescript TypeScript
// Platzhalter-Bilddaten; ein echter Executor erfasst den Bildschirm als PNG-Bytes
const PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot antwortet mit einem Bildblock statt mit Text
return [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: PLACEHOLDER_PNG,
},
},
];
}
function clickAt(x: number, y: number): string {
return `clicked at (${x}, ${y})`;
}
function clickAtCursor(): string {
return "clicked at the current cursor position";
}
function typeText(text: string): string {
return `typed: ${text}`;
}
function handleComputerAction(
action: string,
input: unknown,
): string | Anthropic.ImageBlockParam[] {
const params: object =
typeof input === "object" && input !== null ? input : {};
switch (action) {
case "screenshot":
return captureScreenshot();
case "left_click":
// coordinate ist im Toolset optional; ohne Angabe wird an der Cursorposition geklickt
if ("coordinate" in params && Array.isArray(params.coordinate)) {
const [x, y] = params.coordinate;
return clickAt(x, y);
}
return clickAtCursor();
case "type":
if ("text" in params) {
return typeText(String(params.text));
}
break;
}
// Behandle weitere Aktionen nach Bedarf
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Platzhalter-Bilddaten; ein echter Executor erfasst den Bildschirm und gibt die PNG-Bytes zurück
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
// screenshot antwortet mit einem Bildblock statt Text: gib die Ergebnis-Inhaltsliste zurück
List CaptureScreenshot() =>
[
new ImageBlockParam(
new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
),
];
string ClickAt(int x, int y) => $"clicked at ({x}, {y})";
string ClickAtCursor() => "clicked at the current cursor position";
string TypeText(string text) => $"typed: {text}";
ToolResultBlockParamContent HandleComputerAction(
string action,
IReadOnlyDictionary input
) =>
action switch
{
"screenshot" => CaptureScreenshot(),
// coordinate ist bei click-Membern optional; ohne sie wird an der Cursorposition geklickt
"left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
xy[0].GetInt32(),
xy[1].GetInt32()
),
"left_click" => ClickAtCursor(),
"type" => TypeText(input["text"].GetString()!),
// Behandle weitere Aktionen nach Bedarf
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG steht für eine echte Aufnahme: Ein Executor gibt den
// Bildschirm als base64-kodierte PNG-Daten zurück.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// captureScreenshot gibt einen Bildblock statt Text zurück.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
// textContent verpackt Text als tool_result-Inhalt.
func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{Text: text}},
}
}
func clickAt(x, y int) string {
return fmt.Sprintf("clicked at (%d, %d)", x, y)
}
func clickAtCursor() string {
return "clicked at the current cursor position"
}
func typeText(text string) string {
return fmt.Sprintf("typed: %s", text)
}
func handleComputerAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
switch action {
case "screenshot":
return captureScreenshot(), nil
case "left_click":
// coordinate ist optional; ohne sie wird dort geklickt, wo der Cursor bereits ist
coord, ok := params["coordinate"].([]any)
if !ok {
return textContent(clickAtCursor()), nil
}
if len(coord) == 2 {
x, xok := coord[0].(float64)
y, yok := coord[1].(float64)
if xok && yok {
return textContent(clickAt(int(x), int(y))), nil
}
}
case "type":
if text, ok := params["text"].(string); ok {
return textContent(typeText(text)), nil
}
// Behandle weitere Aktionen nach Bedarf
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Wird erreicht, wenn der Eingabe eines Members ein Feld fehlt oder ein Feld den falschen Typ hat
return nil, fmt.Errorf("invalid input for %s", action)
}
```
```java Java
/** Placeholder pixels; a real executor captures the screen and base64-encodes the PNG. */
static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
ToolResultBlockParam.Content captureScreenshot() {
ImageBlockParam image = ImageBlockParam.builder()
.source(Base64ImageSource.builder()
.mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
.data(PLACEHOLDER_PNG)
.build())
.build();
return ToolResultBlockParam.Content.ofBlocks(
List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
}
String clickAt(long x, long y) {
return "clicked at (" + x + ", " + y + ")";
}
String clickAtCursor() {
return "clicked at current cursor";
}
String typeText(String text) {
return "typed: " + text;
}
/** Runs one computer toolset member; {@code action} is the tool_use block's name. */
ToolResultBlockParam.Content handleComputerAction(String action, Map input) {
if (action.equals("screenshot")) {
return captureScreenshot(); // the one member here that answers with an image block
}
String output = switch (action) {
case "left_click" -> {
JsonValue coordinate = input.get("coordinate"); // optional on the toolset
if (coordinate == null) {
yield clickAtCursor();
}
List point = (List) coordinate.asArray().get();
long x = ((Number) point.get(0).asNumber().get()).longValue();
long y = ((Number) point.get(1).asNumber().get()).longValue();
yield clickAt(x, y);
}
case "type" -> typeText(input.get("text").asStringOrThrow());
// Weitere Aktionen nach Bedarf behandeln
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Platzhalter für echte PNG-Bytes; ein echter Executor erfasst den Bildschirm
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function captureScreenshot(): array
{
// screenshot antwortet mit einem Bildblock statt Text, gib daher die Ergebnis-Inhaltsliste zurück
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function clickAt(?array $coordinate): string
{
// left_click kann coordinate weglassen; dann landet der Klick dort, wo der Cursor bereits ist
if ($coordinate === null) {
return 'clicked at current cursor';
}
[$x, $y] = $coordinate;
return "clicked at ({$x}, {$y})";
}
function typeText(string $text): string
{
return "typed: {$text}";
}
function handleComputerAction(string $name, array $input): string|array
{
return match ($name) {
'screenshot' => captureScreenshot(),
'left_click' => clickAt($input['coordinate'] ?? null),
'type' => typeText($input['text']),
// Behandle weitere Aktionen nach Bedarf
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Platzhalter-Bilddaten; ein echter Executor erfasst den Bildschirm als PNG.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
# screenshot antwortet mit einem Bildblock statt mit Text
def capture_screenshot
[
{
type: "image",
source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
}
]
end
def click(coordinate = nil)
return "clicked at current cursor" if coordinate.nil?
x, y = coordinate
"clicked at (#{x}, #{y})"
end
def type_text(text)
"typed: #{text}"
end
def handle_computer_action(name, input)
case name
when "screenshot"
capture_screenshot
when "left_click"
# coordinate ist optional; ohne sie wird dort geklickt, wo der Cursor bereits ist
click(input[:coordinate])
when "type"
type_text(input[:text])
# Behandle weitere Aktionen nach Bedarf
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
Extrahiere Tool-Aufrufe aus Claudes Antworten und führe sie aus:
```python Python
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
```
```typescript TypeScript
const HALT_TEXT =
"Not executed: an earlier computer action in this turn failed.";
function computerResult(
toolUseId: string,
content: string | Anthropic.ImageBlockParam[],
isError?: boolean,
): Anthropic.ToolResultBlockParam {
return {
type: "tool_result",
tool_use_id: toolUseId,
toolset_name: "computer",
content,
is_error: isError,
};
}
function processToolCalls(
response: Anthropic.Message,
): Anthropic.ToolResultBlockParam[] {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
let failed = false;
for (const block of response.content) {
if (block.type !== "tool_use") {
continue;
}
if (block.toolset_name !== "computer") {
// Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools
// hierher weiter, falls du sie hinzufügst.
continue;
}
if (failed) {
// Ein Batch stoppt beim ersten Fehler; beantworte spätere Aktionen als nicht ausgeführt
toolResults.push(computerResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Ein String oder die Bildblock-Liste, die screenshot zurückgibt
const result = handleComputerAction(block.name, block.input);
toolResults.push(computerResult(block.id, result));
} catch (error) {
failed = true;
const message = error instanceof Error ? error.message : String(error);
toolResults.push(computerResult(block.id, `Error: ${message}`, true));
}
}
return toolResults;
}
```
```csharp C#
const string HaltText = "Not executed: an earlier computer action in this turn failed.";
List ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "computer")
{
// Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools
// hier weiter, falls du sie hinzufügst.
continue;
}
if (failed)
{
// Ein Batch stoppt beim ersten Fehler; beantworte spätere Aktionen, ohne sie auszuführen
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "computer",
}
);
continue;
}
try
{
// Ein String oder die Bildblock-Liste, die screenshot zurückgibt
var result = HandleComputerAction(toolUse.Name, toolUse.Input);
toolResults.Add(
new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "computer" }
);
}
catch (Exception e)
{
failed = true;
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = $"Error: {e.Message}",
IsError = true,
ToolsetName = "computer",
}
);
}
}
return toolResults;
}
```
```go Go
const notExecuted = "Not executed: an earlier computer action in this turn failed."
// computerToolResult erstellt das Ergebnis für eine Computer-Aktion. Anders als ein
// gewöhnliches Tool-Ergebnis muss es den Toolset-Namen zurückgeben.
func computerToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
result := anthropic.ToolResultBlockParam{
ToolUseID: toolUseID,
ToolsetName: anthropic.String("computer"),
Content: content,
}
if isError {
result.IsError = anthropic.Bool(true)
}
return anthropic.ContentBlockParamUnion{OfToolResult: &result}
}
// processToolCalls führt die Computer-Aktionen in Claudes Antwort der Reihe nach aus und
// erstellt ein tool_result pro tool_use-Block. Nach dem ersten Fehler überspringt es
// den Rest: Claude hat sie unter der Annahme geplant, dass die früheren Aktionen erfolgreich waren.
func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
var toolResults []anthropic.ContentBlockParamUnion
failed := false
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
// Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools hierher, falls du sie hinzufügst.
if variant.ToolsetName != "computer" {
continue
}
if failed {
toolResults = append(toolResults, computerToolResult(variant.ID, textContent(notExecuted), true))
continue
}
var input map[string]any
var content []anthropic.ToolResultBlockParamContentUnion
err := json.Unmarshal(variant.Input, &input)
if err == nil {
// Text oder der Bildblock, den screenshot zurückgibt
content, err = handleComputerAction(variant.Name, input)
}
if err != nil {
failed = true
content = textContent("Error: " + err.Error())
}
toolResults = append(toolResults, computerToolResult(variant.ID, content, err != nil))
}
}
return toolResults
}
```
```java Java
/** The exact text the toolset contract prescribes for member calls skipped after a failure. */
static final String HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";
/** Every result answering a computer toolset member echoes toolset_name. */
ToolResultBlockParam.Builder computerResult(ToolUseBlock toolUse) {
return ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.toolsetName("computer");
}
/**
* Run the computer actions in Claude's response in order and build one
* tool_result per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools hierher, falls du sie hinzufügst.
if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("computer"))) {
continue;
}
ToolUseBlock toolUse = block.asToolUse();
ToolResultBlockParam result;
if (failed) {
result = computerResult(toolUse).content(HALT_TEXT).isError(true).build();
} else {
try {
Map input =
(Map) toolUse._input().asObject().get();
// Ein String oder der Bildblock, den screenshot zurückgibt
ToolResultBlockParam.Content output = handleComputerAction(toolUse.name(), input);
result = computerResult(toolUse).content(output).build();
} catch (RuntimeException e) {
failed = true;
result = computerResult(toolUse).content("Error: " + e.getMessage()).isError(true).build();
}
}
toolResults.add(ContentBlockParam.ofToolResult(result));
}
return toolResults;
}
```
```php PHP
const HALT_TEXT = 'Not executed: an earlier computer action in this turn failed.';
function processToolCalls(Message $response): array
{
$toolResults = [];
$failed = false;
foreach ($response->content as $block) {
// Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools hierher, falls du sie hinzufügst.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
if ($failed) {
// Ein Batch stoppt beim ersten Fehler; die restlichen Aktionen werden ohne Ausführung beantwortet
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Ein String oder die Bildblock-Liste, die screenshot zurückgibt
$toolResults[] = [...$result, 'content' => handleComputerAction($block->name, $block->input)];
} catch (\Throwable $e) {
$failed = true;
$toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
}
}
return $toolResults;
}
```
```ruby Ruby
NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
# Führe die Computer-Aktionen in Claudes Antwort der Reihe nach aus und erstelle ein
# tool_result pro tool_use-Block. Nach dem ersten Fehler überspringe den Rest:
# Claude hat sie unter der Annahme geplant, dass die vorherigen Aktionen erfolgreich waren.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Dieses Beispiel deklariert nur das Computer-Toolset; leite andere Tools hierher,
# falls du sie hinzufügst.
next unless block.type == :tool_use && block.toolset_name == "computer"
result = { type: "tool_result", tool_use_id: block.id, toolset_name: "computer" }
if failed
result.update(content: NOT_EXECUTED, is_error: true)
else
begin
# Ein String oder die Bild-Content-Blöcke, die screenshot zurückgibt
result[:content] = handle_computer_action(block.name, block.input)
rescue => e
result.update(content: "Error: #{e.message}", is_error: true)
failed = true
end
end
tool_results << result
end
tool_results
end
```
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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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:
```json
{
"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](https://platform.claude.com/docs/de/build-with-claude/vision#evaluate-image-size) 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.
Die Limits variieren je nach Modell. Claude Opus 4.7 und spätere Modelle, einschließlich jedes Modells, das `computer_toolset_20260801` unterstützt, akzeptieren bis zu 2576 Pixel an der langen Kante und insgesamt 4784 visuelle Token (`⌈width / 28⌉ × ⌈height / 28⌉`, ungefähr 3,75 Megapixel); frühere Modelle akzeptieren bis zu 1568 Pixel an der langen Kante und insgesamt ungefähr 1,15 Megapixel (siehe [Auflösung und Token-Kosten](https://platform.claude.com/docs/de/build-with-claude/vision#evaluate-image-size) für die Stufe jedes Modells). Das folgende Beispiel verwendet die Limits von 1568 px / 1,15 MP der früheren Modelle. Für ein Modell der hochauflösenden Stufe richte die Größe am Limit der visuellen Token statt an einer Pixelgesamtzahl aus, zum Beispiel mit dem Resize-Helfer unter [Bild vor dem Hochladen skalieren](https://platform.claude.com/docs/de/build-with-claude/vision-coordinates#resize-your-image-before-uploading).
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:
```python Python
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)
```
```typescript TypeScript
const screenWidth = 1512;
const screenHeight = 982;
const MAX_LONG_EDGE = 1568;
const MAX_PIXELS = 1_150_000;
function getScaleFactor(width: number, height: number): number {
const longEdge = Math.max(width, height);
const totalPixels = width * height;
const longEdgeScale = MAX_LONG_EDGE / longEdge;
const totalPixelsScale = Math.sqrt(MAX_PIXELS / totalPixels);
return Math.min(1.0, longEdgeScale, totalPixelsScale);
}
// Beim Aufnehmen eines Screenshots
const scale = getScaleFactor(screenWidth, screenHeight);
const scaledWidth = Math.floor(screenWidth * scale);
const scaledHeight = Math.floor(screenHeight * scale);
// Skaliere das Bild auf die skalierten Abmessungen, bevor du es an Claude sendest
const screenshot = captureAndResize(scaledWidth, scaledHeight);
// Skaliere Claudes Koordinaten bei der Verarbeitung wieder hoch
function executeClick(x: number, y: number): void {
const screenX = x / scale;
const screenY = y / scale;
performClick(screenX, screenY);
}
```
```csharp C#
int screenWidth = 1512, screenHeight = 982;
double GetScaleFactor(int width, int height)
{
// Skalierungsfaktor berechnen, um die API-Beschränkungen einzuhalten.
int longEdge = Math.Max(width, height);
int totalPixels = width * height;
double longEdgeScale = 1568.0 / longEdge;
double totalPixelsScale = Math.Sqrt(1_150_000.0 / totalPixels);
return Math.Min(1.0, Math.Min(longEdgeScale, totalPixelsScale));
}
// Beim Aufnehmen eines Screenshots
double scale = GetScaleFactor(screenWidth, screenHeight);
int scaledWidth = (int)(screenWidth * scale);
int scaledHeight = (int)(screenHeight * scale);
// Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
var screenshot = CaptureAndResize(scaledWidth, scaledHeight);
// Beim Verarbeiten von Claudes Koordinaten diese wieder hochskalieren
void ExecuteClick(int x, int y)
{
double screenX = x / scale;
double screenY = y / scale;
PerformClick(screenX, screenY);
}
```
```go Go
func getScaleFactor(width, height int) float64 {
longest := float64(max(width, height))
area := float64(width * height)
return min(1.0, 1568/longest, math.Sqrt(1_150_000/area))
}
// ...
screenWidth, screenHeight := 1512, 982
// Beim Aufnehmen eines Screenshots
scale := getScaleFactor(screenWidth, screenHeight)
scaledWidth := int(float64(screenWidth) * scale)
scaledHeight := int(float64(screenHeight) * scale)
// Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
screenshot := captureAndResize(scaledWidth, scaledHeight)
// Beim Verarbeiten von Claudes Koordinaten diese wieder hochskalieren
executeClick := func(x, y int) {
performClick(float64(x)/scale, float64(y)/scale)
}
```
```java Java
static double getScaleFactor(int width, int height) {
return Math.min(
1.0,
Math.min(
1568.0 / Math.max(width, height),
Math.sqrt(1_150_000.0 / (width * height))
)
);
}
void main() {
int screenWidth = 1512, screenHeight = 982;
// Beim Aufnehmen eines Screenshots
double scale = getScaleFactor(screenWidth, screenHeight);
int scaledWidth = (int)(screenWidth * scale);
int scaledHeight = (int)(screenHeight * scale);
// Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
var screenshot = captureAndResize(scaledWidth, scaledHeight);
// Beim Verarbeiten von Claudes Koordinaten diese wieder hochskalieren
BiConsumer executeClick =
(x, y) -> performClick(x / scale, y / scale);
// ...
}
```
```php PHP
function getScaleFactor(int $width, int $height): float
{
return min(
1.0,
1568 / max($width, $height),
sqrt(1_150_000 / ($width * $height)),
);
}
$screenWidth = 1512;
$screenHeight = 982;
// Beim Aufnehmen eines Screenshots
$scale = getScaleFactor($screenWidth, $screenHeight);
$scaledWidth = (int)($screenWidth * $scale);
$scaledHeight = (int)($screenHeight * $scale);
// Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
$screenshot = captureAndResize($scaledWidth, $scaledHeight);
// Beim Verarbeiten von Claudes Koordinaten diese wieder hochskalieren
$executeClick = fn(int $x, int $y) => performClick($x / $scale, $y / $scale);
```
```ruby Ruby
def get_scale_factor(width, height)
[1.0, 1568.0 / [width, height].max, Math.sqrt(1_150_000.0 / (width * height))].min
end
screen_width, screen_height = 1512, 982
# Beim Aufnehmen eines Screenshots
scale = get_scale_factor(screen_width, screen_height)
scaled_width = (screen_width * scale).to_i
scaled_height = (screen_height * scale).to_i
# Bild vor dem Senden an Claude auf die skalierten Abmessungen verkleinern
screenshot = capture_and_resize(scaled_width, scaled_height)
# Beim Verarbeiten von Claudes Koordinaten diese wieder hochskalieren
execute_click = ->(x, y) { perform_click(x / scale, y / scale) }
```
**macOS-Retina-Displays** erfassen Screenshots mit einem Gerätepixelverhältnis von 2, sodass das Bild die doppelte Auflösung der logischen Bildschirmkoordinaten hat. Skaliere entweder den Screenshot vor dem Senden um den Faktor 2 herunter oder halbiere die Koordinaten, die Claude zurückgibt, bevor du den Klick ausführst.
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](https://platform.claude.com/docs/de/build-with-claude/vision#request-limits) 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](https://platform.claude.com/docs/de/build-with-claude/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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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, Claude Sonnet 5.5 und Claude Haiku 5.5 solltest du das Bereinigen auf dem Client vermeiden: Das Entfernen eines früheren Screenshots [macht jeden späteren Thinking-Block ungültig](https://platform.claude.com/docs/de/build-with-claude/thinking#preserved-in-conversation), und zwar in jeder Anfrage, die diese Turns noch enthält. Skaliere Screenshots stattdessen auf höchstens 2000 px pro Seite und verwende das serverseitige [Löschen von Tool-Ergebnissen](https://platform.claude.com/docs/de/build-with-claude/context-editing#tool-result-clearing), um alte Screenshots aus dem Kontext zu entfernen. Wenn du bereinigen musst, lass ab diesem Zeitpunkt [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/de/build-with-claude/thinking#preserved-thinking-controls) gesetzt; nach jeder Bereinigung fährt Claude ohne das seit dem entfernten Screenshot erzeugte Nachdenken fort, bei dieser Anfrage und jeder späteren. Bei Claude Sonnet 5.5 funktioniert `block_binding` nur mit `thinking: {"type": "adaptive"}`. Mit `between_tools` solltest du den Verlauf nur erweitern (append-only) oder die Thinking-Blöcke ab dem bearbeiteten Turn entfernen. Bei Claude Haiku 5.5 funktioniert `block_binding` nur mit `thinking: {"type": "adaptive"}`; mit `thinking: {"type": "disabled"}` solltest du den Verlauf nur erweitern (append-only) oder die Thinking-Blöcke ab dem bearbeiteten Turn entfernen.
### Klickprobleme diagnostizieren
Wenn Klicks ihr Ziel verfehlen, ist die Ursache meist eine der folgenden:
| Symptom | Wahrscheinliche Ursache | Versuche |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Klicks sind durchgehend in eine Richtung versetzt | Claudes Koordinaten, die im Pixelraum der von dir zurückgegebenen Screenshots liegen, werden ohne Skalierung auf ein Display anderer Größe angewendet | Skaliere jede Koordinate vor dem Klicken mit dem Verhältnis deiner Bildschirmgröße zu deiner Screenshot-Größe (siehe [Screenshots an Bildlimits anpassen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)); berücksichtige auf macOS-Retina-Displays das 2x-Gerätepixelverhältnis |
| Klicks landen im richtigen Bereich, verfehlen aber das Ziel | Das Ziel ist sehr klein, beim Herunterskalieren einer 4K+-Quelle gingen Details verloren oder das Seitenverhältnis wurde verzerrt | Lasse das `zoom`-Member aktiviert und implementiere es, damit Claude den Bereich in voller Auflösung untersuchen kann; erfasse mit niedrigerer DPI oder schneide auf den relevanten Bereich zu; behalte beim Skalieren das Seitenverhältnis bei |
| Claude klickt ein völlig falsches Element an | Mehrdeutige Anweisung oder visuell ähnliche Elemente in der Nähe | Verwende positionsbezogene Prompts („der blaue Submit-Button unten rechts“); zerlege die Interaktion in kleinere Schritte |
| Die Genauigkeit ist durchgehend schlecht | Auflösung zu niedrig | Versuche 1280x720 als Ausgangsbasis |
**Die Modellwahl beeinflusst die Klickpräzision.** Unter den Modellen, die das frühere Tool `computer_20251124` verwenden, ist Claude Sonnet 4.6 beim Klicken mechanisch präziser als Claude Opus 4.6 und robuster, wenn Screenshots stark herunterskaliert werden müssen. Claude Opus 4.7 verringert diesen Abstand: Seine Klickpräzision ist in etwa mit Sonnet 4.6 vergleichbar, und sein höheres Auflösungslimit bedeutet, dass weniger Herunterskalierung nötig ist.
### Best Practices für die Implementierung befolgen
Manche Anwendungen brauchen Zeit, um auf Aktionen zu reagieren:
```python Python
def click_and_wait(x, y, wait_time=0.5):
click_at(x, y)
time.sleep(wait_time) # Allow UI to update
```
```typescript TypeScript
async function clickAndWait(x: number, y: number, waitMs = 500): Promise {
clickAt(x, y);
await setTimeout(waitMs); // Allow UI to update
}
```
```csharp C#
static void ClickAndWait(int x, int y, double waitSeconds = 0.5)
{
ClickAt(x, y);
Thread.Sleep(TimeSpan.FromSeconds(waitSeconds)); // Allow UI to update
}
```
```go Go
func clickAndWaitFor(x, y int, wait time.Duration) {
clickAt(x, y)
time.Sleep(wait) // Allow UI to update
}
func clickAndWait(x, y int) {
clickAndWaitFor(x, y, 500*time.Millisecond)
}
```
```java Java
void clickAndWait(int x, int y) throws InterruptedException {
clickAndWait(x, y, 500);
}
void clickAndWait(int x, int y, long waitTimeMillis) throws InterruptedException {
clickAt(x, y);
Thread.sleep(waitTimeMillis); // Allow UI to update
}
```
```php PHP
function clickAndWait(int $x, int $y, float $waitSeconds = 0.5): void
{
clickAt($x, $y);
usleep((int) ($waitSeconds * 1_000_000)); // Allow UI to update
}
```
```ruby Ruby
def click_and_wait(x, y, wait_time: 0.5)
click_at(x, y)
sleep(wait_time) # Allow UI to update
end
```
Prüfe, ob angeforderte Aktionen sicher und gültig sind:
```python Python
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
```
```typescript TypeScript
const displayWidth = 1024;
const displayHeight = 768;
interface ActionParams {
coordinate?: [number, number];
}
function validateAction(actionType: string, params: ActionParams): [boolean, string | null] {
if (actionType === "left_click" && params.coordinate) {
const [x, y] = params.coordinate;
if (!(x >= 0 && x < displayWidth && y >= 0 && y < displayHeight)) {
return [false, "Coordinates out of bounds"];
}
}
return [true, null];
}
```
```csharp C#
const int DisplayWidth = 1024;
const int DisplayHeight = 768;
// ...
static (bool IsValid, string? Error) ValidateAction(string actionType, IReadOnlyDictionary parameters)
{
if (actionType == "left_click" && parameters.TryGetValue("coordinate", out JsonElement coordinate))
{
int x = coordinate[0].GetInt32();
int y = coordinate[1].GetInt32();
if (x is < 0 or >= DisplayWidth || y is < 0 or >= DisplayHeight)
{
return (false, "Coordinates out of bounds");
}
}
return (true, null);
}
```
```go Go
const (
displayWidth = 1024
displayHeight = 768
)
func validateAction(actionType string, params map[string]any) (bool, string) {
raw, hasCoordinate := params["coordinate"]
if actionType == "left_click" && hasCoordinate {
coord, ok := raw.([]any)
if !ok || len(coord) != 2 {
return false, "Invalid coordinate"
}
x, y := int(coord[0].(float64)), int(coord[1].(float64))
if !(0 <= x && x < displayWidth && 0 <= y && y < displayHeight) {
return false, "Coordinates out of bounds"
}
}
return true, ""
}
```
```java Java
static final int DISPLAY_WIDTH = 1024;
static final int DISPLAY_HEIGHT = 768;
record Validation(boolean valid, String error) {}
Validation validateAction(String actionType, Map params) {
if (actionType.equals("left_click") && params.containsKey("coordinate")) {
List coord = (List) params.get("coordinate").asArray().get();
long x = ((Number) coord.get(0).asNumber().get()).longValue();
long y = ((Number) coord.get(1).asNumber().get()).longValue();
if (!(0 <= x && x < DISPLAY_WIDTH && 0 <= y && y < DISPLAY_HEIGHT)) {
return new Validation(false, "Coordinates out of bounds");
}
}
return new Validation(true, null);
}
```
```php PHP
const DISPLAY_WIDTH = 1024;
const DISPLAY_HEIGHT = 768;
/** @return array{bool, ?string} */
function validateAction(string $actionType, array $params): array
{
if ($actionType === 'left_click' && isset($params['coordinate'])) {
[$x, $y] = $params['coordinate'];
if (!(0 <= $x && $x < DISPLAY_WIDTH && 0 <= $y && $y < DISPLAY_HEIGHT)) {
return [false, 'Coordinates out of bounds'];
}
}
return [true, null];
}
```
```ruby Ruby
DISPLAY_WIDTH = 1024
DISPLAY_HEIGHT = 768
def validate_action(action_type, params)
if action_type == "left_click" && params.key?(:coordinate)
x, y = params[:coordinate]
unless (0...DISPLAY_WIDTH).cover?(x) && (0...DISPLAY_HEIGHT).cover?(y)
return [false, "Coordinates out of bounds"]
end
end
[true, nil]
end
```
Führe ein Protokoll aller Aktionen zur Fehlerbehebung:
```python Python
import logging
def log_action(action_type, params, result):
logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")
```
```typescript TypeScript
function logAction(actionType: string, params: unknown, result: unknown): void {
console.error(
`Action: ${actionType}, Params: ${JSON.stringify(params)}, Result: ${JSON.stringify(
result
)}`
);
}
```
```csharp C#
static void LogAction(string actionType, object? parameters, object? result)
{
Console.Error.WriteLine($"Action: {actionType}, Params: {parameters}, Result: {result}");
}
```
```go Go
func logAction(actionType string, params map[string]any, result any) {
log.Printf("Action: %s, Params: %v, Result: %v", actionType, params, result)
}
```
```java Java
import static java.lang.System.Logger.Level.INFO;
static final System.Logger LOGGER = System.getLogger("computer-use");
void logAction(String actionType, Object params, Object result) {
LOGGER.log(INFO, "Action: {0}, Params: {1}, Result: {2}", actionType, params, result);
}
```
```php PHP
function logAction(string $actionType, array $params, mixed $result): void
{
error_log(sprintf(
'Action: %s, Params: %s, Result: %s',
$actionType,
json_encode($params),
json_encode($result),
));
}
```
```ruby Ruby
require "logger"
LOGGER = Logger.new($stderr)
def log_action(action_type, params, result)
LOGGER.info("Action: #{action_type}, Params: #{params}, Result: #{result}")
end
```
***
## Von `computer_20251124` migrieren
Das Upgrade von `computer_20251124` auf das Toolset ist optional: Die Modelle, die unter [Frühere Tool-Versionen](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) für `computer_20251124` aufgeführt sind, akzeptieren es weiterhin mit seinem Beta-Header, sodass eine bestehende Integration funktioniert, bis du sie änderst. Claude 5.5 und spätere 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, Claude Sonnet 5.5 und Claude Haiku 5.5 `computer_20251124`. Nimm für das Upgrade die folgenden Änderungen gemeinsam vor:
1. **Entferne den Beta-Header.** Entferne `anthropic-beta: computer-use-2025-11-24` aus deinen Anfragen. Entferne beim SDK `betas` (csharp, go: `Betas`; java: `.addBeta()`) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#available-actions)).
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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#batch-actions) beschrieben. Wenn deine Schleife noch keine Batches ausführen kann, erklärt [Tool-Parameter](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#tool-parameters), 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference#client-toolsets) aufgeführt.
Dies ist der `tools`-Eintrag vor der Änderung, gesendet mit dem Header `anthropic-beta: computer-use-2025-11-24`:
```json
{
"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:
```json
{
"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`:
```json
{
"type": "tool_use",
"id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
"name": "computer",
"input": { "action": "left_click", "coordinate": [500, 300] }
}
```
```json
{
"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](https://platform.claude.com/docs/de/api/beta-headers) bei jeder Anfrage, und ihre Parameter sind in der [Referenz der Beta-Messages-API](https://platform.claude.com/docs/de/api/beta/messages/create) dokumentiert. Übergib beim SDK den Header über `betas` (csharp, go: `Betas`; java: `.addBeta()`) und verwende den Beta-Namespace; nur das Computer-Use-Tool benötigt den Header, nicht die Bash- oder Texteditor-Tools in derselben Anfrage.
| Tool-Version | Beta-Header | Verwendung mit | Parameter |
| ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `computer_20251124` | `computer-use-2025-11-24` | Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 und Claude Opus 4.5; auf Amazon Bedrock außerdem Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 | [API-Referenz](https://platform.claude.com/docs/de/api/beta/messages/create) |
| `computer_20250124` | `computer-use-2025-01-24` | Claude Sonnet 4.5 ([abgekündigt](https://platform.claude.com/docs/de/about-claude/model-deprecations)), Claude Haiku 4.5, Claude Opus 4.1 ([eingestellt, außer auf Bedrock und Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)), Claude Sonnet 4 ([eingestellt, außer auf Bedrock und Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) und Claude Opus 4 ([eingestellt, außer auf Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) | [API-Referenz](https://platform.claude.com/docs/de/api/beta/messages/create) |
***
## 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](https://platform.claude.com/docs/de/build-with-claude/thinking#summarized-thinking) 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/computer-use-tool#security-considerations) 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](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
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](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
## Preise
„Computer use“ (Computernutzung) folgt der standardmäßigen [Preisgestaltung für Tool-Nutzung](https://platform.claude.com/docs/de/agents-and-tools/tool-use/overview#pricing). 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.590 bei Claude Sonnet 5 und etwa 4.520 bei den anderen unterstützten Modellen). Dies umfasst die Definitionen der Mitglieds-Tools und den System-Prompt für die Tool-Nutzung. Das Deaktivieren von `zoom` mit `configs` entfernt etwa 410 dieser Token. Die genaue Anzahl für eine Anfrage wird im `usage` der Antwort angegeben, und du kannst sie vorab mit dem [Token-Counting-Endpunkt](https://platform.claude.com/docs/de/build-with-claude/token-counting) abschä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](https://platform.claude.com/docs/de/build-with-claude/vision#evaluate-image-size))
* Ergebnisse der Tool-Ausführung, die an Claude zurückgegeben werden
Wenn du neben Computer Use auch Bash- oder Texteditor-Tools verwendest, haben diese Tools ihre eigenen Token-Kosten, wie auf den jeweiligen Seiten dokumentiert.
## Nächste Schritte
Starte mit dem Treiber eines Partners oder schreibe deinen eigenen in Python oder TypeScript. Das SDK führt die Schleife und den von dir übergebenen Genehmigungs-Callback aus.
Behebe die häufigsten Fehler bei der Tool-Nutzung mit Diagnosetabellen von Symptom zu Lösung.
Starte mit der vollständigen Docker-basierten Implementierung
Verbinde Claude mit externen Tools und APIs. Erfahre, wo Tools ausgeführt werden, wann Claude sie aufruft und welches Tool zu deiner Aufgabe passt.
Durch Benchmarks gestützte Empfehlungen zu Auflösung, Denkaufwand und Kontextverwaltung
Lass Claude in deiner eigenen Browserumgebung Webseiten navigieren, lesen und mit ihnen interagieren, für Aufgaben, die im Browser bleiben.