Claude Platform Docs
MessagesOutils

Outil de récupération web

Récupérez et lisez le contenu d'URL spécifiques pour enrichir le contexte de Claude avec du contenu web en direct.

L'outil de récupération web permet à Claude de récupérer le contenu complet de pages web et de documents PDF spécifiés.

La dernière version de l'outil de récupération web (web_fetch_20260318) prend en charge le « dynamic filtering » (filtrage dynamique) : Claude peut écrire et exécuter du code pour filtrer le contenu récupéré avant qu'il n'atteigne la « context window » (fenêtre de contexte). Il ne conserve ainsi que les informations pertinentes et écarte le reste. Cela réduit la consommation de « tokens » (jetons) tout en maintenant la qualité des réponses. Le filtrage dynamique est disponible avec Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 et Claude Sonnet 4.6. web_fetch_20260318 ajoute également le contrôle de l'inclusion dans la réponse pour les « agentic workflows » (flux de travail agentiques). Les versions précédentes restent disponibles : web_fetch_20260309 pour le filtrage dynamique et le contournement du cache, web_fetch_20260209 pour le filtrage dynamique uniquement, et web_fetch_20250910 pour la récupération de base.

La récupération web (avec et sans filtrage dynamique) est disponible sur l'API Claude, Claude Platform on AWS et Microsoft Foundry. Sur Microsoft Foundry, les déploiements hébergés sur Azure ne prennent en charge que l'outil de récupération web de base (web_fetch_20250910, sans filtrage dynamique). Les déploiements hébergés par Anthropic prennent en charge toutes les versions. La récupération web n'est actuellement pas disponible sur Amazon Bedrock ni sur Google Cloud.

Pour l'éligibilité à la « Zero Data Retention » (conservation zéro des données) et la solution de contournement allowed_callers, consultez Outils serveur.

Pour la prise en charge des modèles, consultez la Référence des outils.

Fonctionnement de la récupération web

La récupération web est un « server tool » (outil serveur) : l'API récupère le contenu pendant la requête et insère les résultats dans la conversation. Vous n'exécutez rien et ne renvoyez pas de tool_result.

Il existe une exception. Claude peut appeler la récupération web et l'un de vos outils client dans le même groupe d'appels d'outils parallèles. Dans ce cas, l'API renvoie la réponse avec stop_reason: "tool_use" avant que cette récupération n'ait été exécutée. Elle exécute ensuite la récupération lorsque vous renvoyez les blocs tool_result du client. Consultez Combiner des outils serveur et des outils client dans un même tour.

Lorsque vous ajoutez l'outil de récupération web à votre requête API :

  1. Claude détermine quand récupérer du contenu en fonction du prompt et des URL disponibles.
  2. L'API récupère le contenu textuel complet de l'URL spécifiée.
  3. Pour les PDF, l'API renvoie le contenu sous forme de données encodées en base64 et le traite comme un document PDF joint directement.
  4. Claude analyse le contenu récupéré et fournit une réponse avec des citations facultatives.

Quand Claude effectue une récupération

Claude effectue une récupération lorsque la requête désigne une page ou un document spécifique :

  • Une URL est fournie dans la conversation (ou dans un résultat d'outil précédent)
  • L'utilisateur nomme une ressource spécifique sans URL (un article particulier, un README, une page de tarifs ou une section de documentation), et l'outil de recherche web est également activé pour que Claude puisse d'abord la localiser (consultez Recherche et récupération combinées)

Claude n'effectue pas de récupération pour les questions de culture générale ou les questions ouvertes qui ne font pas référence à une page spécifique. « Résume cet article : <url> » déclenche une récupération. « Quelles sont les bonnes pratiques de conception d'API REST ? » reçoit une réponse directe.

Filtrage dynamique

La récupération de pages web et de PDF complets peut rapidement consommer des tokens, en particulier lorsque seules des informations spécifiques sont nécessaires dans de gros documents. Avec web_fetch_20260209 ou une version ultérieure, Claude peut écrire et exécuter du code pour filtrer le contenu récupéré avant de le charger dans le contexte.

Ce filtrage dynamique est particulièrement utile pour :

  • Extraire des sections spécifiques de longs documents
  • Traiter des données structurées provenant de pages web
  • Filtrer les informations pertinentes dans des PDF
  • Réduire les coûts en tokens lors du travail avec de gros documents

Pour activer le filtrage dynamique, utilisez web_fetch_20260209 ou toute version ultérieure. Les exemples suivants utilisent web_fetch_20260318 :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260318", "name": "web_fetch"}],
)
print(response)

