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 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 des réponses pour les workflows 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.

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.



Fonctionnement de la récupération web

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 à partir de l'URL spécifiée.
3. Pour les PDF, une extraction automatique du texte est effectuée.
4. Claude analyse le contenu récupéré et fournit une réponse avec des citations optionnelles.



Quand Claude effectue une récupération

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 n'effectue pas de récupération pour des questions de culture générale ou des 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 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 à partir de documents volumineux. 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 documents longs
• 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 traitement de documents volumineux

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

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_20260209", "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
  "blocked_domains": ["private.example.com"],

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

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



Nombre maximal d'utilisations

Le paramètre max_uses limite le nombre de récupérations web effectuées. 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 aucune 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 permet de contrôler l'utilisation des tokens lors de la récupération de documents volumineux.



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 à jour ; la valeur par défaut est true. Ne désactivez la mise en cache que lorsque l'utilisateur demande explicitement du contenu à jour ou lors de la récupération de sources qui changent rapidement, car le contournement du cache augmente la latence.



Inclusion des réponses

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 cours du 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, réduisant ainsi les coûts en tokens de sortie pour les workflows 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 provenant d'appels directs, ou d'appels d'exécution de code qui se sont interrompus 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 optionnelles pour la récupération web. 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 : horodatage indiquant quand le contenu a été récupéré

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 :

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

Voici les codes d'erreur possibles :

• invalid_input : format d'URL invalide
• 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 et les restrictions du modèle
• 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 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

La récupération web fonctionne de manière transparente avec la recherche web pour une collecte d'informations complè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 workflow, Claude va :

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

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.



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

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 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 via l'API Messages Batches sont facturés au même tarif que ceux effectués dans les requêtes standard 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



Étapes suivantes