Das Web-Suchwerkzeug gibt Claude direkten Zugriff auf Echtzeit-Webinhalte und ermöglicht es ihm, Fragen mit aktuellen Informationen über seinen Wissensstichtag hinaus zu beantworten. Claude zitiert automatisch Quellen aus Suchergebnissen als Teil seiner Antwort.

Bitte teilen Sie uns Ihre Erfahrungen mit dem Web-Suchwerkzeug über unser Feedback-Formular mit.

​
Unterstützte Modelle

Die Web-Suche ist verfügbar für:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (neu) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Wie die Web-Suche funktioniert

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

  1. Claude entscheidet basierend auf der Eingabeaufforderung, wann gesucht werden soll.
  2. Die API führt die Suchen durch und stellt Claude die Ergebnisse zur Verfügung. Dieser Prozess kann sich mehrmals innerhalb einer einzigen Anfrage wiederholen.
  3. Am Ende seines Zuges liefert Claude eine endgültige Antwort mit zitierten Quellen.

​
Wie man die Web-Suche verwendet

Der Administrator Ihrer Organisation muss die Web-Suche in der Console 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-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "How do I update a web app to TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Tool-Definition

Das Web-Suchwerkzeug unterstützt die folgenden Parameter:

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

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

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

  // Optional: Niemals Ergebnisse von diesen Domains einbeziehen
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Suchergebnisse lokalisieren
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

​
Maximale Verwendungen

Der Parameter max_uses begrenzt die Anzahl der durchgeführten Suchen. Wenn Claude mehr Suchen als erlaubt versucht, wird das web_search_tool_result ein Fehler mit dem Fehlercode max_uses_exceeded sein.

​
Domain-Filterung

Bei der Verwendung von Domain-Filtern:

  • Domains sollten nicht das HTTP/HTTPS-Schema enthalten (verwenden Sie example.com anstelle von https://example.com)
  • Subdomains werden automatisch einbezogen (example.com deckt docs.example.com ab)
  • Unterpfade werden unterstützt (example.com/blog)
  • Sie können entweder allowed_domains oder blocked_domains verwenden, aber nicht beide in derselben Anfrage.

​
Lokalisierung

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

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

​
Antwort

Hier ist ein Beispiel für eine 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

Suchergebnisse beinhalten:

  • url: Die URL der Quellseite
  • title: Der Titel der Quellseite
  • page_age: Wann die Seite zuletzt aktualisiert wurde
  • encrypted_content: Verschlüsselter Inhalt, der für Zitate in Gesprächen mit mehreren Runden zurückgegeben werden muss

​
Zitate

Zitate sind für die Web-Suche immer 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 Gespräche mit mehreren Runden zurückgegeben werden muss.
  • cited_text: Bis zu 150 Zeichen des zitierten Inhalts

Die Web-Suchzitationsfelder cited_text, title und url werden nicht auf die Nutzung von Eingabe- oder Ausgabe-Token angerechnet.

Bei der Anzeige von Webergebnissen oder Informationen aus Webergebnissen für Endbenutzer müssen Inline-Zitate in Ihrer Benutzeroberfläche deutlich sichtbar und anklickbar sein.

​
Fehler

Wenn während der Web-Suche ein Fehler auftritt, erhalten Sie eine Antwort in folgender Form:

{
  "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: Ratengrenze überschritten
  • invalid_input: Ungültiger Suchanfrageparameter
  • max_uses_exceeded: Maximale Verwendung des Web-Suchwerkzeugs überschritten
  • query_too_long: Anfrage überschreitet maximale Länge
  • unavailable: Ein interner Fehler ist aufgetreten

​
pause_turn Stoppgrund

Die Antwort kann einen pause_turn Stoppgrund enthalten, der anzeigt, dass die API einen lang laufenden Zug pausiert hat. Sie können die Antwort unverändert in einer nachfolgenden Anfrage zurückgeben, um Claude seinen Zug fortsetzen zu lassen, oder den Inhalt modifizieren, wenn Sie das Gespräch unterbrechen möchten.

​
Prompt-Caching

Die Web-Suche funktioniert mit Prompt-Caching. Um Prompt-Caching zu aktivieren, fügen Sie mindestens einen cache_control-Haltepunkt in Ihrer Anfrage hinzu. Das System wird automatisch bis zum letzten web_search_tool_result-Block beim Ausführen des Tools zwischenspeichern.

Für Gespräche mit mehreren Runden setzen Sie einen cache_control-Haltepunkt auf oder nach dem letzten web_search_tool_result-Block, um zwischengespeicherte Inhalte wiederzuverwenden.

Hier ist ein Beispiel für die Verwendung von Prompt-Caching mit Web-Suche für ein Gespräch mit mehreren Runden:

import anthropic

client = anthropic.Anthropic()

# Erste Anfrage mit Web-Suche und Cache-Haltepunkt
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

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

# Claudes Antwort zum Gespräch hinzufügen
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Zweite Anfrage mit Cache-Haltepunkt 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-opus-4-20250514",
    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,
# kann aber bei Bedarf immer noch neue Suchen durchführen
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Bei 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 ausgelassen)

​
Batch-Anfragen

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

​
Nutzung und Preisgestaltung

Die Nutzung der Web-Suche 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 Web-Suche ist in der Anthropic API für 10 $ pro 1.000 Suchen verfügbar, zuzüglich der Standardkosten für Token für suchgenerierte Inhalte. Web-Suchergebnisse, die während eines Gesprächs abgerufen werden, werden als Eingabe-Token gezählt, sowohl in Suchiterationen, die während eines einzelnen Zuges ausgeführt werden, als auch in nachfolgenden Gesprächsrunden.

Jede Web-Suche zählt als eine Verwendung, unabhängig von der Anzahl der zurückgegebenen Ergebnisse. Wenn während der Web-Suche ein Fehler auftritt, wird die Web-Suche nicht in Rechnung gestellt.