Outil de récupération web

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 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), en ne conservant que les informations pertinentes et en écartant le reste. Cela réduit la consommation de tokens tout en maintenant la qualité des réponses. Le filtrage dynamique est disponible avec Claude 4.6 et les modèles ultérieurs ainsi qu’avec Claude Mythos Preview. web_fetch_20260318 ajoute également le contrôle de l’inclusion dans la réponse pour les flux de travail agentiques. Les autres versions (web_fetch_20260309 pour le filtrage dynamique et le contournement du cache, web_fetch_20260209 pour le filtrage dynamique uniquement, web_fetch_20250910 pour la récupération de base) sont disponibles.

La récupération web (avec et sans filtrage dynamique) est disponible sur l’API Claude, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) 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 sur Anthropic prennent en charge toutes les versions.

Pour l’éligibilité à la conservation zéro des données (Zero Data Retention) 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 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. L’exception est lorsque Claude appelle la récupération web et l’un de vos outils client dans le même groupe d’appels d’outils parallèles : l’API renvoie la réponse avec stop_reason: "tool_use" avant que cette récupération n’ait été exécutée, puis exécute 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 directement joint.
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 (un article particulier, un README, une page de tarification ou une section de documentation) sans URL, et l’outil de recherche web est également activé afin que Claude puisse d’abord la localiser (consultez Recherche et récupération combinées)

Claude n’effectue pas de récupération pour des questions de culture générale ou 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 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-5-5",
    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

Pour savoir comment les paramètres de récupération web de votre organisation s’appliquent dans les sessions Claude Managed Agents, consultez Restreindre les domaines de recherche web et de 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-5-5",
    max_tokens=4096,
    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 :

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

  // Optional: Limit the number of fetches
  "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: Don't fetch URLs that appear only in client-side tool results
  "url_sources": {
    "client_tool_results": { "type": "none" }
  },

  // 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 : use_cache nécessite web_fetch_20260309 ou une version ultérieure (consultez Contournement du cache), et response_inclusion nécessite web_fetch_20260318 ou une version ultérieure (consultez Inclusion dans la réponse).

Nombre maximal d’utilisations

Le paramètre max_uses limite le nombre de récupérations web au cours d’un seul tour. Les récupérations échouées sont comptabilisées dans la limite. Si Claude appelle directement la récupération web plus de fois que le nombre autorisé, le web_fetch_tool_result est une erreur avec le code d’erreur max_uses_exceeded. Si Claude appelle la récupération web depuis l’exécution de code plus de fois que le nombre autorisé, l’exécution du code se termine par une erreur. Il n’existe aucune limite par défaut.

Un tour peut s’étendre sur plusieurs requêtes. Une requête poursuit un tour lorsqu’elle reprend après pause_turn ou lorsque son dernier message ne contient que des blocs tool_result. Les récupérations issues de requêtes antérieures de ce tour sont comptabilisées dans la limite, sauf si Claude les a exécutées depuis l’exécution de code via le filtrage dynamique.

Filtrage de domaines

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

Sur Claude Managed Agents, définissez ces champs dans l’entrée web_fetch de l’ensemble d’outils de l’agent ; 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 aide à contrôler l’utilisation des tokens lors de la récupération de gros documents. La limite est approximative : le nombre réel de tokens d’entrée utilisés peut varier légèrement. La limite s’applique au contenu textuel, et non au contenu binaire tel que les PDF.

Si un PDF récupéré fait dépasser à la requête les limites de pages ou de taille des PDF, le web_fetch_tool_result est une erreur avec le code d’erreur content_too_large. Les PDF et les images déjà présents dans la conversation sont comptabilisés dans ces limites ; les supprimer peut donc permettre à la récupération de réussir.

Sur Claude Managed Agents, l’entrée web_fetch de l’ensemble d’outils de l’agent accepte également max_content_tokens ; consultez les paramètres des outils web.

Contournement du cache

Le paramètre use_cache contrôle si du contenu mis en cache peut être renvoyé. Définissez "use_cache": false pour contourner le cache et récupérer du contenu frais. La valeur par défaut est true. Ne désactivez la mise en cache que lorsque l’utilisateur demande explicitement du contenu frais ou lors de la récupération de sources qui changent rapidement, car le contournement du cache augmente la « latency » (latence).

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

