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.

Avec web_search_20260209 et les versions ultérieures, Claude peut écrire et exécuter du code qui filtre les résultats de recherche avant qu’ils n’atteignent la « context window » (fenêtre de contexte) (filtrage dynamique), en ne conservant que les informations pertinentes. Le filtrage dynamique est disponible avec Claude 4.6 et les modèles ultérieurs ainsi qu’avec Claude Mythos Preview.

Trois versions de l’outil de recherche web sont disponibles :

• web_search_20250305 : recherche web de base
• web_search_20260209 : ajoute le filtrage dynamique
• web_search_20260318 : ajoute le contrôle de l’inclusion dans la réponse pour les flux de travail agentiques

Les exemples de cette page utilisent web_search_20250305 pour la recherche de base et web_search_20260318 pour le filtrage dynamique.

Pour l’éligibilité de la recherche web à la conservation zéro des données et la configuration allowed_callers associée, consultez Outils serveur.

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

Pour vérifier si un modèle accepte la recherche web avant d’envoyer une requête, lisez sa valeur capabilities.server_tools.web_search.supported depuis la Models API. Utilisation de la Models API décrit ce champ.

Fonctionnement de la recherche web

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

1. Claude détermine 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 des 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, actualités ou annonces récents
• Prix, taux, scores ou statistiques actuels
• Informations sur des organisations, des personnes ou des 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 fait appel à des connaissances stables :

• Faits établis, mathématiques, fondamentaux scientifiques ou concepts de programmation
• Écriture créative ou brainstorming
• Analyse de contenu déjà fourni dans la conversation
• Échanges conversationnels et salutations

Le déclenchement est orientable via votre « system prompt » (invite système) : vous pouvez encourager Claude à effectuer des recherches plus facilement ou à privilégier les réponses directes. Pour imposer une limite, utilisez max_uses pour plafonner le nombre de recherches dans un tour.

Filtrage dynamique

Avec la recherche web de base, chaque résultat de recherche est chargé dans la fenêtre de contexte de Claude, et une grande partie de ce contenu peut être sans rapport avec la requête. Avec web_search_20260209 ou une version ultérieure, Claude écrit et exécute plutôt du code qui filtre d’abord les résultats, de sorte que seul le contenu pertinent atteint la fenêtre de contexte. Cela réduit l’utilisation de tokens sur les requêtes impliquant de nombreuses recherches.

Le filtrage dynamique exécute la recherche web depuis l’exécution de code : sur web_search_20260209 et les versions ultérieures, le champ allowed_callers de l’outil a pour valeur par défaut ["code_execution_20260120"], et lorsque le filtrage dynamique s’exécute, l’API provisionne automatiquement l’exécution de code dont elle a besoin pour la requête. Vous n’avez pas besoin d’ajouter vous-même l’outil d’exécution de code à tools. Les appels d’exécution de code effectués de cette manière n’entraînent aucun frais supplémentaire au-delà des coûts standard en tokens.

Pour appeler la recherche web directement, sans filtrage dynamique, définissez allowed_callers: ["direct"]. Les modèles qui ne prennent pas en charge l’appel d’outils programmatique nécessitent ce paramètre. Sans lui, l’API renvoie une erreur 400 qui vous indique de le définir.

Les exemples suivants utilisent web_search_20260318 :

client = anthropic.Anthropic()

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

Comment utiliser la recherche web

Pour savoir comment les paramètres de recherche web de votre organisation s’appliquent dans les sessions Claude Managed Agents, consultez Restreindre les domaines de recherche web et de récupération web.

Fournissez l’outil de recherche web dans votre requête API :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "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"
  }
}

Toutes les versions de l’outil de recherche web acceptent allowed_callers, qui détermine si Claude appelle la recherche web directement ou depuis l’exécution de code via le filtrage dynamique. Sur web_search_20260209 et les versions ultérieures, sa valeur par défaut est ["code_execution_20260120"] au lieu de ["direct"]. Consultez ZDR et allowed_callers pour savoir comment le configurer. web_search_20260318 et les versions ultérieures acceptent également response_inclusion.

Nombre maximal d’utilisations

Le paramètre max_uses limite le nombre de recherches dans un même tour. Les requêtes portant sur un seul fait utilisent généralement 1 à 3 recherches ; les recherches comparatives ou portant sur plusieurs entités peuvent en utiliser 10 ou plus.

Les recherches échouées sont comptabilisées dans la limite. Si Claude appelle la recherche web directement plus de fois que le nombre autorisé, le web_search_tool_result est une erreur avec le code d’erreur max_uses_exceeded. Si Claude appelle la recherche web depuis l’exécution de code plus de fois que le nombre autorisé, l’exécution de code se termine par une erreur.

Un tour peut s’étendre sur plusieurs requêtes. Une requête poursuit un tour lorsqu’elle reprend après pause_turn ou lorsque son dernier message ne contient que des blocs tool_result. Les recherches des requêtes précédentes de ce tour sont comptabilisées dans la limite, sauf si Claude les a exécutées depuis l’exécution de code via le filtrage dynamique.

Filtrage de domaines

