Herramienta de obtención web

La herramienta de obtención web (web fetch) permite a Claude recuperar el contenido completo de páginas web y documentos PDF especificados.

La versión más reciente de la herramienta de obtención web (web_fetch_20260318) admite filtrado dinámico con Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 y Claude Sonnet 4.6. Claude puede escribir y ejecutar código para filtrar el contenido obtenido antes de que llegue a la ventana de contexto, conservando solo la información relevante y descartando el resto. Esto reduce el consumo de tokens mientras mantiene la calidad de las respuestas. web_fetch_20260318 también añade control de inclusión de respuesta para flujos de trabajo agénticos. Las versiones anteriores (web_fetch_20260309 para filtrado dinámico y omisión de caché, web_fetch_20260209 solo para filtrado dinámico, web_fetch_20250910 para obtención básica) siguen disponibles.

La obtención web (con y sin filtrado dinámico) está disponible en la API de Claude, Claude Platform en AWS y Microsoft Foundry. En Microsoft Foundry, la obtención web requiere una implementación Hosted on Anthropic. Actualmente no está disponible en Amazon Bedrock ni en Google Cloud.

Para la elegibilidad de Zero Data Retention y la solución alternativa de allowed_callers, consulta Herramientas de servidor.

Para la compatibilidad de modelos, consulta la Referencia de herramientas.



Cómo funciona la obtención web

La obtención web es una herramienta de servidor: la API obtiene el contenido durante la solicitud e inserta los resultados en la conversación. No ejecutas nada ni devuelves un tool_result. La excepción es cuando Claude llama a la obtención web y a una de tus herramientas de cliente en el mismo grupo de llamadas paralelas a herramientas: la API devuelve la respuesta con stop_reason: "tool_use" antes de que esa obtención se haya ejecutado, y luego ejecuta la obtención cuando envías de vuelta los bloques tool_result del cliente. Consulta Combinar herramientas de servidor y herramientas de cliente en un mismo turno.

Cuando añades la herramienta de obtención web a tu solicitud de API:

1. Claude decide cuándo obtener contenido según el prompt y las URLs disponibles.
2. La API recupera el contenido de texto completo de la URL especificada.
3. Para PDFs, la API devuelve el contenido como datos codificados en base64 y lo procesa como un documento PDF adjunto directamente.
4. Claude analiza el contenido obtenido y proporciona una respuesta con citas opcionales.



Cuándo obtiene Claude

Claude realiza una obtención cuando la solicitud apunta a una página o documento específico:

• Se proporciona una URL en la conversación (o en un resultado de herramienta previo)
• El usuario nombra un recurso específico (un artículo en particular, un README, una página de precios o una sección de documentación) sin una URL, y la herramienta de búsqueda web también está habilitada para que Claude pueda localizarlo primero (consulta Búsqueda y obtención combinadas)

Claude no realiza obtenciones para preguntas de conocimiento general o abiertas que no hagan referencia a una página específica. "Resume este artículo: <url>" activa una obtención. "¿Cuáles son las mejores prácticas para el diseño de API REST?" se responde directamente.



Filtrado dinámico

Obtener páginas web y PDFs completos puede consumir tokens rápidamente, especialmente cuando solo se necesita información específica de documentos grandes. Con web_fetch_20260209 o posterior, Claude puede escribir y ejecutar código para filtrar el contenido obtenido antes de cargarlo en el contexto.

Este filtrado dinámico es particularmente útil para:

• Extraer secciones específicas de documentos largos
• Procesar datos estructurados de páginas web
• Filtrar información relevante de PDFs
• Reducir costos de tokens al trabajar con documentos grandes

Para habilitar el filtrado dinámico, usa web_fetch_20260209 o cualquier versión posterior. Los siguientes ejemplos usan 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)



Cómo usar la obtención web

Proporciona la herramienta de obtención web en tu solicitud de 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)



Definición de la herramienta

La herramienta de obtención web admite los siguientes parámetros:

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

Las versiones posteriores de la herramienta añaden dos parámetros opcionales más: use_cache requiere web_fetch_20260309 o posterior (consulta Omisión de caché), y response_inclusion requiere web_fetch_20260318 o posterior (consulta Inclusión de respuesta).



Usos máximos

El parámetro max_uses limita el número de obtenciones web realizadas. Las obtenciones fallidas cuentan para el límite. Si Claude intenta más obtenciones de las permitidas, el web_fetch_tool_result es un error con el código de error max_uses_exceeded. Actualmente no hay un límite predeterminado.



Filtrado de dominios

Para el filtrado de dominios con allowed_domains y blocked_domains, consulta Herramientas de servidor.



Límites de contenido

El parámetro max_content_tokens limita la cantidad de contenido incluido en el contexto. Si el contenido obtenido excede este límite, la herramienta lo trunca. Esto ayuda a controlar el uso de tokens al obtener documentos grandes. El límite se aplica al contenido de texto, no al contenido binario como los PDFs.



Omisión de caché

El parámetro use_cache controla si se puede devolver contenido almacenado en caché. Establece "use_cache": false para omitir la caché y obtener contenido actualizado. El valor predeterminado es true. Deshabilita el almacenamiento en caché solo cuando el usuario solicite explícitamente contenido actualizado o cuando obtengas fuentes que cambian rápidamente, porque omitir la caché aumenta la latencia.

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



