Outil de récupération web

L'outil de récupération web (web fetch) 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 avec Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 et Claude Sonnet 4.6. Claude peut écrire et exécuter du code pour filtrer le contenu récupéré avant qu'il n'atteigne la 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. web_fetch_20260318 ajoute également le contrôle de l'inclusion de réponse pour les flux de travail agentiques. Les versions précédentes (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) restent disponibles.

La récupération web (avec et sans filtrage dynamique) est disponible sur l'API Claude, Claude Platform sur AWS et Microsoft Foundry. Sur Microsoft Foundry, la récupération web nécessite un déploiement Hosted on Anthropic. Elle n'est actuellement pas disponible sur Amazon Bedrock ou Google Cloud.

Pour l'éligibilité à la rétention 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.



Comment fonctionne 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 clients 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 Mélanger les outils serveur et les outils clients dans un même tour.

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

1. Claude décide 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 récupère

Claude effectue une récupération lorsque la requête pointe vers 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 (voir Recherche et récupération combinées)

Claude ne récupère pas pour les 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 pour la 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 grands 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 à partir de pages web
• Filtrer les informations pertinentes à partir de PDF
• Réduire les coûts en tokens lors du travail avec de grands 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 :

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



Utilisations maximales

Le paramètre max_uses limite le nombre de récupérations web effectuées. Les récupérations échouées comptent dans la 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'y a actuellement pas de limite par défaut.



Filtrage de domaines

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



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 grands documents. La limite s'applique au contenu textuel, pas au contenu binaire tel que les PDF.



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 changeant rapidement, car le contournement du cache augmente la latence.

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



Inclusion de 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é dans le même tour. Définissez "response_inclusion": "excluded" pour supprimer entièrement ces paires imbriquées de blocs server_tool_use et de résultats de la réponse, réduisant ainsi les coûts en tokens de sortie pour les flux de travail agentiques qui n'ont pas besoin de renvoyer le contenu brut de la page au client. La valeur par défaut est "full". Les résultats des appels directs, ou des appels d'exécution de code qui se sont mis en pause avant de se terminer, sont toujours renvoyés intégralement afin de pouvoir être renvoyés au tour suivant.

{
  "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 voit 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 invalide, telle qu'une URL mal formée ou un schéma non 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 et robots.txt
• url_not_in_prior_context : l'URL n'est pas apparue plus tôt dans la conversation (voir 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)
• 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 qui sont 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 provenant 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 arbitraires générées par Claude ni des URL provenant d'outils serveur basés sur des conteneurs (exécution de code, Bash, etc.).



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 en 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 récupérer le contenu complet.
4. Fournit une analyse détaillée avec des citations.



Mise en cache des prompts

Pour la mise en cache des définitions d'outils entre les tours, consultez Utilisation d'outils avec la mise en cache des prompts.



Streaming

Avec le streaming 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 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 de l'outil de récupération web via l'API Messages Batches sont facturés au même tarif que ceux des requêtes régulières de l'API Messages.



Utilisation et tarification

L'utilisation de la récupération web n'entraîne aucuns frais supplémentaires 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 l'API Claude 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 contenu volumineux qui consommerait 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'usage et de vos considérations budgétaires.

Exemple d'utilisation de tokens pour du contenu typique :

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



Prochaines étapes