Web-Search-Tool
Gib Claude Zugriff auf aktuelle Webinhalte mit zitierten Quellen, optionaler dynamischer Filterung und Domain-Steuerung.
Nutzung unterscheidet sich je nach Produkt
tools der Anfrage ein web_search-Tool hinzu. Einstellungen wie max_uses, Domain-Listen und user_location werden an diesem Tool gesetzt.max_uses, citations oder cache_control.Das Web-Such-Tool gibt Claude direkten Zugriff auf Echtzeit-Webinhalte, sodass es Fragen mit aktuellen Informationen jenseits seines Wissensstichtags beantworten kann. 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 („dynamic filtering“ (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-Such-Tools sind verfügbar:
web_search_20250305: einfache Websucheweb_search_20260209: fügt dynamische Filterung hinzuweb_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.
Informationen zur Zero-Data-Retention-Berechtigung der Websuche und zur zugehörigen allowed_callers-Konfiguration findest du unter Server-Tools.
Informationen zur Modellunterstützung findest du in der Tool-Referenz.
Um zu prüfen, ob ein Modell die Websuche akzeptiert, bevor du eine Anfrage sendest, lies seinen Wert capabilities.server_tools.web_search.supported aus der Models API aus. Verwendung der Models API beschreibt das Feld.
Wie die Websuche funktioniert
Wenn du das Web-Such-Tool zu deiner API-Anfrage hinzufügst:
- Claude entscheidet anhand des Prompts, wann gesucht wird.
- Die API führt die Suchen aus und stellt Claude die Ergebnisse bereit. Dieser Vorgang kann sich innerhalb einer einzelnen Anfrage mehrmals wiederholen.
- Am Ende seines Zuges 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 in der Unterhaltung bereitgestellt wurden
- Gesprächsbeiträge und Begrüßungen
Das Auslösen lässt sich über deinen „system prompt“ (System-Prompt) steuern: Du kannst Claude dazu ermutigen, bereitwilliger zu suchen oder lieber direkt zu antworten. Um ein Limit durchzusetzen, verwende max_uses, um die Anzahl der Suchen in einem Zug zu begrenzen.
Dynamische Filterung
Bei der einfachen 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 dafür benötigte Code-Ausführung für die Anfrage automatisch bereit. Du musst das Code-Ausführungs-Tool nicht selbst zu tools hinzufügen. Für auf diese Weise erfolgte Code-Ausführungsaufrufe fallen über die Standard-Token-Kosten hinaus keine zusätzlichen Gebühren an.
Um die Websuche direkt ohne dynamische Filterung aufzurufen, setze allowed_callers: ["direct"]. Modelle, die programmatische Tool-Aufrufe nicht 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
Wie die Websuche-Einstellungen deiner Organisation in Claude-Managed-Agents-Sitzungen gelten, erfährst du unter Web-Such- und Web-Fetch-Domains einschränken.
Stelle das Web-Such-Tool in deiner API-Anfrage bereit:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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-Such-Tool unterstützt die folgenden Parameter:
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches
"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-Such-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"]. Wie du es konfigurierst, erfährst du unter ZDR und allowed_callers. web_search_20260318 und später akzeptieren außerdem response_inclusion.
Maximale Nutzungen
Der Parameter max_uses begrenzt die Anzahl der Suchen in einem einzelnen Zug. Abfragen zu einem einzelnen Fakt verwenden typischerweise 1–3 Suchen; vergleichende Recherchen oder Recherchen zu mehreren Entitäten können 10 oder mehr verwenden.
Fehlgeschlagene Suchen zählen zum Limit. Wenn Claude die Websuche häufiger direkt aufruft als erlaubt, ist das web_search_tool_result ein Fehler mit dem Fehlercode max_uses_exceeded. Wenn Claude die Websuche häufiger aus der Code-Ausführung aufruft als erlaubt, endet der Code-Ausführungslauf mit einem Fehler.
Ein Zug kann sich über mehrere Anfragen erstrecken. Eine Anfrage setzt einen Zug fort, wenn sie nach pause_turn fortgesetzt wird oder wenn ihre letzte Nachricht nur tool_result-Blöcke enthält. Suchen aus früheren Anfragen in diesem Zug zählen zum Limit, es sei denn, Claude hat sie über dynamische Filterung aus der Code-Ausführung ausgeführt.
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 Leitfaden zu Server-Tools.
Bei Claude Managed Agents setzt du diese Felder im web_search-Eintrag des Agent-Toolsets; siehe Web-Such- und Web-Fetch-Domains einschränken.
Lokalisierung
Mit dem Parameter user_location kannst du Suchergebnisse basierend auf dem Standort eines Benutzers lokalisieren. Gib mindestens eines der Felder city, region, country oder timezone an.
type: Der Typ des Standorts (mussapproximatesein)city: Der Name der Stadtregion: Die Region oder das Bundeslandcountry: Der zweistellige Ländercode nach ISO 3166-1 alpha-2 (die API lehnt einen nicht unterstützten Code mit einem 400-Fehler ab)timezone: Die IANA-Zeitzonen-ID
Bei Claude Managed Agents akzeptiert der web_search-Eintrag des Agent-Toolsets ebenfalls user_location; siehe die Einstellungen der Web-Tools.
Antworteinbeziehung
Der Parameter response_inclusion steuert, wie Suchergebnisblöcke in der API-Antwort erscheinen, wenn das Ergebnis von einem abgeschlossenen Code-Ausführungs-Aufruf in derselben Antwort verarbeitet wurde. Setze "response_inclusion": "excluded", um diese verschachtelten Paare aus server_tool_use- und Ergebnisblöcken vollständig aus der Antwort zu entfernen – für agentische Workflows, die die rohen Suchinhalte nicht benötigen. Der Token-Verbrauch bleibt davon unberührt, da Claude die Ausgabe des Codes liest und nicht diese Blöcke. Der Standardwert ist "full". Ergebnisse aus direkten Aufrufen oder aus Code-Ausführungsaufrufen, die vor dem Abschluss pausiert wurden, gibt die API immer vollständig zurück, damit du sie in der nächsten Anfrage zurücksenden kannst.
{
"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-Ausführungs-Tools, und jedes verschachtelte Paar aus server_tool_use und web_search_tool_result trägt ein caller-Feld, das den Code-Ausführungsaufruf identifiziert, der es ausgelöst hat.
Suchergebnisse
Suchergebnisse enthalten:
url: Die URL der Quellseitetitle: Der Titel der Quellseitepage_age: Wann die Website zuletzt aktualisiert wurdeencrypted_content: Verschlüsselter Inhalt, den du in Unterhaltungen mit mehreren Zügen zurückgeben musst
Um eine Unterhaltung fortzusetzen, die Suchergebnisse enthält, sende die Inhaltsblö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 Anfragen, 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 Quelletitle: Der Titel der zitierten Quelleencrypted_index: Eine Referenz, die in Unterhaltungen mit mehreren Zügen zurückgegeben werden musscited_text: Bis zu 150 Zeichen des zitierten Inhalts
Die Zitatfelder der Websuche cited_text, title und url zählen nicht zum Eingabe- oder Ausgabe-Token-Verbrauch.
Fehler
Wenn beim Web-Such-Tool ein Fehler auftritt (z. B. beim Erreichen von Ratenlimits), gibt die Claude API trotzdem eine 200-Antwort (Erfolg) zurück. Der Fehler wird im Antworttext 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 Treffer liefert, gibt eine leere content-Liste zurück, keinen Fehler.
Dies sind die möglichen Fehlercodes:
too_many_requests: Ratenlimit überschritteninvalid_tool_input: Ungültiger Parameter für die Suchanfragemax_uses_exceeded: Maximale Nutzungen des Web-Such-Tools überschrittenquery_too_long: Die Anfrage überschreitet die maximale Längerequest_too_large: Die Suchanfrage ist zu groß, typischerweise wegen einer langen Domain-Filterlisteunavailable: Ein interner Fehler ist aufgetreten
Stoppgrund pause_turn
Die API kann einen lang laufenden Suchzug pausieren und stop_reason: "pause_turn" zurückgeben. Um fortzufahren, sende die pausierte Assistentennachricht 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 der 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 kombinieren.
Informationen zur serverseitigen Schleife und zur Behandlung von pause_turn findest du unter 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 runs
// 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-Such-Tool in die Message Batches API einbinden. Aufrufe des Web-Such-Tools über die Message Batches API werden genauso berechnet wie die in regulären Messages-API-Anfragen.
Zum Schutz gemeinsam genutzter Kapazität drosselt die Batches API Websuche-Anfragen für jede Organisation, sodass große Batches mit vielen Suchen länger brauchen können. Das Websuche-Ratenlimit deiner Organisation siehst du auf der Seite Ratenlimits in der Claude Console. Um ein höheres Limit anzufordern, 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
}
}
}Auf der Claude API kostet die Websuche 10 $ USD pro 1.000 Suchen, zuzüglich der Standard-Token-Kosten für durch die Suche generierte Inhalte. Suchergebnisse werden als Input-Token gezählt, sowohl während Claude innerhalb eines Turns weitersucht als auch in späteren Konversations-Turns.
Jede Websuche zählt als eine Nutzung, unabhängig von der Anzahl der zurückgegebenen Ergebnisse. Eine Websuche, die mit einem Fehler fehlschlägt, wird nicht in Rechnung gestellt.
Nächste Schritte
Rufe Inhalte von bestimmten URLs ab und lies sie, um Claudes Kontext mit aktuellen Webinhalten zu erweitern.
Arbeite mit Tools, die Anthropic ausführt: server_tool_use-Blöcke, Fortsetzung mit pause_turn und Domain-Filterung.
Verzeichnis der von Anthropic bereitgestellten Tools und Referenz für optionale Eigenschaften der Tool-Definition.
Verfügbarkeit
Claude API
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelle
- Alle Modelle
- Hinweis
Nur das einfache Web-Search-Tool (
web_search_20250305), ohne dynamische Filterung.
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Modelle
- Alle Modelle
- Hinweis
Nur das einfache Web-Search-Tool (
web_search_20250305), ohne dynamische Filterung.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messagesmit Toolweb_search
Ausgenommen: Abgedeckte Modelle
Echtzeit-Ergebnisse des Web-Search-Tools, die in der API-Antwort zurückgegeben werden. Die dynamische Filterung für das Web-Search-Tool ist nicht für ZDR oder HIPAA berechtigt.
Die dynamische Filterung für das Web-Search-Tool ist nicht für ZDR oder HIPAA berechtigt.
War diese Seite hilfreich?