Fournissez allowed_domains ou blocked_domains, mais pas les deux. Si une requête inclut les deux, l’API renvoie une erreur 400. Les entrées sont des domaines nus avec un chemin facultatif, par exemple example.com ou example.com/blog, sans schéma.

Pour les règles complètes de filtrage de domaines, consultez Filtrage de domaines dans le guide des outils serveur.

Sur Claude Managed Agents, définissez ces champs sur l’entrée web_search de l’ensemble d’outils de l’agent ; consultez Restreindre les domaines de recherche web et de récupération web.

Localisation

Le paramètre user_location vous permet de localiser les résultats de recherche en fonction de l’emplacement d’un utilisateur. Fournissez au moins l’un des champs city, region, country ou timezone.

• type : le type d’emplacement (doit être approximate)
• city : le nom de la ville
• region : la région ou l’État
• country : le code pays à deux lettres ISO 3166-1 alpha-2 (l’API rejette un code non pris en charge avec une erreur 400)
• timezone : l’identifiant de fuseau horaire IANA

Sur Claude Managed Agents, l’entrée web_search de l’ensemble d’outils de l’agent accepte également user_location ; consultez les paramètres des outils web.

Inclusion dans la 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 la même réponse. Définissez "response_inclusion": "excluded" pour supprimer entièrement de la réponse ces paires imbriquées de blocs server_tool_use et de résultats, pour les flux de travail agentiques qui n’ont pas besoin du contenu brut des recherches. L’utilisation de tokens n’est pas affectée, car Claude lit la sortie du code plutôt que ces blocs. La valeur par défaut est "full". L’API renvoie toujours intégralement les résultats des appels directs, ou des appels d’exécution de code mis en pause avant d’être terminés, afin que vous puissiez les renvoyer dans la requête suivante.

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

Cet exemple montre une recherche directe. Lorsqu’une recherche s’exécute via le filtrage dynamique, la réponse contient également les blocs de résultats de l’outil d’exécution de code, et chaque paire imbriquée server_tool_use et web_search_tool_result comporte un champ caller identifiant l’appel d’exécution de code qui l’a effectuée.

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 : le contenu chiffré que vous devez renvoyer dans les conversations à plusieurs tours

Pour poursuivre une conversation contenant des résultats de recherche, renvoyez les blocs de contenu de l’assistant exactement tels que vous les avez reçus, y compris le encrypted_content de chaque résultat. L’API déchiffre ce contenu lors des requêtes suivantes pour restaurer les résultats de recherche dans le contexte de Claude. Si encrypted_content est manquant ou modifié, la requête échoue avec une erreur de validation 400.

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 à plusieurs tours
• cited_text : jusqu’à 150 caractères du contenu cité

Les champs de citation de la 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), la Claude API 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"
  }
}

En cas d’erreur, content est un objet d’erreur unique plutôt qu’une liste de blocs de résultats. Une recherche qui réussit mais ne trouve aucun résultat renvoie une liste content vide, et non une erreur.

Voici les codes d’erreur possibles :

• too_many_requests : limite de débit dépassée
• invalid_tool_input : paramètre de requête de recherche non valide
• 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
• request_too_large : la requête de recherche est trop volumineuse, généralement en raison d’une longue liste de filtres de domaines
• unavailable : une erreur interne s’est produite

Raison d’arrêt pause_turn

L’API peut mettre en pause un tour de recherche de longue durée et renvoyer stop_reason: "pause_turn". Pour continuer, renvoyez le message de l’assistant mis en pause, sans modification, dans une nouvelle requête.

Si Claude appelle la recherche web et l’un de vos outils client dans le même groupe d’appels d’outils parallèles, l’API renvoie plutôt stop_reason: "tool_use" et n’exécute pas encore la recherche. Pour continuer, renvoyez les résultats des outils client, et l’API exécute la recherche lors de la requête suivante. Consultez Combiner outils serveur et outils client dans un même tour.

Pour la boucle côté serveur et la gestion de pause_turn, consultez La boucle côté serveur et pause_turn dans le guide des outils serveur.

Mise en cache des prompts

Pour mettre en cache les définitions d’outils d’un tour à l’autre, consultez Utilisation d’outils avec la mise en cache des prompts.

Streaming

Lorsque le streaming est activé, vous recevez les événements de recherche dans le flux. Une pause se produit 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 runs

// 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 la Message Batches API. Les appels à l’outil de recherche web via la Message Batches API sont facturés au même prix que ceux effectués dans les requêtes classiques à la Messages API.

Pour protéger la capacité partagée, la Batches API limite les requêtes de recherche web pour chaque organisation ; les lots volumineux comportant de nombreuses recherches peuvent donc prendre plus de temps à se terminer. Vous pouvez consulter la limite de débit de recherche web de votre organisation sur la page Limites de débit de la Claude Console. Pour demander une limite plus élevée, contactez l’équipe commerciale depuis cette page.

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 pour 10 $ USD par 1 000 recherches, plus 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 « input tokens » (tokens d’entrée), aussi bien dans les itérations de recherche exécutées au cours d’un même tour que dans les tours de conversation suivants.

Chaque recherche web compte comme une utilisation, quel que soit le nombre de résultats renvoyés. Une recherche web qui échoue avec une erreur n’est pas facturée.

Étapes suivantes

Disponibilité