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_20260209) admite filtrado dinámico con Claude Opus 4.8, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 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. La versión anterior de la herramienta (web_fetch_20250910) sigue disponible sin filtrado dinámico.

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

Cuando agregas 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 los PDFs, se realiza una extracción automática de texto.
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 anterior)
• 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 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 la versión de herramienta web_fetch_20260209, 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 la versión de herramienta 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
  "blocked_domains": ["private.example.com"],

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

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



Usos máximos

El parámetro max_uses limita el número de obtenciones web realizadas. 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.



Citas

A diferencia de la búsqueda web, donde las citas siempre están habilitadas, las citas son opcionales para la obtención web. 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:

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

Estos son los posibles códigos de error:

• invalid_input: Formato de URL no válido
• url_too_long: La URL excede la longitud máxima (250 caracteres)
• url_not_allowed: URL bloqueada por reglas de filtrado de dominios y restricciones del modelo
• url_not_accessible: No se pudo obtener el contenido (error HTTP)
• too_many_requests: Límite de velocidad excedido
• unsupported_content_type: Tipo de contenido no admitido (solo texto 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 (Ejecución de código, Bash, etc.).



Búsqueda y obtención combinadas

La obtención web funciona perfectamente con la búsqueda web para una recopilación integral de información:

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. Usará la búsqueda web para encontrar artículos relevantes
2. Seleccionará los resultados más prometedores
3. Usará la obtención web para recuperar el contenido completo
4. Proporcionará un análisis detallado con citas

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.



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 API de lotes de mensajes. Las llamadas a la herramienta de obtención web a través de la API de lotes de mensajes tienen el mismo precio que las de las solicitudes regulares de la API de mensajes.



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