Outil de recherche sur le Web de Claude

L’outil de recherche Web donne à Claude un accès direct au contenu Web en temps réel, ce qui lui permet de répondre aux questions avec des informations à jour au-delà de son seuil de connaissances. Claude cite automatiquement les sources des résultats de recherche dans le cadre de sa réponse.

Modèles pris en charge

La recherche sur le Web est disponible à l’adresse suivante :

Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
Claude 3.5 Sonnet (nouveau) (claude-3-5-sonnet-latest)
Claude 3.5 Haïku (claude-3-5-haiku-latest)

Comment fonctionne la recherche sur le Web

Lorsque vous ajoutez l’outil de recherche Web à votre demande d’API :

Claude décide quand effectuer la recherche en fonction de l’invite.
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 demande.
À la fin de son tour, Claude fournit une réponse finale avec des sources citées.

Comment utiliser la recherche sur le Web

L’administrateur de votre organisation doit activer la recherche Web dans la console.

Fournissez l’outil de recherche Web dans votre demande d’API :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "How do I update a web app to TypeScript 5.5?"
        }
    ],
    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 :

JSON
{
  "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
  "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"
  }
}

Utilisations maximales

Le paramètre limite le nombre de recherches effectuées. Si Claude tente plus de recherches que ce qui est autorisé, il y aura une erreur avec le code d’erreur.max_usesweb_search_tool_resultmax_uses_exceeded

Filtrage de domaine

Lors de l’utilisation de filtres de domaine :

Les domaines ne doivent pas inclure le schéma HTTP/HTTPS (utilisez au lieu de example.comhttps://example.com)
Les sous-domaines sont automatiquement inclus ( couvertures example.comdocs.example.com)
Les sous-chemins sont pris en charge (example.com/blog)
Vous pouvez utiliser l’un ou l’autre ou , mais pas les deux dans la même demande.allowed_domainsblocked_domains

Localisation

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

type: Le type de lieu (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 de l’IANA.

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"
}

Résultats de la recherche

Les résultats de la recherche sont les suivants :

url: L’URL de la page source
title: Le titre de la page source
page_age: Date de la dernière mise à jour du site
encrypted_content: Contenu crypté qui doit être renvoyé dans des conversations à plusieurs tours pour les citations

Références

Les citations sont toujours activées pour la recherche sur le Web, et chacune comprend :web_search_result_location

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 repassée pour les conversations à plusieurs tours.
cited_text: Jusqu’à 150 caractères du contenu cité

Les champs de citation de recherche Web , , et ne sont pas pris en compte dans l’utilisation du jeton d’entrée ou de sortie.cited_texttitleurl

Erreurs

Si une erreur se produit lors d’une recherche sur le Web, vous recevrez une réponse qui se présente sous 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: Dépassement de la limite de débit
invalid_input: Paramètre de requête de recherche non valide
max_uses_exceeded: Dépassement du nombre maximal d’utilisations de l’outil de recherche web
query_too_long: La requête dépasse la longueur maximale
unavailable: Une erreur interne s’est produite

`pause_turn` Raison de l’arrêt

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

Mise en cache des invites

La recherche sur le Web fonctionne avec la mise en cache des invites. Pour activer la mise en cache des invites, ajoutez au moins un point d’arrêt cache_control dans votre demande. 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 au moment ou après le dernier bloc pour réutiliser le contenu mis en cache.cache_controlweb_search_tool_result

Par exemple, pour utiliser la mise en cache d’invite avec la recherche Web pour une conversation à plusieurs tours :

import anthropic

client = anthropic.Anthropic()

# First request with web search and cache breakpoint
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-3-7-sonnet-latest",
    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"
        }
    }]
)

# Add Claude's response to the conversation
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Second request with cache breakpoint after the search results
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # Cache up to this point
})

response2 = client.messages.create(
    model="claude-3-7-sonnet-latest",
    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"
        }
    }]
)
# The second response will benefit from cached search results
# while still being able to perform new searches if needed
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Streaming

Lorsque la diffusion en continu est activée, vous recevrez des é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", "value": "{\"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)

Demandes 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 au même prix que ceux des requêtes API Messages standard.

Utilisation et tarification

L’utilisation de la recherche Web est facturée en plus de l’utilisation du jeton :

"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 sur le Web est disponible sur l’API Anthropic pour 10 $ par 1 000 recherches, plus les coûts de jeton standard pour le contenu généré par la recherche. Les résultats de recherche Web dans la conversation sont comptés comme des jetons d’entrée sur les demandes d’achèvement ultérieures pendant le tour en cours ou sur les tours de conversation suivants.

Chaque recherche sur le Web compte pour une utilisation, quel que soit le nombre de résultats renvoyés. Si une erreur se produit lors d’une recherche sur le Web, la recherche sur le Web ne sera pas facturée.

Tutoriels - Anthropic

https://docs.anthropic.com/fr/docs/claude-code/tutorials#configurer-le-model-context-protocol-mcp

Table des matières

Web search tool - Anthropic

https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool

Premiers pas avec Claude Code - Anthropic

https://docs.anthropic.com/fr/docs/claude-code/getting-started

-----------------------------

Pierre Erol GIRAUDY

https://www.erolgiraudy.eu/

https://uga-ia.blogspot.com/

https://www.erolgiraudy.eu/2024/10/mes-15-livres.html

https://and500.blogspot.com/

https://www.ugaia.eu/

Pour Info : Mon livre https://amzn.eu/d/eTuHn56 sur AMAZON