Websuche-Tool

Das Websuche-Tool gibt Claude direkten Zugriff auf Echtzeit-Webinhalte und ermöglicht es ihm, Fragen mit aktuellen Informationen zu beantworten, die über seinen Wissensstand hinausgehen. Die Antwort enthält Zitate für Quellen, die aus den Suchergebnissen stammen.

Mit web_search_20260209 und späteren Versionen kann Claude Code schreiben und ausführen, der die Suchergebnisse filtert, bevor sie das Kontextfenster erreichen (dynamische Filterung), und so nur relevante Informationen behält. Dynamische Filterung ist mit Claude 4.6 und späteren Modellen sowie Claude Mythos Preview verfügbar.

Es sind drei Versionen des Websuche-Tools verfügbar:

• web_search_20250305: grundlegende Websuche
• web_search_20260209: fügt dynamische Filterung hinzu
• web_search_20260318: fügt die Steuerung der Antwort-Einbeziehung für agentische Workflows hinzu

Die Beispiele auf dieser Seite verwenden web_search_20250305 für die grundlegende Suche und web_search_20260318 für die dynamische Filterung.

Informationen zur Zero-Data-Retention-Eignung der Websuche und zur zugehörigen allowed_callers-Konfiguration findest du unter Server-Tools.

Informationen zur Modellunterstützung findest du in der Tool-Referenz.



So funktioniert die Websuche

Wenn du das Websuche-Tool zu deiner API-Anfrage hinzufügst:

1. Claude entscheidet basierend auf dem Prompt, wann gesucht werden soll.
2. Die API führt die Suchen aus und stellt Claude die Ergebnisse bereit. Dieser Prozess kann sich innerhalb einer einzelnen Anfrage mehrfach wiederholen.
3. Am Ende seines Turns liefert Claude eine finale Antwort mit zitierten Quellen.



Wann Claude sucht

Claude sucht, wenn die Anfrage von Informationen abhängt, die aktuell sind, sich ändern oder außerhalb seiner Trainingsdaten liegen:

• Aktuelle Ereignisse, Nachrichten oder Ankündigungen
• Aktuelle Preise, Kurse, Spielstände oder Statistiken
• Informationen über bestimmte Organisationen, Personen oder Produkte, die sich geändert haben könnten
• Explizite Aufforderungen, etwas zu suchen oder nachzuschlagen

Claude antwortet direkt ohne zu suchen, wenn die Anfrage auf stabilem Wissen basiert:

• Etablierte Fakten, Mathematik, naturwissenschaftliche Grundlagen oder Programmierkonzepte
• Kreatives Schreiben oder Brainstorming
• Analyse von Inhalten, die bereits in der Konversation bereitgestellt wurden
• Konversationelle Turns und Begrüßungen

Das Auslösen ist über deinen System-Prompt steuerbar: Du kannst Claude ermutigen, bereitwilliger zu suchen oder lieber direkt zu antworten. Für eine harte Beschränkung verwende max_uses, um die Anzahl der Suchen pro Anfrage zu begrenzen.



Dynamische Filterung

Bei der grundlegenden Websuche wird jedes Suchergebnis in Claudes Kontextfenster geladen, und ein Großteil dieses Inhalts kann für die Anfrage irrelevant sein. Mit web_search_20260209 oder später schreibt und führt Claude stattdessen Code aus, der die Ergebnisse zuerst filtert, sodass nur relevante Inhalte das Kontextfenster erreichen. Dies reduziert den Token-Verbrauch bei suchintensiven Anfragen.

Die dynamische Filterung führt die Websuche innerhalb der Code-Ausführung aus: Bei web_search_20260209 und später ist das Feld allowed_callers des Tools standardmäßig auf ["code_execution_20260120"] gesetzt, und wenn die dynamische Filterung läuft, stellt die API die benötigte Code-Ausführung für die Anfrage automatisch bereit. Du musst das Code-Ausführungs-Tool nicht selbst zu tools hinzufügen. Es fallen keine zusätzlichen Gebühren für auf diese Weise getätigte Code-Ausführungsaufrufe an, abgesehen von den standardmäßigen Token-Kosten.

Um die Websuche direkt ohne dynamische Filterung aufzurufen, setze allowed_callers: ["direct"]. Modelle, die keine programmatischen Tool-Aufrufe unterstützen, benötigen diese Einstellung. Ohne sie gibt die API einen 400-Fehler zurück, der dich auffordert, sie zu setzen.

