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 fenêtre de contexte (filtrage dynamique), en ne conservant que les informations pertinentes. Le filtrage dynamique est disponible avec les modèles Claude 4.6 et ultérieurs et 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 rétention zéro des données (Zero Data Retention) 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.



Comment fonctionne 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 en dehors de 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 qui pourraient avoir changé
• Demandes explicites de rechercher ou de vérifier quelque chose

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
• Écriture créative ou brainstorming
• Analyse de contenu déjà fourni dans la conversation
• Tours de conversation et salutations

Le déclenchement peut être orienté via votre invite système : vous pouvez encourager Claude à rechercher plus facilement ou à préférer répondre directement. Pour une contrainte stricte, utilisez max_uses pour plafonner le nombre de recherches pour chaque requête.



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 nécessitant de nombreuses recherches.

Le filtrage dynamique exécute la recherche web depuis l'intérieur de 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. Il n'y a pas de frais supplémentaires pour les appels d'exécution de code effectués de cette manière 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 programmatique d'outils 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",
    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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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.
  // 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 contrôle 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 Outils serveur pour savoir comment le configurer. web_search_20260318 et les versions ultérieures acceptent également response_inclusion.



Utilisations maximales

Le paramètre max_uses limite le nombre de recherches effectuées. Si Claude tente 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 portant sur plusieurs entités peuvent en utiliser 10 ou plus. Pour des conseils sur le choix d'une valeur, consultez Outils serveur.



Filtrage de domaines

Fournissez allowed_domains ou blocked_domains, 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 optionnel, 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.



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 éléments suivants : 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 les codes pays non pris en charge avec une erreur 400.
• timezone : l'identifiant de fuseau horaire IANA.



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 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 flux de travail agentiques qui n'ont pas besoin de renvoyer le contenu brut de la recherche au client. La valeur par défaut est "full". Les résultats des appels directs, ou des appels d'exécution de code qui se sont mis en pause avant de se terminer, sont toujours renvoyés intégralement afin qu'ils puissent ê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"
}

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

Pour poursuivre une conversation qui contient 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 tours ultérieurs 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 multi-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 (comme l'atteinte des 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 en utilisant 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 correspond à aucun résultat renvoie une liste content vide, pas 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 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
• 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 stop_reason: "tool_use" à la place et n'exécute pas encore la recherche. Pour continuer, renvoyez les résultats des outils client, et l'API exécute la recherche dans la requête suivante. Consultez Mélanger les outils serveur et les 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 la mise en cache des définitions d'outils entre les tours, consultez Utilisation d'outils avec la mise en cache des prompts.



Streaming

Avec le streaming activé, vous recevrez les é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 de l'outil de recherche web via l'API Messages Batches sont facturés au même tarif que ceux des requêtes régulières de l'API Messages.

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 à se terminer. Vous pouvez consulter la limite de débit de recherche web de votre organisation sur la page Limits dans la Claude Console. Pour demander une limite plus élevée, contactez le service commercial 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 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.



Prochaines étapes