Web-Suchwerkzeug

Das Web-Suchwerkzeug gibt Claude direkten Zugriff auf Echtzeit-Webinhalte, wodurch es Fragen mit aktuellen Informationen über seinen Wissensstichtag hinaus beantworten kann. Die Antwort enthält Zitate für Quellen aus den Suchergebnissen.

Die neueste Version des Web-Suchwerkzeugs (web_search_20260209) unterstützt dynamische Filterung mit Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 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 beibehalten und der Rest verworfen wird. Dies führt zu genaueren Antworten und reduziert den Token-Verbrauch. Die vorherige Werkzeugversion (web_search_20250305) bleibt ohne dynamische Filterung verfügbar.

Für Claude Mythos Preview wird Web-Suche auf der Claude API, Microsoft Foundry und Google Vertex AI unterstützt. Web-Suche ist nicht für Mythos Preview auf Amazon Bedrock verfügbar.

Informationen zur Zero Data Retention-Berechtigung und zum Workaround allowed_callers finden Sie unter Server-Tools.

Informationen zur Modellunterstützung finden Sie in der Tool-Referenz.

Funktionsweise der Web-Suche

Wenn Sie das Web-Suchwerkzeug zu Ihrer API-Anfrage hinzufügen:

Claude entscheidet basierend auf der Eingabeaufforderung, wann eine Suche durchgeführt werden soll.
Die API führt die Suchen durch und stellt Claude die Ergebnisse zur Verfügung. Dieser Prozess kann sich während einer einzelnen Anfrage mehrmals wiederholen.
Am Ende seines Zuges stellt Claude eine endgültige Antwort mit zitierten Quellen bereit.

Dynamische Filterung

Web-Suche ist eine Token-intensive Aufgabe. Bei der grundlegenden Web-Suche muss Claude Suchergebnisse in den Kontext ziehen, vollständiges HTML von mehreren Websites abrufen und alles davon analysieren, bevor er zu einer Antwort kommt. Oft ist ein großer Teil dieses Inhalts irrelevant, was die Antwortqualität beeinträchtigen kann.

Mit der Werkzeugversion web_search_20260209 kann Claude Code schreiben und ausführen, um Abfrageergebnisse nachzubearbeiten. Anstatt vollständige HTML-Dateien zu analysieren, filtert Claude Suchergebnisse dynamisch, bevor sie in den Kontext geladen werden, und behält nur das Relevante bei und verwirft den Rest.

Dynamische Filterung ist besonders effektiv für:

Durchsuchen technischer Dokumentation
Literaturrecherche und Zitierverifikation
Technische Forschung
Antwortverankerung und Verifikation

Dynamische Filterung erfordert, dass das Code-Ausführungswerkzeug aktiviert ist. Das verbesserte Web-Suchwerkzeug ist auf der Claude API und Microsoft Azure verfügbar. Auf Google Vertex AI ist das grundlegende Web-Suchwerkzeug (ohne dynamische Filterung) verfügbar.

Um dynamische Filterung zu aktivieren, verwenden Sie die Werkzeugversion web_search_20260209:

Verwendung der Web-Suche

Der Administrator Ihrer Organisation muss die Web-Suche in der Claude Console aktivieren.

Stellen Sie das Web-Suchwerkzeug in Ihrer API-Anfrage bereit:

Werkzeugdefinition

Das Web-Suchwerkzeug unterstützt die folgenden Parameter:

JSON

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

  // Optional: Begrenzen Sie die Anzahl der Suchen pro Anfrage
  "max_uses": 5,

  // Optional: Nur Ergebnisse von diesen Domains einschließen
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Ergebnisse von diesen Domains niemals einschließen
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Suchergebnisse lokalisieren
  "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 zulässig, ist das web_search_tool_result ein Fehler mit dem Fehlercode max_uses_exceeded.

Domain-Filterung

Informationen zur Domain-Filterung mit allowed_domains und blocked_domains finden Sie unter Server-Tools.

Lokalisierung

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

type: Der Standorttyp (muss approximate sein)
city: Der Stadtname
region: Die Region oder der Bundesstaat
country: Das Land
timezone: Die IANA-Zeitzonen-ID.

Antwort

Hier ist eine Beispielantwortstruktur:

Output

{
  "role": "assistant",
  "content": [
    // 1. Claudes Entscheidung zu suchen
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. Die verwendete Suchabfrage
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Suchergebnisse
    {
      "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. Claudes Antwort mit Zitaten
    {
      "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 Website zuletzt aktualisiert wurde
encrypted_content: Verschlüsselter Inhalt, der in mehrteiligen Gesprächen für Zitate zurückgegeben werden muss

Zitate

Zitate sind immer für die Web-Suche aktiviert, und jedes 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 mehrteilige Gespräche zurückgegeben werden muss.
cited_text: Bis zu 150 Zeichen des zitierten Inhalts

Die Web-Suche-Zitierfelder cited_text, title und url zählen nicht zur Eingabe- oder Ausgabe-Token-Nutzung.

Wenn Sie API-Ausgaben direkt an Endbenutzer anzeigen, müssen Zitate zur ursprünglichen Quelle eingeschlossen werden. Wenn Sie Änderungen an API-Ausgaben vornehmen, einschließlich durch Neuverarbeitung und/oder Kombinieren mit Ihrem eigenen Material, bevor Sie diese Endbenutzer anzeigen, zeigen Sie Zitate wie angemessen basierend auf Rücksprache mit Ihrem Rechtsteam an.

Fehler

Wenn das Web-Suchwerkzeug auf einen Fehler stößt (z. B. Ratenlimit-Überschreitung), gibt die Claude API immer noch eine 200-Antwort (Erfolg) zurück. Der Fehler wird im Antwortkörper mit der folgenden Struktur dargestellt:

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_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 Suchabfrageparameter
max_uses_exceeded: Maximale Web-Suchwerkzeug-Nutzungen überschritten
query_too_long: Abfrage überschreitet maximale Länge
unavailable: Ein interner Fehler ist aufgetreten

`pause_turn` Stop-Grund

Informationen zum Fortfahren nach einem pause_turn Stop-Grund finden Sie unter Server-Tools.

Prompt-Caching

Informationen zum Caching von Werkzeugdefinitionen über Zuges hinweg finden Sie unter Tool-Nutzung mit Prompt-Caching.

Streaming

Mit aktiviertem Streaming erhalten Sie Suchereignisse als Teil des Streams. Es gibt eine Pause während die Suche ausgeführt wird:

Output

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

Sie können das Web-Suchwerkzeug in die Messages Batches API einbeziehen. Web-Suchwerkzeug-Aufrufe über die Messages Batches API werden genauso berechnet wie die in regulären Messages API-Anfragen.

Nutzung und Preisgestaltung

Web search usage is charged in addition to token usage:

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

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Nächste Schritte

Server-Tools

Gemeinsame Mechaniken für von Anthropic ausgeführte Werkzeuge.

Tool-Referenz

Verzeichnis aller von Anthropic bereitgestellten Werkzeuge.

client = anthropic.Anthropic()

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

client = anthropic.Anthropic()

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

Funktionsweise der Web-Suche

Dynamische Filterung

Verwendung der Web-Suche

Werkzeugdefinition

Max uses

Domain-Filterung

Lokalisierung

Antwort

Suchergebnisse

Zitate

Fehler

pause_turn Stop-Grund

Prompt-Caching

Streaming

Batch-Anfragen

Nutzung und Preisgestaltung

Nächste Schritte

`pause_turn` Stop-Grund