Web-Search-Tool

Das Web-Search-Tool gibt Claude direkten Zugriff auf Webinhalte in Echtzeit und ermöglicht es ihm, Fragen mit aktuellen Informationen jenseits seines Wissensstichtags zu beantworten. 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 „context window“ (Kontextfenster) erreichen (dynamische Filterung), sodass nur relevante Informationen erhalten bleiben. Dynamische Filterung ist mit Claude 4.6 und späteren Modellen sowie Claude Mythos Preview verfügbar.

Drei Versionen des Web-Search-Tools sind verfügbar:

• web_search_20250305: einfache Websuche
• web_search_20260209: fügt dynamische Filterung hinzu
• web_search_20260318: fügt die Steuerung der Antworteinbeziehung für agentische Workflows hinzu

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

Zur Zero-Data-Retention-Berechtigung der Websuche und der zugehörigen allowed_callers-Konfiguration siehe Server-Tools.

Zur Modellunterstützung siehe die Tool-Referenz.

So funktioniert die Websuche

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

1. Claude entscheidet anhand des Prompts, wann gesucht wird.
2. Die API führt die Suchen aus und stellt Claude die Ergebnisse bereit. Dieser Vorgang kann sich innerhalb einer einzelnen Anfrage mehrfach wiederholen.
3. Am Ende seines Zugs liefert Claude eine abschließende 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
• Ausdrückliche Aufforderungen, etwas zu suchen oder nachzuschlagen

Claude antwortet direkt ohne Suche, wenn die Anfrage auf stabilem Wissen beruht:

• Etablierte Fakten, Mathematik, naturwissenschaftliche Grundlagen oder Programmierkonzepte
• Kreatives Schreiben oder Brainstorming
• Analyse von Inhalten, die bereits im Gespräch bereitgestellt wurden
• Gesprächsbeiträge und Begrüßungen

Das Auslösen ist über deinen System-Prompt steuerbar: Du kannst Claude dazu anregen, bereitwilliger zu suchen oder bevorzugt 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 einfachen Websuche wird jedes Suchergebnis in Claudes Kontextfenster geladen, und ein Großteil dieser Inhalte 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. Das 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 für die Anfrage benötigte Code-Ausführung automatisch bereit. Du musst das Code-Execution-Tool nicht selbst zu tools hinzufügen. Für auf diese Weise durchgeführte Code-Execution-Aufrufe fallen über die üblichen Token-Kosten hinaus keine zusätzlichen Gebühren an.

Um die Websuche direkt, ohne dynamische Filterung, aufzurufen, setze allowed_callers: ["direct"]. Modelle, die kein programmatisches Tool-Calling unterstützen, erfordern 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-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

Diese Einstellungen auf Organisationsebene in der Claude Console gelten nur für Messages-API-Anfragen. Sitzungen von Claude Managed Agents verwenden ausschließlich die toolspezifischen Listen allowed_domains und blocked_domains im Agent-Toolset; siehe Domains für Websuche und Web-Fetch einschränken.

Stelle das Web-Search-Tool in deiner API-Anfrage bereit:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 Web-Search-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 Web-Search-Tools akzeptieren allowed_callers, das steuert, ob Claude die Websuche direkt oder aus der Code-Ausführung über dynamische Filterung aufruft. Bei web_search_20260209 und später ist der Standardwert ["code_execution_20260120"] statt ["direct"]. Siehe Server-Tools zur 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 entweder allowed_domains oder blocked_domains an, nicht beides. Enthält eine Anfrage beides, 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 Leitfaden zu Server-Tools.

Bei Claude Managed Agents setzt du diese Felder im web_search-Eintrag des Agent-Toolsets; siehe Domains für Websuche und Web-Fetch einschränken.

Lokalisierung

