Websuche-Tool

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

Die neueste Version des Websuche-Tools (web_search_20260318) unterstützt dynamisches Filtern mit Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 und Claude Sonnet 4.6. Claude kann Code schreiben und ausführen, um Suchergebnisse zu filtern, bevor sie das Kontextfenster erreichen, wobei nur relevante Informationen behalten und der Rest verworfen wird. Dies führt zu genaueren Antworten bei gleichzeitig reduziertem Token-Verbrauch. web_search_20260318 fügt außerdem die Steuerung der Antwort-Einbeziehung für agentische Workflows hinzu. Die vorherigen Versionen (web_search_20260209 nur für dynamisches Filtern, web_search_20250305 für die einfache Suche) bleiben verfügbar.

Für die Zero-Data-Retention-Berechtigung und den allowed_callers-Workaround siehe Server-Tools.

Für die Modellunterstützung siehe die 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 mehrmals 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, Ergebnisse oder Statistiken
• Informationen über bestimmte Organisationen, Personen oder Produkte, die sich geändert haben könnten
• Explizite Aufforderungen zu suchen oder etwas 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 im Gespräch 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.



Dynamisches Filtern

Die Websuche ist eine token-intensive Aufgabe. Bei der einfachen Websuche muss Claude Suchergebnisse in den Kontext laden, vollständiges HTML von mehreren Websites abrufen und über all das nachdenken, bevor es zu einer Antwort kommt. Oft ist ein Großteil dieser Inhalte irrelevant, was die Antwortqualität beeinträchtigen kann.

Mit web_search_20260209 oder höher kann Claude Code schreiben und ausführen, um Abfrageergebnisse nachzubearbeiten. Anstatt über vollständige HTML-Dateien nachzudenken, filtert Claude Suchergebnisse dynamisch, bevor sie in den Kontext geladen werden, behält nur das Relevante und verwirft den Rest.

Dynamisches Filtern ist besonders effektiv für:

• Durchsuchen technischer Dokumentation
• Literaturrecherche und Zitatverifizierung
• Technische Recherche
• Fundierung und Verifizierung von Antworten

Um dynamisches Filtern zu aktivieren, verwende web_search_20260209 oder eine spätere Version. Die folgenden Beispiele verwenden web_search_20260209:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20260209", "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-4-8",
    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
  "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"
  }
}



Max uses

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 oder Multi-Entity-Recherchen können 10 oder mehr verwenden. Für latenzempfindliche Abfragen begrenzt max_uses: 3 die Kosten, ohne dabei häufig abzuschneiden. Für Recherche-Agenten setze max_uses auf 15–20 oder lasse es ganz weg.



Domain-Filterung

Für Domain-Filterung mit allowed_domains und blocked_domains siehe Server-Tools.



Lokalisierung

Der Parameter user_location ermöglicht es dir, Suchergebnisse basierend auf dem Standort eines Nutzers zu lokalisieren.

• type: Der Typ des Standorts (muss approximate sein)
• city: Der Stadtname
• region: Die Region oder das Bundesland
• country: Das Land
• 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 konsumiert 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 rohe Suchinhalte nicht an den Client zurückgeben müssen. Der Standardwert ist "full". Ergebnisse von direkten Aufrufen oder von 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"
}



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, der in mehrstufigen Gesprächen für Zitate zurückgegeben werden muss



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 mehrstufige Gespräche 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"
  }
}

Dies sind die möglichen Fehlercodes:

• too_many_requests: Ratenlimit überschritten
• invalid_input: Ungültiger Suchabfrage-Parameter
• max_uses_exceeded: Maximale Anzahl an Websuche-Tool-Nutzungen überschritten
• query_too_long: Abfrage überschreitet die maximale Länge
• unavailable: Ein interner Fehler ist aufgetreten



pause_turn-Stop-Reason

Für das Fortsetzen nach einem pause_turn-Stop-Reason siehe Server-Tools.



Prompt-Caching

Für das Cachen von Tool-Definitionen über mehrere Turns hinweg siehe 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 ausgeführt wird:

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 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 Limits in der Claude Console einsehen; kontaktiere den Vertrieb von dieser Seite aus, um ein höheres Limit anzufordern. Typische Batch-Websuche-Workloads umfassen das Anreichern von Datensätzen mit aktuellen Webdaten, das Recherchieren einer großen Liste von Entitäten und das Fundieren oder Überprüfen eines Inhaltskorpus anhand von Live-Quellen.



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