Die folgenden Beispiele verwenden web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)



So verwendest du die Websuche

Gib das Websuche-Tool in deiner API-Anfrage an:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)



Tool-Definition

Das Websuche-Tool unterstützt die folgenden Parameter:

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Alle Versionen des Websuche-Tools akzeptieren allowed_callers, das steuert, ob Claude die Websuche direkt oder über die Code-Ausführung mittels dynamischer Filterung aufruft. Bei web_search_20260209 und später ist der Standardwert ["code_execution_20260120"] statt ["direct"]. Siehe Server-Tools für die Konfiguration. web_search_20260318 und später akzeptieren außerdem response_inclusion.



Maximale Nutzungen

Der Parameter max_uses begrenzt die Anzahl der durchgeführten Suchen. Wenn Claude mehr Suchen versucht als erlaubt, ist das web_search_tool_result ein Fehler mit dem Fehlercode max_uses_exceeded.

Einfache Faktenabfragen verwenden typischerweise 1–3 Suchen; vergleichende Recherchen oder Recherchen zu mehreren Entitäten können 10 oder mehr verwenden. Hinweise zur Wahl eines Werts findest du unter Server-Tools.



Domain-Filterung

Gib allowed_domains oder blocked_domains an, nicht beides. Wenn eine Anfrage beides enthält, gibt die API einen 400-Fehler zurück. Einträge sind reine Domains mit optionalem Pfad, zum Beispiel example.com oder example.com/blog, ohne Schema.

Die vollständigen Regeln zur Domain-Filterung findest du unter Domain-Filterung im Server-Tools-Leitfaden.



Lokalisierung

Der Parameter user_location ermöglicht es dir, Suchergebnisse basierend auf dem Standort eines Nutzers zu lokalisieren. Gib mindestens eines von city, region, country oder timezone an.

• type: Der Typ des Standorts (muss approximate sein)
• city: Der Name der Stadt
• region: Die Region oder das Bundesland
• country: Der zweistellige ISO 3166-1 alpha-2-Ländercode. Die API lehnt nicht unterstützte Ländercodes mit einem 400-Fehler ab.
• timezone: Die IANA-Zeitzonen-ID.



Antwort-Einbeziehung

Der Parameter response_inclusion steuert, wie Suchergebnis-Blöcke in der API-Antwort erscheinen, wenn das Ergebnis von einem abgeschlossenen Code-Ausführungs-Aufruf im selben Turn verarbeitet wurde. Setze "response_inclusion": "excluded", um diese verschachtelten server_tool_use- und Ergebnis-Block-Paare vollständig aus der Antwort zu entfernen und so die Output-Token-Kosten für agentische Workflows zu reduzieren, die den rohen Suchinhalt nicht an den Client zurückgeben müssen. Der Standardwert ist "full". Ergebnisse aus direkten Aufrufen oder aus Code-Ausführungs-Aufrufen, die vor dem Abschluss pausiert wurden, werden immer vollständig zurückgegeben, damit sie im nächsten Turn zurückgesendet werden können.

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}



Antwort

Hier ist ein Beispiel für eine Antwortstruktur:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Dieses Beispiel zeigt eine direkte Suche. Wenn eine Suche über dynamische Filterung läuft, enthält die Antwort auch die Ergebnis-Blöcke des Code-Ausführungs-Tools, und jedes verschachtelte server_tool_use- und web_search_tool_result-Paar trägt ein caller-Feld, das den Code-Ausführungs-Aufruf identifiziert, der es erzeugt hat.



Suchergebnisse

Suchergebnisse enthalten:

• url: Die URL der Quellseite
• title: Der Titel der Quellseite
• page_age: Wann die Seite zuletzt aktualisiert wurde
• encrypted_content: Verschlüsselter Inhalt, den du in Multi-Turn-Konversationen zurückgeben musst

Um eine Konversation fortzusetzen, die Suchergebnisse enthält, sende die Content-Blöcke des Assistenten genau so zurück, wie du sie erhalten hast, einschließlich des encrypted_content jedes Ergebnisses. Die API entschlüsselt diesen Inhalt in späteren Turns, um die Suchergebnisse in Claudes Kontext wiederherzustellen. Wenn encrypted_content fehlt oder verändert wurde, schlägt die Anfrage mit einem 400-Validierungsfehler fehl.