Mit dem Parameter user_location kannst du Suchergebnisse anhand des Standorts eines Nutzers 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 der Bundesstaat
• country: Der zweibuchstabige Ländercode nach ISO 3166-1 alpha-2. Die API lehnt nicht unterstützte Ländercodes mit einem 400-Fehler ab.
• timezone: Die IANA-Zeitzonen-ID.

Bei Claude Managed Agents akzeptiert der web_search-Eintrag des Agent-Toolsets ein user_location-Objekt mit denselben Feldern. Die API lehnt einen nicht unterstützten country-Code mit einem 400-Fehler ab, wenn du den Agenten erstellst oder aktualisierst oder wenn du eine Sitzung erstellst oder aktualisierst, die diese Einstellung liefert. Siehe Domains für Websuche und Web-Fetch einschränken.

Antworteinbeziehung

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

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

Antwort

Hier ist ein Beispiel für die 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 zusätzlich die Ergebnisblöcke des Code-Execution-Tools, und jedes verschachtelte Paar aus server_tool_use und web_search_tool_result trägt ein caller-Feld, das den Code-Execution-Aufruf identifiziert, der es ausgelöst 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 mehrzügigen Gesprächen zurückgeben musst

Um ein Gespräch fortzusetzen, das 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 Zügen, um die Suchergebnisse in Claudes Kontext wiederherzustellen. Fehlt encrypted_content oder wurde es verändert, 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 mehrzügige Gespräche zurückgegeben werden muss
• cited_text: Bis zu 150 Zeichen des zitierten Inhalts

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

Fehler

Wenn das Web-Search-Tool auf einen Fehler stößt (etwa das Erreichen von Ratenlimits), gibt die Claude API dennoch eine 200-Antwort (Erfolg) zurück. Der Fehler wird im Antwort-Body 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 Ergebnisblöcken. Eine Suche, die erfolgreich ist, aber keine Ergebnisse findet, 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 Suchanfrageparameter
• max_uses_exceeded: Maximale Anzahl an Nutzungen des Web-Search-Tools überschritten
• query_too_long: Anfrage überschreitet die maximale Länge
• request_too_large: Die Suchanfrage ist zu groß, typischerweise wegen einer langen Domain-Filterliste
• unavailable: Ein interner Fehler ist aufgetreten

Stop-Reason pause_turn

Die API kann einen lang laufenden Suchzug 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 Ergebnisse des Client-Tools zurück, und die API führt die Suche in der nächsten Anfrage aus. Siehe Server-Tools und Client-Tools in einem Zug mischen.

Zur serverseitigen Schleife und zur Behandlung von pause_turn siehe Die serverseitige Schleife und pause_turn im Leitfaden zu Server-Tools.

Prompt-Caching

Um Tool-Definitionen über Züge hinweg zu cachen, siehe Tool-Nutzung mit Prompt-Caching.

Streaming

Bei aktiviertem Streaming erhältst du Suchereignisse als Teil des Streams. Während die Suche läuft, gibt es eine Pause:

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 Web-Search-Tool in der Messages Batches API verwenden. Aufrufe des Web-Search-Tools über die Messages Batches API werden genauso abgerechnet wie in regulären Messages-API-Anfragen.

Zum Schutz gemeinsam genutzter Kapazität drosselt die Batches API Websuchanfragen pro Organisation, sodass große Batches mit vielen Suchen länger bis zum Abschluss brauchen können. Das Websuche-Ratenlimit deiner Organisation findest du auf der Seite Ratenlimits in der Claude Console. Um ein höheres Limit anzufragen, kontaktiere den Vertrieb über diese Seite.

Nutzung und Preise

Die Nutzung der „web search“ (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 auf der Claude API für 10 $ pro 1.000 Suchen verfügbar, zuzüglich der Standard-Token-Kosten für durch die Suche generierte Inhalte. Websuchergebnisse, die im Verlauf einer Konversation abgerufen werden, werden als Input-Token gezählt – sowohl bei Suchiterationen, die innerhalb 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