L'outil de recherche web — Claude sur Google Cloud (Vertex AI / Agent Platform)

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 : la plateforme exécute les recherches, et vous n’écrivez aucune implémentation. Sur Google Cloud, il demande en revanche une autorisation explicite de votre organisation.

Un outil serveur

C’est la troisième famille de la leçon 21 : vous activez l’outil dans la requête, le serveur fait le reste. D’après Google, les recherches passent par un moteur tiers, Brave Search. 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],
)

L’autoriser sur Google Cloud

Le cours officiel ne le dit pas, mais c’est le premier obstacle que vous rencontrerez : sur Google Cloud, la recherche web est désactivée par défaut. La contrainte de politique d’organisation constraints/vertexai.allowedPartnerModelFeatures doit l’autoriser explicitement, ce que règle un administrateur de l’organisation. Deux autres points relèvent de la gouvernance :

si le projet se trouve dans un périmètre VPC Service Controls, les requêtes qui utilisent l’outil sont rejetées avec une erreur 400 ;
pendant leur traitement par le moteur de recherche tiers, les données ne bénéficient plus des engagements d’Agent Platform comme les clés de chiffrement gérées par le client (CMEK) ou la résidence des données.

Google recommande de peser ces deux points avant d’ouvrir l’outil.

Une seule version sur Vertex

Sur Google Cloud, offre gérée par Google, seule la version de base existe : web_search_20250305. L’API Claude propose aussi des versions plus récentes, web_search_20260209 et web_search_20260318, avec un filtrage dynamique : Claude y écrit et exécute du code qui trie les résultats avant qu’ils n’entrent dans son contexte. Ces versions ne sont pas disponibles sur Vertex. Si vous reprenez du code écrit pour l’API Claude, remplacez le type de l’outil par la version de base.

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

D'après la leçon « The web search tool » (Claude Academy, Claude on Google Cloud) et la page Web search tool (documentation Claude).

Bloc	Contenu
`text`	Les phrases de Claude, par exemple « Je vais chercher les dernières publications. »
`server_tool_use`	La recherche lancée, avec sa requête : `{"query": "…"}`
`web_search_tool_result`	Les résultats ; pour chacun, `url`, `title`, `page_age` et un `encrypted_content`
`text` avec `citations`	Les phrases appuyées sur une source ; chaque citation donne `url`, `title` et `cited_text`, le passage cité

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 28, 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 28 fait déjà exactement cela.

Le coût

D’après la grille de Google Cloud, 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 supplémentaires. 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. Vérifiez d’abord avec votre administrateur que la politique d’organisation autorise la recherche web. Ajoutez ensuite l’outil, limité à impots.gouv.fr, à l’assistant de la leçon 28, 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) · Server tools (boucle côté serveur et pause_turn) · Web search with Anthropic Claude models (Google Cloud : politique d’organisation, VPC Service Controls, moteur tiers) · Partner models pricing (Google Cloud : tarif des recherches)

Points clés à retenir

Outil serveur : la plateforme exécute les recherches, vous lisez la réponse.
Désactivé par défaut sur Google Cloud : la politique d’organisation constraints/vertexai.allowedPartnerModelFeatures doit l’autoriser.
Sur Vertex, seule la version de base web_search_20250305 existe.
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.