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 wenden Sie sich über unser Feedback-Formular an uns, 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 dem Prompt, 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 einzigen Anfrage mehrmals wiederholen.
  3. Am Ende seines Zugs liefert Claude eine finale 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-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 Gesprächen 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 Gespräche zurückgegeben werden muss.
  • cited_text: Bis zu 150 Zeichen des zitierten Inhalts

Die Web-Suche-Zitierfelder 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 das Web-Suche-Tool auf einen Fehler stößt (wie das Erreichen von Ratenlimits), gibt die Anthropic API trotzdem eine 200 (Erfolg) Antwort zurück. Der Fehler wird im Antworttext 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 ü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 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 Breakpoint in Ihre Anfrage hinzu. Das System wird automatisch bis zum letzten web_search_tool_result Block cachen, wenn das Tool ausgeführt wird.

Für mehrteilige Gespräche setzen Sie einen cache_control Breakpoint auf oder nach dem letzten web_search_tool_result Block, um gecachte 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": "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 zum Gespräch hinzufügen
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Zweite Anfrage mit Cache-Breakpoint nach den Suchergebnissen
messages.append({
    "role": "user",
    "content": "Sollte ich später diese Woche mit Regen rechnen?",
    "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 gecachten Suchergebnissen profitieren
# während sie trotzdem neue Suchen durchführen kann, wenn 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.