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 connaissances. 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_20260318) prend en charge le filtrage dynamique avec Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, 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 ne conservant que les informations pertinentes et en écartant le reste. Cela conduit à des réponses plus précises tout en réduisant la consommation de tokens. web_search_20260318 ajoute également le contrôle d'inclusion de réponse pour les workflows agentiques. Les versions précédentes (web_search_20260209 pour le filtrage dynamique uniquement, web_search_20250305 pour la recherche de base) restent disponibles.

Pour l'éligibilité à la rétention zéro des données (Zero Data Retention) et la solution de contournement allowed_callers, consultez Outils serveur.

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



Fonctionnement de la recherche web

Lorsque vous ajoutez l'outil de recherche web à votre requête API :

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



Quand Claude effectue une recherche

Claude effectue une recherche lorsque la requête dépend d'informations actuelles, changeantes ou extérieures à ses données d'entraînement :

• Événements récents, actualités ou annonces
• Prix, taux, scores ou statistiques actuels
• Informations sur des organisations, personnes ou produits spécifiques susceptibles d'avoir changé
• Demandes explicites de recherche ou de vérification

Claude répond directement sans effectuer de recherche lorsque la requête s'appuie sur des connaissances stables :

• Faits établis, mathématiques, fondamentaux scientifiques ou concepts de programmation
• Rédaction créative ou brainstorming
• Analyse de contenu déjà fourni dans la conversation
• Tours de conversation et salutations

Le déclenchement est orientable via votre invite système : vous pouvez encourager Claude à effectuer des recherches plus facilement ou à privilégier une réponse directe. Pour une contrainte stricte, utilisez max_uses afin de plafonner le nombre de recherches pour chaque requête.



Filtrage dynamique

La recherche web est une tâche gourmande en tokens. Avec la recherche web de base, Claude doit intégrer les résultats de recherche dans le contexte, récupérer le HTML complet de plusieurs sites web et raisonner sur l'ensemble avant d'arriver à une réponse. Souvent, une grande partie de ce contenu n'est pas pertinente, ce qui peut dégrader la qualité de la réponse.

Avec web_search_20260209 ou une version ultérieure, 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 ne conservant que ce qui est pertinent et en écartant le reste.

Le filtrage dynamique est particulièrement efficace pour :

• La recherche dans la documentation technique
• La revue de littérature et la vérification de citations
• La recherche technique
• L'ancrage et la vérification des réponses

Pour activer le filtrage dynamique, utilisez web_search_20260209 ou toute version ultérieure. Les exemples suivants utilisent web_search_20260209 :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 requête API :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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"
  }
}



Nombre maximal d'utilisations

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

Les requêtes factuelles simples utilisent généralement 1 à 3 recherches ; les recherches comparatives ou multi-entités peuvent en utiliser 10 ou plus. Pour les recherches sensibles à la latence, max_uses: 3 limite le coût tout en tronquant rarement. Pour les agents de recherche, définissez max_uses entre 15 et 20 ou omettez-le entièrement.



Filtrage de domaines

Pour le filtrage de domaines avec allowed_domains et blocked_domains, consultez Outils serveur.



Localisation

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

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



Inclusion de réponse

Le paramètre response_inclusion contrôle la manière dont les blocs de résultats de recherche apparaissent dans la réponse de l'API lorsque le résultat a été consommé par un appel d'exécution de code terminé dans le même tour. Définissez "response_inclusion": "excluded" pour supprimer entièrement ces paires imbriquées de blocs server_tool_use et de résultats de la réponse, réduisant ainsi les coûts en tokens de sortie pour les workflows agentiques qui n'ont pas besoin de renvoyer le contenu brut de recherche au client. La valeur par défaut est "full". Les résultats provenant d'appels directs, ou d'appels d'exécution de code mis en pause avant leur achèvement, sont toujours renvoyés intégralement afin de pouvoir être renvoyés au tour suivant.

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}



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 : La date de dernière mise à jour du site
• 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 sont pas comptabilisés dans l'utilisation des tokens d'entrée ou de sortie.



Erreurs

Lorsque l'outil de recherche web rencontre une erreur (par exemple en atteignant les limites de débit), l'API Claude renvoie tout de même une réponse 200 (succès). L'erreur est représentée dans le corps de la réponse à l'aide de la structure suivante :

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_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 : Nombre maximal d'utilisations de l'outil de recherche web dépassé
• 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, consultez Outils serveur.



Mise en cache des prompts

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



Streaming

Lorsque le streaming est activé, vous recevrez des événements de recherche dans le cadre du 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)



Requêtes par lots

Vous pouvez inclure l'outil de recherche web dans l'API Messages Batches. Les appels à l'outil de recherche web via l'API Messages Batches sont facturés au même tarif que ceux des requêtes API Messages standard.

Pour protéger la capacité partagée, l'API Batches limite le débit des requêtes de recherche web par organisation, de sorte que les lots volumineux comportant de nombreuses recherches peuvent prendre plus de temps à s'exécuter. Vous pouvez consulter la limite de débit de recherche web de votre organisation sur la page Limites dans la Claude Console ; contactez le service commercial depuis cette page pour demander une limite plus élevée. Les charges de travail typiques de recherche web par lots incluent l'enrichissement d'enregistrements avec des données web actuelles, la recherche sur une longue liste d'entités, et l'ancrage ou la vérification d'un corpus de contenu par rapport à des sources en direct.



Utilisation et tarification

L'utilisation de la recherche web est facturée en plus de l'utilisation des tokens :

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

La recherche web est disponible sur l'API Claude au tarif de 10 $ pour 1 000 recherches, auquel s'ajoutent les coûts standard des tokens pour le contenu généré par la recherche. Les résultats de recherche web récupérés tout au long d'une conversation sont comptabilisés comme des tokens d'entrée, que ce soit dans les itérations de recherche exécutées au cours d'un même tour ou dans les tours de conversation suivants.

Chaque recherche web compte comme une utilisation, quel que soit le nombre de résultats renvoyés. Si une erreur survient pendant la recherche web, celle-ci ne sera pas facturée.



Étapes suivantes