Herramienta de obtención web

La herramienta de obtención web 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: 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. 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 otras versiones (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) están disponibles.

La obtención web (con y sin filtrado dinámico) está disponible en la Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) y Microsoft Foundry. En Microsoft Foundry, las implementaciones alojadas en Azure solo admiten la herramienta básica de obtención web (web_fetch_20250910, sin filtrado dinámico). Las implementaciones alojadas en Anthropic admiten todas las versiones.

Para conocer la elegibilidad para la retención cero de datos y la solución alternativa con allowed_callers, consulta Herramientas de servidor.

Para conocer 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 a herramientas en paralelo: la API devuelve la respuesta con stop_reason: "tool_use" antes de que se haya ejecutado esa obtención, 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 turno.

Cuando agregas 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 contenido 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 previo de herramienta)
• 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 obtiene contenido para preguntas de conocimiento general o abiertas que no hacen 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 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

Para saber cómo se aplica la configuración de obtención web de tu organización en las sesiones de Claude Managed Agents, consulta Restringir dominios de búsqueda web y 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=4096,
    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
  "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: Don't fetch URLs that appear only in client-side tool results
  "url_sources": {
    "client_tool_results": { "type": "none" }
  },

  // 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 en la respuesta).

Usos máximos

El parámetro max_uses limita el número de obtenciones web en un solo turno. Las obtenciones fallidas cuentan para el límite. Si Claude llama a la obtención web directamente más veces de las permitidas, el web_fetch_tool_result es un error con el código de error max_uses_exceeded. Si Claude llama a la obtención web desde la ejecución de código más veces de las permitidas, la ejecución de código termina con un error. No hay un límite predeterminado.

Un turno puede abarcar varias solicitudes. Una solicitud continúa un turno cuando se reanuda después de pause_turn o cuando su último mensaje contiene solo bloques tool_result. Las obtenciones de solicitudes anteriores en ese turno cuentan para el límite, a menos que Claude las haya ejecutado desde la ejecución de código mediante filtrado dinámico.

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; 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 es aproximado: el número real de tokens de entrada usados puede variar ligeramente. El límite se aplica al contenido de texto, no al contenido binario como los PDFs.

Si un PDF obtenido hace que la solicitud supere los límites de páginas o de tamaño de PDF, el web_fetch_tool_result es un error con el código de error content_too_large. Los PDFs y las imágenes que ya están en la conversación cuentan para esos límites, por lo que eliminarlos puede permitir que la obtención tenga éxito.

En Claude Managed Agents, la entrada web_fetch del conjunto de herramientas del agente también acepta max_content_tokens; consulta la configuración de herramientas 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. Desactiva la caché solo cuando el usuario solicite explícitamente contenido actualizado o al obtener fuentes que cambian rápidamente, ya que omitir la caché aumenta la latencia.

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

Inclusión en la 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 completada de ejecución de código en la misma respuesta. Establece "response_inclusion": "excluded" para eliminar por completo de la respuesta esos pares anidados de bloques server_tool_use y de resultado, en flujos de trabajo agénticos que no necesitan el contenido bruto de la página. El uso de tokens no se ve afectado, porque Claude lee la salida del código en lugar de estos bloques. El valor predeterminado es "full". La API siempre devuelve completos los resultados de llamadas directas, o de llamadas de ejecución de código que se pausaron antes de completarse, para que puedas enviarlos de vuelta en la siguiente solicitud.

{
  "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 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 Claude API devuelve una respuesta 200 (éxito) con el error representado en el cuerpo de la respuesta. Claude recibe 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 códigos de error posibles:

• 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ó antes en la conversación, o apareció solo en fuentes que url_sources excluye (consulta Validación de URL)
• url_not_accessible: No se pudo obtener el contenido (error HTTP)
• too_many_requests: Se superó el límite de velocidad
• unsupported_content_type: Tipo de contenido no admitido (solo texto, HTML y PDF)
• content_too_large: El PDF obtenido haría que la solicitud superara los límites de páginas o de tamaño de PDF (consulta Límites de contenido)
• max_uses_exceeded: Se superó el número máximo de usos de la herramienta de obtención web
• unavailable: Se produjo 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 que aparezcan solo en la propia salida de Claude o solo 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. De forma predeterminada, 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 lo 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.

Fuentes de URL

El parámetro opcional url_sources te permite desactivar cualquiera de las tres fuentes permitidas, o limitar los resultados de herramientas a ciertas herramientas. Tiene una clave para cada fuente, y cada clave tiene como valor predeterminado {"type": "all"}:

• user_input: URLs en mensajes del usuario. Su type es "all" o "none".
• client_tool_results: URLs en resultados de herramientas del lado del cliente. Su type es "all", "none", o un filtro "only" o "except" que nombra herramientas, como en el siguiente ejemplo.
• server_tool_results: URLs de resultados previos de búsqueda web u obtención web. Acepta los mismos valores, y sus filtros nombran web_search o web_fetch.

Por ejemplo, una herramienta que ejecuta código escrito por Claude devuelve lo que ese código imprima, incluida cualquier URL que Claude haya puesto en él. Para evitar que los resultados de esa herramienta cuenten como fuente, nómbrala en un filtro "except":

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "url_sources": {
        "client_tool_results": {
          "type": "except",
          "tools": [{ "type": "tool_reference", "name": "run_code" }]
        }
      }
    },
    {
      "name": "run_code",
      "description": "Run Python code and return its output",
      "input_schema": {
        "type": "object",
        "properties": { "code": { "type": "string" } },
        "required": ["code"]
      }
    }
  ]
}

Un filtro enumera las herramientas como objetos tool_reference. Cada nombre debe coincidir con una herramienta del arreglo tools de la solicitud: una herramienta de cliente para client_tool_results, o una herramienta de servidor para server_tool_results. De lo contrario, la solicitud falla con un error. Con "except", una herramienta que agregues a tools más adelante cuenta como fuente. Con "only", no cuenta.

Las herramientas del lado del cliente distintas de run_code también pueden devolver texto escrito por Claude, por ejemplo en un mensaje de error que lo cita. Para excluir todos los resultados de herramientas del lado del cliente, establece client_tool_results en {"type": "none"}.

Si una URL apareció solo en fuentes que url_sources excluye, obtenerla devuelve el error url_not_in_prior_context.

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 stream, con una pausa durante la recuperación del 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 runs

// 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 Message Batches API. Las llamadas a la herramienta de obtención web a través de la Message Batches API tienen el mismo precio que las de las solicitudes normales a la Messages API.

Uso y precios

El uso de la obtención web 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 de obtención web 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

Disponibilidad