Das Web-Suchwerkzeug gibt Claude direkten Zugriff auf Echtzeit-Webinhalte, wodurch es Fragen mit aktuellen Informationen über seinen Wissensstichtag hinaus beantworten kann. Claude zitiert automatisch Quellen aus Suchergebnissen als Teil seiner Antwort.
Bitte teilen Sie Ihre Erfahrungen mit dem Web-Suchwerkzeug über unser Feedback-Formular mit.
Web-Suche ist verfügbar auf:
claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-3-7-sonnet-20250219)claude-haiku-4-5-20251001)claude-3-5-haiku-latest)claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)Wenn Sie das Web-Suchwerkzeug zu Ihrer API-Anfrage hinzufügen:
Der Administrator Ihrer Organisation muss die Web-Suche in der Konsole aktivieren.
Stellen Sie das Web-Suchwerkzeug in Ihrer API-Anfrage bereit:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "What is the weather in NYC?"
}
],
"tools": [{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}]
}'Das Web-Suchwerkzeug unterstützt die folgenden Parameter:
{
"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"
}
}Der Parameter max_uses begrenzt die Anzahl der durchgeführten Suchen. Wenn Claude mehr Suchen versucht als erlaubt, wird das web_search_tool_result ein Fehler mit dem Fehlercode max_uses_exceeded sein.
Bei Verwendung von Domain-Filtern:
example.com statt https://example.com)example.com umfasst docs.example.com)docs.example.com gibt nur Ergebnisse von dieser Subdomain zurück, nicht von example.com oder api.example.com)example.com/blog)allowed_domains oder blocked_domains verwenden, aber nicht beide in derselben Anfrage.Domain-Beschränkungen auf Anforderungsebene müssen mit Domain-Beschränkungen auf Organisationsebene kompatibel sein, die in der Konsole konfiguriert sind. Domain-Beschränkungen auf Anforderungsebene können Domains nur weiter einschränken, nicht die Liste auf Organisationsebene außer Kraft setzen oder erweitern. Wenn Ihre Anfrage Domains enthält, die mit Organisationseinstellungen in Konflikt stehen, gibt die API einen Validierungsfehler zurück.
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 Stadtnameregion: Die Region oder der Bundesstaatcountry: Das Landtimezone: Die IANA-Zeitzone-ID.Hier ist eine Beispiel-Antwortstruktur:
{
"role": "assistant",
"content": [
// 1. Claudes Entscheidung zu suchen
{
"type": "text",
"text": "I'll search for when Claude Shannon was born."
},
// 2. Die verwendete Suchanfrage
{
"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 enthalten:
url: Die URL der Quellseitetitle: Der Titel der Quellseitepage_age: Wann die Website zuletzt aktualisiert wurdeencrypted_content: Verschlüsselter Inhalt, der in mehrteiligen Gesprächen für Zitate zurückgegeben werden mussZitate sind immer für die Web-Suche aktiviert, und jedes web_search_result_location enthält:
url: Die URL der zitierten Quelletitle: Der Titel der zitierten Quelleencrypted_index: Eine Referenz, die für mehrteilige Gespräche zurückgegeben werden muss.cited_text: Bis zu 150 Zeichen des zitierten InhaltsDie Web-Such-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 Kombination mit Ihrem eigenen Material, bevor Sie diese Endbenutzer anzeigen, zeigen Sie Zitate wie angemessen basierend auf Rücksprache mit Ihrem Rechtsteam an.
Wenn das Web-Suchwerkzeug auf einen Fehler stößt (z. B. Ratenlimit überschritten), gibt die Claude API immer noch eine 200-Antwort (Erfolg) zurück. Der Fehler wird im Antwortkörper mit der folgenden Struktur dargestellt:
{
"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 überschritteninvalid_input: Ungültiger Suchanfrageparametermax_uses_exceeded: Maximale Web-Suchwerkzeug-Nutzungen überschrittenquery_too_long: Anfrage überschreitet maximale Längeunavailable: Ein interner Fehler ist aufgetretenpause_turn Stop-GrundDie Antwort kann einen pause_turn Stop-Grund enthalten, der anzeigt, dass die API einen lange laufenden Zug unterbrochen hat. Sie können die Antwort in einer nachfolgenden Anfrage unverändert zurückgeben, um Claude seinen Zug fortsetzen zu lassen, oder den Inhalt ändern, wenn Sie das Gespräch unterbrechen möchten.
Die Web-Suche funktioniert mit Prompt-Caching. Um Prompt-Caching zu aktivieren, fügen Sie mindestens einen cache_control Breakpoint in Ihrer Anfrage hinzu. Das System speichert automatisch bis zum letzten web_search_tool_result Block beim Ausführen des Werkzeugs.
Für mehrteilige Gespräche setzen Sie einen cache_control Breakpoint auf oder nach dem letzten web_search_tool_result Block, um zwischengespeicherte Inhalte wiederzuverwenden.
Zum Beispiel, um Prompt-Caching mit Web-Suche für ein mehrteiliges Gespräch zu verwenden:
import anthropic
client = anthropic.Anthropic()
# Erste Anfrage mit Web-Suche und Cache-Breakpoint
messages = [
{
"role": "user",
"content": "What's the current weather in San Francisco today?"
}
]
response1 = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages,
tools=[{
"type": "web_search_20250305",
"name": "web_search",
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}]
)
# Fügen Sie Claudes Antwort zum Gespräch hinzu
messages.append({
"role": "assistant",
"content": response1.content
})
# Zweite Anfrage mit Cache-Breakpoint nach den Suchergebnissen
messages.append({
"role": "user",
"content": "Should I expect rain later this week?",
"cache_control": {"type": "ephemeral"} # Cache bis zu diesem Punkt
})
response2 = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages,
tools=[{
"type": "web_search_20250305",
"name": "web_search",
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}]
)
# Die zweite Antwort profitiert von zwischengespeicherten Suchergebnissen
# während sie immer noch neue Suchen durchführen kann, falls erforderlich
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")Mit aktiviertem Streaming erhalten Sie Suchereignisse 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": ""}}
// Claudes Entscheidung zu suchen
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
// Suchanfrage gestreamt
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 während die Suche ausgeführt wird
// Suchergebnisse gestreamt
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"}]}}
// Claudes Antwort mit Zitaten (in diesem Beispiel weggelassen)Sie können das Web-Suchwerkzeug in die Messages Batches API einschließen. Web-Suchwerkzeug-Aufrufe über die Messages Batches API werden genauso berechnet wie die in regulären Messages API-Anfragen.
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.