Das Web-Suche-Tool gibt Claude direkten Zugang zu Echtzeit-Webinhalten und ermöglicht es, Fragen mit aktuellen Informationen jenseits seines Wissensstichtags zu beantworten. Claude zitiert automatisch Quellen aus den Suchergebnissen als Teil seiner Antwort.

Bitte kontaktieren Sie uns über unser Feedback-Formular, um Ihre Erfahrungen mit dem Web-Suche-Tool zu teilen.

​
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-Suche-Tool zu Ihrer API-Anfrage hinzufügen:

  1. Claude entscheidet basierend auf der Eingabeaufforderung, wann gesucht werden soll.
  2. Die API führt die Suchen aus und stellt Claude die Ergebnisse zur Verfügung. Dieser Prozess kann sich während einer einzelnen Anfrage mehrmals wiederholen.
  3. Am Ende seines Zugs gibt Claude eine finale Antwort mit zitierten Quellen.

​
Wie man die Web-Suche verwendet

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

Stellen Sie das Web-Suche-Tool 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": "Wie aktualisiere ich eine Web-App auf TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Tool-Definition

Das Web-Suche-Tool 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 einschließen
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Niemals Ergebnisse von diesen Domains 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 erlaubt, 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 anstatt https://example.com)
  • Subdomains sind automatisch eingeschlossen (example.com umfasst docs.example.com)
  • Subpfade 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 Staat
  • 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": "Ich werde nach dem Geburtsdatum von Claude Shannon suchen."
    },
    // 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": "Basierend auf den Suchergebnissen, ",
      "type": "text"
    },
    // 4. Claudes Antwort mit Zitaten
    {
      "text": "wurde Claude Shannon am 30. April 1916 in Petoskey, Michigan geboren",
      "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 Seite zuletzt aktualisiert wurde
  • encrypted_content: Verschlüsselter Inhalt, der in mehrteiligen Unterhaltungen für Zitate zurückgegeben werden muss

​
Zitate

Zitate sind für die Web-Suche 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 mehrteilige Unterhaltungen zurückgegeben werden muss.
  • cited_text: Bis zu 150 Zeichen des zitierten Inhalts

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

Beim Anzeigen von Web-Ergebnissen oder Informationen aus Web-Ergebnissen für Endbenutzer müssen Inline-Zitate in Ihrer Benutzeroberfläche deutlich sichtbar und anklickbar gemacht werden.

​
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: Ratenlimit überschritten
  • invalid_input: Ungültiger Suchanfrage-Parameter
  • max_uses_exceeded: Maximale Web-Suche-Tool-Nutzung überschritten
  • query_too_long: Anfrage überschreitet maximale Länge
  • unavailable: Ein interner Fehler ist aufgetreten

​
pause_turn Stopp-Grund

Die Antwort kann einen pause_turn Stopp-Grund enthalten, der anzeigt, dass die API einen lang laufenden Zug pausiert hat. Sie können die Antwort unverändert in einer nachfolgenden Anfrage bereitstellen, um Claude seinen Zug fortsetzen zu lassen, oder den Inhalt ändern, wenn Sie die Unterhaltung 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 Ihre Anfrage ein. Das System wird automatisch bis zum letzten web_search_tool_result Block zwischenspeichern, wenn das Tool ausgeführt wird.

Für mehrteilige Unterhaltungen setzen Sie einen cache_control Haltepunkt auf oder nach dem letzten web_search_tool_result Block, um zwischengespeicherte Inhalte wiederzuverwenden.

Zum Beispiel, um Prompt-Caching mit Web-Suche für eine mehrteilige Unterhaltung zu verwenden:

import anthropic

client = anthropic.Anthropic()

# Erste Anfrage mit Web-Suche und Cache-Haltepunkt
messages = [
    {
        "role": "user",
        "content": "Wie ist das aktuelle Wetter in San Francisco heute?"
    }
]

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 zur Unterhaltung hinzufügen
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Zweite Anfrage mit Cache-Haltepunkt nach den Suchergebnissen
messages.append({
    "role": "user",
    "content": "Sollte ich später diese Woche Regen erwarten?",
    "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 wird von zwischengespeicherten Suchergebnissen profitieren
# während sie immer noch neue Suchen durchführen kann, falls nötig
print(f"Cache-Lese-Token: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Mit aktiviertem Streaming erhalten Sie Such-Events als Teil des Streams. Es wird eine Pause geben, 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)

​
Batch-Anfragen

Sie können das Web-Suche-Tool in der Messages Batches API einschließen. Web-Suche-Tool-Aufrufe über die Messages Batches API werden genauso bepreist wie die in regulären Messages API-Anfragen.

​
Nutzung und Preise

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 Anthropic 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.