L'outil de recherche web

Avec l’outil de recherche web, Claude cherche lui-même sur Internet les informations récentes ou spécialisées dont il a besoin, et cite ses sources. C’est un outil serveur : Anthropic exécute les recherches, et vous n’écrivez aucune implémentation.

Un outil serveur

C’est la troisième famille de la leçon 31 : vous activez l’outil dans la requête, les serveurs d’Anthropic font le reste. Dans une même requête, Claude peut lancer une recherche, lire les résultats, chercher à nouveau, puis rédiger. Vous ne construisez aucun tool_result : la réponse vous arrive avec les recherches déjà faites.

Activer l’outil

web_search_tool = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
}

response = client.messages.create(
    model=model,
    max_tokens=4096,
    messages=[{"role": "user", "content": "Quelles sont les dernières recommandations publiées par l'ANSSI ?"}],
    tools=[web_search_tool],
)

Le cours officiel demande d’activer d’abord la recherche web dans les réglages de l’organisation. D’après la documentation actuelle, elle est activée par défaut, sauf si un administrateur l’a désactivée dans les réglages de la Claude Console, où il peut aussi restreindre les domaines consultés. Dans ce cas, la requête échoue avec une erreur 400 qui l’indique.

Trois versions

Le filtrage dynamique réduit les jetons consommés par les demandes riches en recherches. L’exécution de code qu’il utilise est fournie automatiquement, sans frais en plus des jetons. Cette leçon utilise la version de base, dont la réponse est la plus simple à lire.

Les réglages

• max_uses plafonne le nombre de recherches par requête. Au-delà, le résultat de recherche porte l’erreur max_uses_exceeded.
• allowed_domains limite les recherches à certains domaines, blocked_domains en exclut. L’un ou l’autre, pas les deux : une requête qui contient les deux reçoit une erreur 400. On écrit les domaines sans protocole, avec un chemin facultatif : nih.gov, example.com/blog.
• user_location adapte les résultats au lieu de l’utilisateur : ville, région, pays ou fuseau horaire.

web_search_tool = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
    "allowed_domains": ["nih.gov"],
}

Le cours officiel prend l’exemple de conseils de santé et d’exercice physique : en limitant la recherche à nih.gov, qui héberge PubMed, on obtient des sources scientifiques plutôt que des billets de blog.

La réponse

Ces blocs sont pensés pour l’affichage : le texte comme contenu, les résultats comme liste de sources, les citations en ligne avec le domaine, le titre, l’adresse et le passage cité. L’utilisateur voit d’où vient chaque affirmation.

Pour poursuivre la conversation, renvoyez les blocs de Claude exactement tels que reçus, encrypted_content compris : l’API en a besoin pour restituer les résultats aux tours suivants, et une valeur absente ou modifiée provoque une erreur 400. add_assistant_message(messages, response) fait exactement cela.

Pause, et mélange avec vos outils

Une recherche longue peut s’arrêter avec stop_reason à pause_turn. Le travail n’est pas fini : renvoyez la conversation, réponse en pause comprise et sans rien y ajouter, pour que Claude reprenne. Avec la boucle de la leçon 38, il suffit de relancer run_conversation sur le même historique.

Si Claude demande dans la même réponse la recherche web et l’un de vos outils, stop_reason vaut tool_use et la recherche n’a pas encore été faite. Renvoyez les résultats de vos outils, seuls, sans texte, avec le même tableau tools : l’API lance la recherche à la requête suivante. La boucle de la leçon 38 fait déjà exactement cela.

Le coût

Chaque recherche est facturée 10 dollars les 1 000, en plus des jetons : les résultats récupérés comptent comme jetons d’entrée, dans le tour où ils arrivent et dans les tours suivants. Une recherche en erreur n’est pas facturée. Le champ usage.server_tool_use.web_search_requests de la réponse donne le nombre de recherches effectuées.

Quand Claude cherche

D’après la documentation, Claude cherche pour l’actualité et les annonces récentes, les prix, taux ou statistiques du moment, les informations sur des organisations, des personnes ou des produits qui ont pu changer, et les demandes explicites de recherche. Il répond sans chercher sur les connaissances stables, l’écriture créative ou l’analyse d’un contenu déjà fourni. Ce comportement s’oriente par le prompt système ; pour une limite ferme, il y a max_uses.

À vous de jouer

Une recherche sourcée. Ajoutez l’outil de recherche web, limité à impots.gouv.fr, à l’assistant de la leçon 38, puis demandez la date limite de la prochaine déclaration de revenus. Affichez la réponse avec ses citations, puis le nombre de recherches indiqué dans usage.

Sources officielles : The web search tool (Claude Academy) · Web search tool (documentation Claude : versions, réglages, réponse, tarif) · Server tools (boucle côté serveur et pause_turn)

Points clés à retenir

• Outil serveur : Anthropic exécute les recherches, vous lisez la réponse.
• Activé par défaut, sauf si un administrateur l’a désactivé dans la Claude Console.
• max_uses, allowed_domains ou blocked_domains (jamais les deux), user_location.
• La réponse contient la requête, les résultats et les citations ; renvoyez-la intacte, encrypted_content compris.
• 10 dollars les 1 000 recherches, plus les jetons des résultats.