Inclusion dans la réponse

Le paramètre response_inclusion contrôle la manière dont les blocs de résultats de récupération apparaissent dans la réponse de l’API lorsque le résultat a été consommé par un appel d’exécution de code terminé au sein de la même réponse. 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, pour les flux de travail agentiques qui n’ont pas besoin du contenu brut des pages. L’utilisation des tokens n’est pas affectée, car Claude lit la sortie du code plutôt que ces blocs. La valeur par défaut est "full". L’API renvoie toujours intégralement les résultats des appels directs, ou des appels d’exécution de code mis en pause avant leur achèvement, afin que vous puissiez les renvoyer dans la requête suivante.

{
  "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 :

{
  "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 incluent :

• 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 :

{
  "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) avec l’erreur représentée dans le corps de la réponse. Claude reçoit le résultat d’erreur et poursuit le tour. Par exemple :

{
  "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 non valide, 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 de 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, ou n’est apparue que dans des sources exclues par url_sources (consultez Validation des URL)
• url_not_accessible : échec de la récupération du contenu (erreur HTTP)
• too_many_requests : limite de débit dépassée
• unsupported_content_type : type de contenu non pris en charge (uniquement texte, HTML et PDF)
• content_too_large : le PDF récupéré ferait dépasser à la requête les limites de pages ou de taille des PDF (consultez Limites de contenu)
• 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 des URL déjà apparues dans le contexte de la conversation. Cela inclut :

• Les URL dans les messages de l’utilisateur
• Les URL 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 des 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, tels que l’exécution de code, le connecteur MCP ou la recherche d’outils, ne constituent pas non plus une source autorisée. Par défaut, les résultats d’outils côté client sont une source autorisée, même lorsqu’ils reprennent du texte produit par Claude (par exemple, une commande qui affiche son entrée, ou un message d’erreur qui la cite).

L’outil refuse également une URL qui semble contenir un identifiant, tel qu’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.

Sources d’URL

Le paramètre facultatif url_sources vous permet de désactiver l’une des trois sources autorisées, ou de limiter les résultats d’outils à certains outils. Il comporte une clé pour chaque source, et chaque clé vaut {"type": "all"} par défaut :

• user_input : les URL dans les messages de l’utilisateur. Son type est "all" ou "none".
• client_tool_results : les URL dans les résultats d’outils côté client. Son type est "all", "none", ou un filtre "only" ou "except" qui nomme des outils, comme dans l’exemple suivant.
• server_tool_results : les URL issues de résultats précédents de recherche web ou de récupération web. Il accepte les mêmes valeurs, et ses filtres nomment web_search ou web_fetch.

Par exemple, un outil qui exécute du code écrit par Claude renvoie tout ce que ce code affiche, y compris toute URL que Claude y a placée. Pour empêcher les résultats de cet outil d’être considérés comme une source, nommez-le dans un filtre "except" :

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "url_sources": {
        "client_tool_results": {
          "type": "except",
          "tools": [{ "type": "tool_reference", "name": "run_code" }]
        }
      }
    },
    {
      "name": "run_code",
      "description": "Run Python code and return its output",
      "input_schema": {
        "type": "object",
        "properties": { "code": { "type": "string" } },
        "required": ["code"]
      }
    }
  ]
}

Un filtre répertorie les outils sous forme d’objets tool_reference. Chaque nom doit correspondre à un outil du tableau tools de la requête : un outil client pour client_tool_results, ou un outil serveur pour server_tool_results. Sinon, la requête échoue avec une erreur. Avec "except", un outil que vous ajoutez ultérieurement à tools est considéré comme une source. Avec "only", il ne l’est pas.

Les outils côté client autres que run_code peuvent également renvoyer du texte écrit par Claude, par exemple dans un message d’erreur qui le cite. Pour exclure tous les résultats d’outils côté client, définissez client_tool_results sur {"type": "none"}.

Si une URL n’est apparue que dans des sources exclues par url_sources, sa récupération renvoie l’erreur url_not_in_prior_context.

Recherche et récupération combinées

Lorsque les outils de recherche web et de récupération web sont tous deux activés, et que l’utilisateur nomme 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 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-5-5",
    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 :

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 runs

// 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 Message Batches. Les appels à l’outil de récupération web via l’API Message 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

Disponibilité