Comment utiliser la récupération web

Fournissez l'outil de récupération web dans votre requête API :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)

Définition de l'outil

L'outil de récupération web prend en charge les paramètres suivants :

JSON
{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

Les versions ultérieures de l'outil ajoutent deux paramètres facultatifs supplémentaires :

Nombre maximal d'utilisations

Le paramètre max_uses limite le nombre de récupérations web effectuées. Les récupérations échouées sont comptabilisées dans cette limite. Si Claude tente plus de récupérations que le nombre autorisé, le web_fetch_tool_result est une erreur avec le code d'erreur max_uses_exceeded. Il n'existe actuellement aucune limite par défaut.

Filtrage des domaines

Pour le filtrage des domaines avec allowed_domains et blocked_domains, consultez Outils serveur.

Sur Claude Managed Agents, définissez ces champs sur l'entrée web_fetch de l'ensemble d'outils de l'agent. Chaque domaine listé doit être un simple nom d'hôte, sans chemin. Consultez Restreindre les domaines de recherche web et de récupération web.

Limites de contenu

Le paramètre max_content_tokens limite la quantité de contenu incluse dans le contexte. Si le contenu récupéré dépasse cette limite, l'outil le tronque. Cela permet de contrôler l'utilisation des tokens lors de la récupération de gros documents. La limite s'applique au contenu textuel, et non au contenu binaire tel que les PDF.

Sur Claude Managed Agents, l'entrée web_fetch de l'ensemble d'outils de l'agent accepte également max_content_tokens. Consultez Restreindre les domaines de recherche web et de récupération web.

Contournement du cache

Le paramètre use_cache détermine si du contenu mis en cache peut être renvoyé. Définissez "use_cache": false pour contourner le cache et récupérer du contenu à jour. La valeur par défaut est true. Le contournement du cache augmente la « latency » (latence). Ne désactivez donc la mise en cache que lorsque l'utilisateur demande explicitement du contenu à jour ou lorsque vous récupérez des sources qui changent rapidement.

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}

Inclusion dans la réponse

Le paramètre response_inclusion détermine comment les blocs de résultats de récupération apparaissent dans la réponse de l'API. Il s'applique lorsque le résultat a été consommé par un appel d'exécution de code terminé dans le 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 résultats. Cela réduit les coûts en tokens de sortie pour les flux de travail agentiques qui n'ont pas besoin de renvoyer le contenu brut des pages au client. La valeur par défaut est "full".

Certains résultats sont toujours renvoyés en intégralité afin de pouvoir être renvoyés au tour suivant. Il s'agit des résultats d'appels directs et des résultats d'appels d'exécution de code qui ont été mis en pause avant de se terminer.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}

Citations

Contrairement à la recherche web, où les citations sont toujours activées, les citations sont facultatives pour la récupération web et désactivées par défaut. Définissez "citations": {"enabled": true} pour permettre à Claude de citer des passages spécifiques des documents récupérés.

Réponse

Voici un exemple de structure de réponse :

Output
{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude's analysis with citations (if enabled)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Résultats de récupération

Les résultats de récupération comprennent :

  • url : l'URL qui a été récupérée
  • content : un bloc de document contenant le contenu récupéré
  • retrieved_at : l'horodatage de la récupération du contenu

Pour les documents PDF, le contenu est renvoyé sous forme de données encodées en base64 :

Output
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}

Erreurs

Lorsque l'outil de récupération web rencontre une erreur, l'API Claude renvoie une réponse 200 (succès) dont le corps contient l'erreur. Claude voit le résultat d'erreur et poursuit le tour. Par exemple :

Output
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

Voici les codes d'erreur possibles :

  • invalid_tool_input : entrée d'outil invalide, comme une URL mal formée ou un schéma autre que HTTP(S)
  • url_too_long : l'URL dépasse la longueur maximale (250 caractères)
  • url_not_allowed : URL bloquée par les règles de filtrage des domaines (y compris les paramètres de votre organisation) ou par des restrictions côté Anthropic, telles que les adresses privées, robots.txt et les URL qui semblent contenir un identifiant que vous n'avez pas fourni
  • url_not_in_prior_context : l'URL n'est pas apparue plus tôt dans la conversation (consultez Validation des URL)
  • url_not_accessible : échec de la récupération du contenu (erreur HTTP)
  • too_many_requests : « rate limit » (limite de débit) dépassée
  • unsupported_content_type : type de contenu non pris en charge (uniquement texte, HTML et PDF)
  • max_uses_exceeded : nombre maximal d'utilisations de l'outil de récupération web dépassé
  • unavailable : une erreur interne s'est produite

