L’outil de recherche web donne à Claude un accès direct au contenu web en temps réel, lui permettant de répondre à des questions avec des informations à jour au-delà de sa date limite de connaissances. Claude cite automatiquement les sources des résultats de recherche dans sa réponse.

N’hésitez pas à nous contacter via notre formulaire de commentaires pour partager votre expérience avec l’outil de recherche web.

​
Modèles pris en charge

La recherche web est disponible sur :

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (nouveau) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Comment fonctionne la recherche web

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

  1. Claude décide quand effectuer une recherche en fonction de la requête.
  2. L’API exécute les recherches et fournit à Claude les résultats. 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 les sources citées.

​
Comment utiliser la recherche web

L’administrateur de votre organisation doit activer la recherche web dans la Console.

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Comment mettre à jour une application web vers TypeScript 5.5 ?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Définition de l’outil

L’outil de recherche web prend en charge les paramètres suivants :

JSON
{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optionnel : Limite le nombre de recherches par requête
  "max_uses": 5,

  // Optionnel : Inclure uniquement les résultats de ces domaines
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optionnel : Ne jamais inclure les résultats de ces domaines
  "blocked_domains": ["untrustedsource.com"],

  // Optionnel : Localiser les résultats de recherche
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

​
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 sera une erreur avec le code d’erreur max_uses_exceeded.

​
Filtrage de domaine

Lors de l’utilisation des filtres de domaine :

  • Les domaines ne doivent pas inclure le protocole HTTP/HTTPS (utilisez example.com au lieu de https://example.com)
  • Les sous-domaines sont automatiquement inclus (example.com couvre docs.example.com)
  • Les sous-chemins sont pris en charge (example.com/blog)
  • Vous pouvez utiliser soit allowed_domains soit blocked_domains, mais pas les deux dans la même requête.

​
Localisation

Le paramètre user_location vous permet de localiser les résultats de recherche en fonction de l’emplacement d’un utilisateur.

  • type : Le type d’emplacement (doit être approximate)
  • city : Le nom de la ville
  • region : La région ou l’état
  • country : Le pays
  • timezone : L’ID de fuseau horaire IANA.

​
Réponse

Voici un exemple de structure de réponse :

{
  "role": "assistant",
  "content": [
    // 1. La décision de Claude de rechercher
    {
      "type": "text",
      "text": "Je vais rechercher quand Claude Shannon est né."
    },
    // 2. La requête de recherche utilisée
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon date de naissance"
      }
    },
    // 3. Résultats de recherche
    {
      "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": "D'après les résultats de recherche, ",
      "type": "text"
    },
    // 4. Réponse de Claude avec citations
    {
      "text": "Claude Shannon est né le 30 avril 1916 à 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"
}

​
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 : Quand le site a été mis à jour pour la dernière fois
  • encrypted_content : Contenu chiffré qui doit être renvoyé dans les conversations à plusieurs tours pour les citations

​
Citations

Les citations sont toujours activées pour la recherche web, et chaque web_search_result_location comprend :

  • 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 recherche web cited_text, title et url ne sont pas comptabilisés dans l’utilisation des tokens d’entrée ou de sortie.

Lorsque vous affichez des résultats web ou des informations contenues dans des résultats web aux utilisateurs finaux, les citations en ligne doivent être clairement visibles et cliquables dans votre interface utilisateur.

​
Erreurs

Si une erreur se produit pendant la recherche web, vous recevrez une réponse qui prend la forme suivante :

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Voici les codes d’erreur possibles :

  • too_many_requests : Limite de débit dépassée
  • invalid_input : Paramètre de requête de recherche invalide
  • max_uses_exceeded : Nombre maximum d’utilisations de l’outil de recherche web dépassé
  • query_too_long : La requête dépasse la longueur maximale
  • unavailable : Une erreur interne s’est produite

​
Raison d’arrêt pause_turn

La réponse peut inclure une raison d’arrêt pause_turn, qui indique que l’API a mis en pause un tour de longue durée. Vous pouvez renvoyer la réponse telle quelle dans une requête ultérieure pour permettre à Claude de continuer son tour, ou modifier le contenu si vous souhaitez interrompre la conversation.

​
Mise en cache des requêtes

La recherche web fonctionne avec la mise en cache des requêtes. Pour activer la mise en cache des requêtes, ajoutez au moins un point d’arrêt cache_control dans votre requête. Le système mettra automatiquement en cache jusqu’au dernier bloc web_search_tool_result lors de l’exécution de l’outil.

Pour les conversations à plusieurs tours, définissez un point d’arrêt cache_control sur ou après le dernier bloc web_search_tool_result pour réutiliser le contenu mis en cache.

Par exemple, pour utiliser la mise en cache des requêtes avec la recherche web pour une conversation à plusieurs tours :

import anthropic

client = anthropic.Anthropic()

# Première requête avec recherche web et point d'arrêt de cache
messages = [
    {
        "role": "user",
        "content": "Quel est le temps actuel à San Francisco aujourd'hui ?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Ajouter la réponse de Claude à la conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Deuxième requête avec point d'arrêt de cache après les résultats de recherche
messages.append({
    "role": "user",
    "content": "Dois-je m'attendre à de la pluie plus tard cette semaine ?",
    "cache_control": {"type": "ephemeral"}  # Mettre en cache jusqu'à ce point
})

response2 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# La deuxième réponse bénéficiera des résultats de recherche mis en cache
# tout en étant capable d'effectuer de nouvelles recherches si nécessaire
print(f"Tokens de lecture du cache : {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Avec le streaming activé, vous recevrez des événements de recherche dans le 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": ""}}

// Décision de Claude de rechercher

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Requête de recherche diffusée
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"dernières avancées en informatique quantique 2025\"}"}}

// Pause pendant l'exécution de la recherche

// Résultats de recherche diffusés
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": "Avancées en informatique quantique en 2025", "url": "https://example.com"}]}}

// Réponse de Claude avec citations (omise dans cet exemple)

​
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 de la même manière que ceux des requêtes API Messages régulières.

​
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 Anthropic 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 comptabilisés comme des tokens d’entrée, dans les itérations de recherche exécutées pendant un seul tour et 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, la recherche web ne sera pas facturée.