Inclusión de respuesta

El parámetro response_inclusion controla cómo aparecen los bloques de resultados de obtención en la respuesta de la API cuando el resultado fue consumido por una llamada de ejecución de código completada en el mismo turno. Establece "response_inclusion": "excluded" para eliminar por completo esos pares anidados de server_tool_use y bloques de resultados de la respuesta, reduciendo los costos de tokens de salida para flujos de trabajo agénticos que no necesitan devolver el contenido sin procesar de la página al cliente. El valor predeterminado es "full". Los resultados de llamadas directas, o de llamadas de ejecución de código que se pausaron antes de completarse, siempre se devuelven completos para que puedan enviarse de vuelta en el siguiente turno.

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



Citas

A diferencia de la búsqueda web, donde las citas siempre están habilitadas, las citas son opcionales para la obtención web y están deshabilitadas de forma predeterminada. Establece "citations": {"enabled": true} para permitir que Claude cite pasajes específicos de los documentos obtenidos.



Respuesta

Aquí tienes un ejemplo de estructura de respuesta:

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



Resultados de obtención

Los resultados de obtención incluyen:

• url: La URL que se obtuvo
• content: Un bloque de documento que contiene el contenido obtenido
• retrieved_at: Marca de tiempo de cuándo se recuperó el contenido

Para documentos PDF, el contenido se devuelve como datos codificados 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"
  }
}



Errores

Cuando la herramienta de obtención web encuentra un error, la API de Claude devuelve una respuesta 200 (éxito) con el error representado en el cuerpo de la respuesta. Claude ve el resultado de error y continúa el turno. Por ejemplo:

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

Estos son los posibles códigos de error:

• invalid_tool_input: Entrada de herramienta no válida, como una URL mal formada o un esquema que no es HTTP(S)
• url_too_long: La URL excede la longitud máxima (250 caracteres)
• url_not_allowed: URL bloqueada por reglas de filtrado de dominios (incluyendo la configuración de tu organización) o por restricciones del lado de Anthropic, como direcciones privadas y robots.txt
• url_not_in_prior_context: La URL no apareció anteriormente en la conversación (consulta Validación de URL)
• url_not_accessible: Error al obtener el contenido (error HTTP)
• too_many_requests: Límite de velocidad excedido
• unsupported_content_type: Tipo de contenido no admitido (solo texto, HTML y PDF)
• max_uses_exceeded: Se excedió el número máximo de usos de la herramienta de obtención web
• unavailable: Ocurrió un error interno



Validación de URL

Por razones de seguridad, la herramienta de obtención web solo puede obtener URLs que hayan aparecido previamente en el contexto de la conversación. Esto incluye:

• URLs en mensajes del usuario
• URLs en resultados de herramientas del lado del cliente
• URLs de resultados previos de búsqueda web u obtención web

La herramienta no puede obtener URLs arbitrarias que Claude genere ni URLs de herramientas de servidor basadas en contenedores (Code Execution, Bash, etc.).



Búsqueda y obtención combinadas

Cuando tanto la herramienta de búsqueda web como la de obtención web están habilitadas, y el usuario nombra una página o documento específico sin proporcionar una URL (por ejemplo, "lee el README del repositorio anthropics/anthropic-sdk-python"), Claude usa la búsqueda web para localizarlo y luego obtiene el resultado. El siguiente ejemplo solicita una búsqueda y un análisis en una sola solicitud:

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)

En este flujo de trabajo, Claude:

1. Usa la búsqueda web para encontrar artículos relevantes.
2. Selecciona los resultados más prometedores.
3. Usa la obtención web para recuperar el contenido completo.
4. Proporciona un análisis detallado con citas.



Almacenamiento en caché de prompts

Para almacenar en caché las definiciones de herramientas entre turnos, consulta Uso de herramientas con almacenamiento en caché de prompts.



Streaming

Con el streaming habilitado, los eventos de obtención forman parte del flujo con una pausa durante la recuperación de contenido:

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...



Solicitudes por lotes

Puedes incluir la herramienta de obtención web en la Messages Batches API. Las llamadas a la herramienta de obtención web a través de la Messages Batches API tienen el mismo precio que las de las solicitudes regulares de la Messages API.



Uso y precios

El uso de web fetch no tiene cargos adicionales más allá de los costos estándar de 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
    }
  }
}

La herramienta web fetch está disponible en la API de Claude sin costo adicional. Solo pagas los costos estándar de tokens por el contenido obtenido que pasa a formar parte del contexto de tu conversación.

Para protegerte contra la obtención inadvertida de contenido de gran tamaño que consumiría una cantidad excesiva de tokens, usa el parámetro max_content_tokens para establecer límites apropiados según tu caso de uso y consideraciones de presupuesto.

Ejemplo de uso de tokens para contenido típico:

• Página web promedio (10 kB): ~2,500 tokens
• Página de documentación grande (100 kB): ~25,000 tokens
• PDF de artículo de investigación (500 kB): ~125,000 tokens



Próximos pasos