Outil de recherche web

L'outil de recherche web (« web search tool ») 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, ou « dynamic filtering »), en ne conservant que les informations pertinentes. Le filtrage dynamique est disponible avec les modèles Claude 4.6 et 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 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.

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 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 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
• Échanges conversationnels et salutations

Le déclenchement est orientable via votre « system prompt » (invite système) : vous pouvez encourager Claude à rechercher plus volontiers ou à préférer répondre directement. Pour une contrainte stricte, utilisez max_uses afin de 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 à la place 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 jetons pour 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 nécessaire à 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 de jetons standard.

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",
    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

Ces paramètres au niveau de l'organisation dans la Claude Console s'appliquent uniquement aux requêtes de l'API Messages. Les sessions Claude Managed Agents utilisent uniquement les listes allowed_domains et blocked_domains par outil définies sur l'ensemble d'outils de l'agent ; 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",
    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.

Nombre maximal d'utilisations

Le paramètre max_uses limite le nombre de recherches effectuées. Si Claude tente plus de recherches que ce qui est 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 par domaine

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 optionnel, par exemple example.com ou example.com/blog, sans schéma.

Pour l'ensemble des règles de filtrage par domaine, consultez Filtrage par domaine 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 les codes pays 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 un objet user_location avec les mêmes champs. L'API rejette un code country non pris en charge avec une erreur 400 lorsque vous créez ou mettez à jour l'agent, ou lorsque vous créez ou mettez à jour une session qui fournit ce paramètre. Consultez Restreindre les domaines de recherche web et de récupération 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é au cours du même tour. Définissez "response_inclusion": "excluded" pour supprimer entièrement de la réponse ces paires imbriquées de blocs server_tool_use et de blocs de résultat, réduisant ainsi les coûts de jetons de sortie pour les flux de travail agentiques qui n'ont pas besoin de renvoyer le contenu brut des recherches au client. La valeur par défaut est "full". Les résultats des appels directs, ou des appels d'exécution de code mis en pause avant d'être terminés, 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"
}

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ésultat 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 : 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 tours suivants 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 jetons 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 selon 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, 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 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 domaine
• 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 à la place stop_reason: "tool_use" et n'exécute pas encore la recherche. Pour continuer, renvoyez les résultats de l'outil client, et l'API exécute la recherche lors de la requête suivante. Consultez Combiner des outils serveur et des 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 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 à l'outil de recherche web via l'API Messages Batches sont facturés au même tarif que ceux des requêtes classiques de l'API Messages.

Pour protéger la capacité partagée, l'API Batches limite les 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 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 la Claude API pour 10 $ 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 comptés comme tokens d'entrée, aussi bien dans les itérations de recherche exécutées au cours d'un seul 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. Si une erreur se produit pendant la recherche web, celle-ci ne sera pas facturée.

Étapes suivantes