Validation des URL

Pour des raisons de sécurité, l'outil de récupération web ne peut récupérer que les URL déjà apparues dans le contexte de la conversation. Cela inclut :

  • Les URL présentes dans les messages de l'utilisateur
  • Les URL présentes dans les résultats d'outils côté client
  • Les URL issues de résultats précédents de recherche web ou de récupération web

L'outil ne peut pas récupérer les URL qui apparaissent uniquement dans la propre sortie de Claude ou uniquement dans l'invite système. Pour qu'une URL de l'invite système puisse être récupérée, incluez-la également dans un message de l'utilisateur.

Les résultats d'autres outils côté serveur ne constituent pas non plus une source autorisée. C'est le cas de l'exécution de code, du connecteur MCP et de la recherche d'outils.

Les résultats d'outils côté client constituent une source autorisée, même lorsqu'ils reprennent du texte produit par Claude. Par exemple, une commande peut afficher son entrée, ou un message d'erreur peut la citer.

L'outil refuse également une URL qui semble contenir un identifiant, comme une clé API ou un mot de passe, sauf si cet identifiant apparaît dans l'invite système ou dans le texte d'un message de l'utilisateur. Un identifiant qui apparaît uniquement dans un résultat d'outil n'est pas pris en compte. Le résultat est une erreur url_not_allowed. Pour récupérer une telle URL, incluez-la dans un message de l'utilisateur.

Recherche et récupération combinées

Lorsque les outils de recherche web et de récupération web sont tous deux activés, l'utilisateur peut nommer une page ou un document spécifique sans fournir d'URL (par exemple, « lis le README du dépôt anthropics/anthropic-sdk-python »). Claude utilise alors la recherche web pour le localiser, puis récupère le résultat. L'exemple suivant demande une recherche et une analyse dans une seule requête :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)
print(response)

Dans ce flux de travail, Claude :

  1. Utilise la recherche web pour trouver des articles pertinents.
  2. Sélectionne les résultats les plus prometteurs.
  3. Utilise la récupération web pour obtenir le contenu complet.
  4. Fournit une analyse détaillée avec des citations.

Mise en cache des prompts

Pour mettre en cache les définitions d'outils d'un tour à l'autre, consultez Utilisation d'outils avec la mise en cache des prompts.

Streaming

Lorsque le streaming est activé, les événements de récupération font partie du flux, avec une pause pendant la récupération du contenu :

Output
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 fetch

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

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude's response continues...

Requêtes par lots

Vous pouvez inclure l'outil de récupération web dans l'API Messages Batches. Les appels à l'outil de récupération web effectués via l'API Messages Batches sont facturés au même tarif que ceux des requêtes classiques à l'API Messages.

Utilisation et tarification

L'utilisation de la récupération web (web fetch) n'entraîne aucun frais supplémentaire au-delà des coûts standard en tokens :

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

L'outil de récupération web est disponible sur la Claude API sans coût supplémentaire. Vous ne payez que les coûts standard en tokens pour le contenu récupéré qui devient partie intégrante du contexte de votre conversation.

Pour vous protéger contre la récupération involontaire de contenus volumineux qui consommeraient un nombre excessif de tokens, utilisez le paramètre max_content_tokens afin de définir des limites appropriées en fonction de votre cas d'utilisation et de vos considérations budgétaires.

Exemple d'utilisation de tokens pour un contenu typique :

  • Page web moyenne (10 kB) : ~2 500 tokens
  • Grande page de documentation (100 kB) : ~25 000 tokens
  • Article de recherche au format PDF (500 kB) : ~125 000 tokens

Étapes suivantes

Outil d'exécution de code

Exécutez du code Python et bash dans un conteneur isolé pour analyser des données, générer des fichiers et itérer sur des solutions.

Outils serveur

Travaillez avec les outils exécutés par Anthropic : blocs server_tool_use, poursuite après pause_turn et filtrage des domaines.

Référence des outils

Répertoire des outils fournis par Anthropic et référence des propriétés facultatives de définition d'outils.

Was this page helpful?