Outil de recherche web

L'outil de recherche web donne à Claude un accès direct au contenu web en temps réel, lui permettant de répondre aux questions avec des informations à jour au-delà de sa date limite de connaissance. La réponse inclut des citations pour les sources tirées des résultats de recherche.

La dernière version de l'outil de recherche web (web_search_20260209) prend en charge le filtrage dynamique avec Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6. Claude peut écrire et exécuter du code pour filtrer les résultats de recherche avant qu'ils n'atteignent la fenêtre de contexte, en conservant uniquement les informations pertinentes et en rejetant le reste. Cela conduit à des réponses plus précises tout en réduisant la consommation de jetons. La version précédente de l'outil (web_search_20250305) reste disponible sans filtrage dynamique.

Pour l'admissibilité à la rétention zéro des données et la solution de contournement allowed_callers, voir Outils serveur.

Pour la prise en charge des modèles, voir la Référence des outils.

Comment fonctionne la recherche web

Lorsque vous ajoutez l'outil de recherche web à votre demande API :

1. Claude décide quand effectuer une recherche en fonction de l'invite.
2. L'API exécute les recherches et fournit à Claude les résultats. Ce processus peut se répéter plusieurs fois au cours d'une seule demande.
3. À la fin de son tour, Claude fournit une réponse finale avec des sources citées.

Filtrage dynamique

La recherche web est une tâche consommatrice de jetons. Avec la recherche web basique, Claude doit extraire les résultats de recherche dans le contexte, récupérer le HTML complet de plusieurs sites web et raisonner sur tout cela avant d'arriver à une réponse. Souvent, une grande partie de ce contenu est non pertinente, ce qui peut dégrader la qualité de la réponse.

Avec la version de l'outil web_search_20260209, Claude peut écrire et exécuter du code pour post-traiter les résultats de requête. Au lieu de raisonner sur des fichiers HTML complets, Claude filtre dynamiquement les résultats de recherche avant de les charger dans le contexte, en conservant uniquement ce qui est pertinent et en rejetant le reste.

Le filtrage dynamique est particulièrement efficace pour :

• Rechercher dans la documentation technique
• Examen de la littérature et vérification des citations
• Recherche technique
• Ancrage et vérification des réponses

Pour activer le filtrage dynamique, utilisez la version de l'outil web_search_20260209 :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260209", "name": "web_search"}],
)
print(response)

Comment utiliser la recherche web

Fournissez l'outil de recherche web dans votre demande API :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

Définition de l'outil

L'outil de recherche web prend en charge les paramètres suivants :

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

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains
  "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"
  }
}

Utilisations maximales

Le paramètre max_uses limite le nombre de recherches effectuées. Si Claude tente plus de recherches que autorisé, le web_search_tool_result est une erreur avec le code d'erreur max_uses_exceeded.

Filtrage des domaines

Pour le filtrage des domaines avec allowed_domains et blocked_domains, voir Outils serveur.

Localisation

Le paramètre user_location vous permet de localiser les résultats de recherche en fonction de la localisation d'un utilisateur.

• type : Le type de localisation (doit être approximate)
• city : Le nom de la ville
• region : La région ou l'état
• country : Le pays
• timezone : L'ID de fuseau horaire IANA.

Réponse

Voici un exemple de structure de réponse :

{
  "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"
}

Résultats de recherche

Les résultats de recherche incluent :

• url : L'URL de la page source
• title : Le titre de la page source
• page_age : Quand le site a été mis à jour pour la dernière fois
• encrypted_content : Contenu chiffré qui doit être renvoyé dans les conversations multi-tours pour les citations

Citations

Les citations sont toujours activées pour la recherche web, et chaque web_search_result_location inclut :

• url : L'URL de la source citée
• title : Le titre de la source citée
• encrypted_index : Une référence qui doit être renvoyée pour les conversations multi-tours.
• cited_text : Jusqu'à 150 caractères du contenu cité

Les champs de citation de recherche web cited_text, title et url ne comptent pas vers l'utilisation des jetons d'entrée ou de sortie.

Erreurs

Lorsque l'outil de recherche web rencontre une erreur (comme atteindre les limites de débit), l'API Claude retourne toujours une réponse 200 (succès). L'erreur est représentée dans le corps de la réponse en utilisant la structure suivante :

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Voici les codes d'erreur possibles :

• too_many_requests : Limite de débit dépassée
• invalid_input : Paramètre de requête de recherche invalide
• max_uses_exceeded : Utilisations maximales de l'outil de recherche web dépassées
• query_too_long : La requête dépasse la longueur maximale
• unavailable : Une erreur interne s'est produite

Raison d'arrêt pause_turn

Pour continuer après une raison d'arrêt pause_turn, voir Outils serveur.

Mise en cache des invites

Pour la mise en cache des définitions d'outils entre les tours, voir Utilisation d'outils avec mise en cache des invites.

Diffusion en continu

Avec la diffusion en continu activée, vous recevrez les événements de recherche dans le flux. Il y aura une pause pendant l'exécution de la recherche :

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 executes

// 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)

Demandes par lot

Vous pouvez inclure l'outil de recherche web dans l'API Messages Batches. Les appels d'outils de recherche web via l'API Messages Batches sont facturés de la même manière que ceux dans les demandes régulières de l'API Messages.

Utilisation et tarification

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.

Étapes suivantes