Claude Platform Docs
MessagesHerramientas

Herramienta de obtención web

Obtén y lee contenido de URLs específicas para ampliar el contexto de Claude con contenido web en vivo.

La herramienta de obtención web ("web fetch tool") 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 web fetch (web_fetch_20260318) admite "dynamic filtering" (filtrado dinámico): Claude puede escribir y ejecutar código para filtrar el contenido obtenido antes de que llegue a la "context window" (ventana de contexto), conservando solo la información relevante y descartando el resto. Esto reduce el consumo de tokens sin afectar la calidad de las respuestas. El filtrado dinámico está disponible con Claude 4.6 y modelos posteriores, y con Claude Mythos Preview. web_fetch_20260318 también añade control de inclusión en la 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 Claude API, Claude Platform en AWS y Microsoft Foundry. En Microsoft Foundry, las implementaciones alojadas en Azure admiten solo la herramienta de obtención web básica (web_fetch_20250910, sin filtrado dinámico). Las implementaciones alojadas en Anthropic admiten todas las versiones. La obtención web no está disponible actualmente 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 ("server tool"): 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 a herramientas en paralelo: 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 determina 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 adjuntado directamente.
  4. Claude analiza el contenido obtenido y proporciona una respuesta con citas opcionales.

Cuándo obtiene Claude

Claude obtiene contenido 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, README, página de precios o sección de documentación en particular) 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 obtiene contenido para preguntas de conocimiento general o abiertas que no hacen referencia a una página específica. "Resume este artículo: <url>" desencadena una obtención. "¿Cuáles son las mejores prácticas para el diseño de APIs 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 los 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_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)

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-5-5",
    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:

JSON
{
  "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.

En Claude Managed Agents, establece estos campos en la entrada web_fetch del conjunto de herramientas del agente, donde cada dominio listado debe ser un nombre de host simple sin ruta; consulta Restringir dominios de búsqueda web y obtención web.

Límites de contenido

El parámetro max_content_tokens limita la cantidad de contenido incluido en el contexto. Si el contenido obtenido supera 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.

En Claude Managed Agents, la entrada web_fetch del conjunto de herramientas del agente también acepta max_content_tokens; consulta Restringir dominios de búsqueda web y obtención web.

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 la caché únicamente cuando el usuario solicite explícitamente contenido actualizado o cuando obtengas fuentes que cambian rápidamente, ya que omitir la caché aumenta la "latency" (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 resultado 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 de la respuesta esos pares anidados de bloques server_tool_use y de resultado, 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

Este es un ejemplo de la estructura de respuesta:

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

Output
{
  "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 Claude API 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:

Output
{
  "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 supera la longitud máxima (250 caracteres)
  • url_not_allowed: URL bloqueada por las reglas de filtrado de dominios (incluida la configuración de tu organización) o por restricciones del lado de Anthropic, como direcciones privadas, robots.txt y URLs que parecen contener una credencial que no proporcionaste
  • url_not_in_prior_context: La URL no apareció anteriormente en la conversación (consulta Validación de URLs)
  • url_not_accessible: No se pudo obtener el contenido (error HTTP)
  • too_many_requests: Se superó el "rate limit" (límite de velocidad)
  • unsupported_content_type: Tipo de contenido no admitido (solo texto, HTML y PDF)
  • max_uses_exceeded: Se superó el número máximo de usos de la herramienta de obtención web
  • unavailable: Ocurrió un error interno

Validación de URLs

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 que aparezcan únicamente en la propia salida de Claude o únicamente en la indicación del sistema. Para que una URL de la indicación del sistema se pueda obtener, inclúyela también en un mensaje del usuario. Los resultados de otras herramientas del lado del servidor, como la ejecución de código, el conector MCP o la búsqueda de herramientas, tampoco son una fuente permitida. Los resultados de herramientas del lado del cliente son una fuente permitida incluso cuando repiten texto que Claude produjo (por ejemplo, un comando que imprime su entrada o un mensaje de error que la cita).

La herramienta también rechaza una URL que parezca contener una credencial, como una clave de API o una contraseña, a menos que esa credencial aparezca en la indicación del sistema o en el texto de un mensaje del usuario. Una credencial que aparece solo en un resultado de herramienta no cuenta. El resultado es un error url_not_allowed. Para obtener una URL de este tipo, inclúyela en un mensaje del usuario.

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

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 del contenido:

Output
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 API de Messages Batches. Las llamadas a la herramienta de obtención web a través de la API de Messages Batches tienen el mismo precio que las de las solicitudes normales 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 Claude API 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 grande que consumiría tokens en exceso, 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

Herramienta de ejecución de código

Ejecuta código Python y bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.

Herramientas de servidor

Trabaja con herramientas ejecutadas por Anthropic: bloques server_tool_use, continuación con pause_turn y filtrado de dominios.

Referencia de herramientas

Directorio de herramientas proporcionadas por Anthropic y referencia de las propiedades opcionales de definición de herramientas.

Was this page helpful?