Zitate

Zitate sind für die Websuche immer aktiviert, und jede web_search_result_location enthält:

• url: Die URL der zitierten Quelle
• title: Der Titel der zitierten Quelle
• encrypted_index: Eine Referenz, die für Multi-Turn-Konversationen zurückgegeben werden muss
• cited_text: Bis zu 150 Zeichen des zitierten Inhalts

Die Websuche-Zitatfelder cited_text, title und url zählen nicht zur Input- oder Output-Token-Nutzung.



Fehler

Wenn das Websuche-Tool auf einen Fehler stößt (z. B. beim Erreichen von Ratenlimits), gibt die Claude API trotzdem eine 200-Antwort (Erfolg) zurück. Der Fehler wird innerhalb des Antwort-Bodys mit der folgenden Struktur dargestellt:

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Bei einem Fehler ist content ein einzelnes Fehlerobjekt statt einer Liste von Ergebnis-Blöcken. Eine Suche, die erfolgreich ist, aber keine Ergebnisse liefert, gibt eine leere content-Liste zurück, keinen Fehler.

Dies sind die möglichen Fehlercodes:

• too_many_requests: Ratenlimit überschritten
• invalid_tool_input: Ungültiger Suchanfrage-Parameter
• max_uses_exceeded: Maximale Anzahl an Websuche-Tool-Nutzungen überschritten
• query_too_long: Anfrage überschreitet die maximale Länge
• request_too_large: Die Suchanfrage ist zu groß, typischerweise aufgrund einer langen Domain-Filterliste
• unavailable: Ein interner Fehler ist aufgetreten



pause_turn-Stop-Reason

Die API kann einen lang laufenden Such-Turn pausieren und stop_reason: "pause_turn" zurückgeben. Um fortzufahren, sende die pausierte Assistenten-Nachricht unverändert in einer neuen Anfrage zurück.

Wenn Claude die Websuche und eines deiner Client-Tools in derselben Gruppe paralleler Tool-Aufrufe aufruft, gibt die API stattdessen stop_reason: "tool_use" zurück und führt die Suche noch nicht aus. Um fortzufahren, gib die Client-Tool-Ergebnisse zurück, und die API führt die Suche in der nächsten Anfrage aus. Siehe Server-Tools und Client-Tools in einem Turn mischen.

Informationen zur serverseitigen Schleife und zur pause_turn-Behandlung findest du unter Die serverseitige Schleife und pause_turn im Server-Tools-Leitfaden.



Prompt-Caching

Informationen zum Caching von Tool-Definitionen über Turns hinweg findest du unter Tool-Nutzung mit Prompt-Caching.



Streaming

Wenn Streaming aktiviert ist, erhältst du Such-Events als Teil des Streams. Es gibt eine Pause, während die Suche läuft:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Claude's decision to search

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)



Batch-Anfragen

Du kannst das Websuche-Tool in die Messages Batches API einbinden. Websuche-Tool-Aufrufe über die Messages Batches API werden genauso berechnet wie in regulären Messages-API-Anfragen.

Um die gemeinsam genutzte Kapazität zu schützen, drosselt die Batches API Websuche-Anfragen pro Organisation, sodass große Batches mit vielen Suchen länger dauern können. Du kannst das Websuche-Ratenlimit deiner Organisation auf der Seite Ratenlimits in der Claude Console einsehen. Um ein höheres Limit anzufordern, kontaktiere den Vertrieb von dieser Seite aus.



Nutzung und Preise

Die Nutzung der Websuche wird zusätzlich zur Token-Nutzung berechnet:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

Die Websuche ist über die Claude API für 10 $ pro 1.000 Suchanfragen verfügbar, zuzüglich der Standard-Token-Kosten für suchgenerierte Inhalte. Websuchergebnisse, die im Verlauf einer Konversation abgerufen werden, werden als Input-Token gezählt – sowohl in Suchiterationen, die während eines einzelnen Turns ausgeführt werden, als auch in nachfolgenden Konversations-Turns.

Jede Websuche zählt als eine Nutzung, unabhängig von der Anzahl der zurückgegebenen Ergebnisse. Wenn während der Websuche ein Fehler auftritt, wird die Websuche nicht in Rechnung gestellt.



Nächste Schritte