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_20260209) prend en charge le filtrage dynamique avec 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 conservant uniquement les informations pertinentes et en supprimant le reste. Cela réduit la consommation de jetons tout en maintenant la qualité des réponses. La version précédente de l'outil (web_fetch_20250910) reste disponible sans filtrage dynamique.

Pour l'admissibilité à la rétention zéro des données et la solution de contournement allowed_callers, voir Outils serveur.

Pour le support du modèle, voir la Référence des outils.

Comment fonctionne 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 le contenu en fonction de l'invite et des URLs disponibles.
2. L'API récupère le contenu texte complet de l'URL spécifiée.
3. Pour les PDF, l'extraction de texte automatique est effectuée.
4. Claude analyse le contenu récupéré et fournit une réponse avec des citations optionnelles.

Filtrage dynamique

La récupération de pages web et de PDF complets peut rapidement consommer des jetons, en particulier lorsque seules des informations spécifiques sont nécessaires à partir de documents volumineux. Avec la version de l'outil web_fetch_20260209, 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 les données structurées des pages web
• Filtrer les informations pertinentes des PDF
• Réduire les coûts en jetons lors du travail avec de grands documents

Pour activer le filtrage dynamique, utilisez la version de l'outil web_fetch_20260209 :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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-7",
    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
}

Max uses

Le paramètre max_uses limite le nombre de récupérations web effectuées. Si Claude tente plus de récupérations que 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 domaine

Pour le filtrage de domaine avec allowed_domains et blocked_domains, voir 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 jetons lors de la récupération de documents volumineux.

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 du moment où le contenu a été récupéré

Pour les documents PDF, le contenu est retourné sous forme de données codé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 retourne 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 domaine 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 (texte et PDF uniquement)
• max_uses_exceeded : Nombre maximum d'utilisations de l'outil de récupération web dépassé
• unavailable : Une erreur interne s'est produite

Validation d'URL

Pour des raisons de sécurité, l'outil de récupération web ne peut récupérer que les URLs qui ont précédemment apparues dans le contexte de la conversation. Cela inclut :

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

L'outil ne peut pas récupérer les URLs arbitraires que Claude génère ou les URLs 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-7",
    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},
        },
    ],
)

Dans ce flux de travail, 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

Mise en cache des invites

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

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 lot

Vous pouvez inclure l'outil de récupération web dans l'API Messages Batches. Les appels d'outils de récupération web via l'API Messages Batches sont facturés de la même manière que ceux dans les requêtes régulières de l'API Messages.

Utilisation et tarification

Web fetch usage has no additional charges beyond standard token costs:

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

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

• Average web page (10 kB): ~2,500 tokens
• Large documentation page (100 kB): ~25,000 tokens
• Research paper PDF (500 kB): ~125,000 tokens

Étapes suivantes