Herramienta de búsqueda web

La herramienta de búsqueda web le da a Claude acceso directo a contenido web en tiempo real, lo que le permite responder preguntas con información actualizada más allá de su fecha límite de conocimiento. La respuesta incluye citas de las fuentes obtenidas de los resultados de búsqueda.

Con web_search_20260209 y versiones posteriores, Claude puede escribir y ejecutar código que filtra los resultados de búsqueda antes de que lleguen a la “context window” (ventana de contexto) (filtrado dinámico), conservando solo la información relevante. El filtrado dinámico está disponible con Claude 4.6 y modelos posteriores y con Claude Mythos Preview.

Hay tres versiones disponibles de la herramienta de búsqueda web:

• web_search_20250305: búsqueda web básica
• web_search_20260209: agrega filtrado dinámico
• web_search_20260318: agrega control de inclusión en la respuesta para flujos de trabajo agénticos

Los ejemplos de esta página usan web_search_20250305 para la búsqueda básica y web_search_20260318 para el filtrado dinámico.

Para conocer la elegibilidad de la búsqueda web para la retención cero de datos y la configuración relacionada de allowed_callers, consulta Herramientas de servidor.

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

Para comprobar si un modelo acepta la búsqueda web antes de enviar una solicitud, lee su valor capabilities.server_tools.web_search.supported desde la Models API. Uso de la Models API describe el campo.

Cómo funciona la búsqueda web

Cuando agregas la herramienta de búsqueda web a tu solicitud de API:

1. Claude determina cuándo buscar según el prompt.
2. La API ejecuta las búsquedas y le proporciona los resultados a Claude. Este proceso puede repetirse varias veces a lo largo de una sola solicitud.
3. Al final de su turno, Claude proporciona una respuesta final con fuentes citadas.

Cuándo busca Claude

Claude busca cuando la solicitud depende de información actual, cambiante o fuera de sus datos de entrenamiento:

• Eventos, noticias o anuncios recientes
• Precios, tasas, puntuaciones o estadísticas actuales
• Información sobre organizaciones, personas o productos específicos que podría haber cambiado
• Solicitudes explícitas de buscar o consultar algo

Claude responde directamente sin buscar cuando la solicitud se basa en conocimiento estable:

• Hechos establecidos, matemáticas, fundamentos de ciencias o conceptos de programación
• Escritura creativa o lluvia de ideas
• Análisis de contenido ya proporcionado en la conversación
• Turnos conversacionales y saludos

Puedes orientar cuándo se activa la búsqueda mediante tu “system prompt” (indicación del sistema): puedes animar a Claude a buscar con más facilidad o a preferir responder directamente. Para imponer un límite, usa max_uses para limitar el número de búsquedas en un turno.

Filtrado dinámico

Con la búsqueda web básica, cada resultado de búsqueda se carga en la ventana de contexto de Claude, y gran parte de ese contenido puede ser irrelevante para la solicitud. Con web_search_20260209 o posterior, Claude en cambio escribe y ejecuta código que primero filtra los resultados, de modo que solo el contenido relevante llega a la ventana de contexto. Esto reduce el uso de tokens en solicitudes con muchas búsquedas.

El filtrado dinámico ejecuta la búsqueda web desde dentro de la ejecución de código: en web_search_20260209 y posteriores, el campo allowed_callers de la herramienta tiene como valor predeterminado ["code_execution_20260120"], y cuando se ejecuta el filtrado dinámico, la API aprovisiona automáticamente la ejecución de código que necesita para la solicitud. No necesitas agregar tú mismo la herramienta de ejecución de código a tools. No hay cargos adicionales por las llamadas de ejecución de código realizadas de esta manera más allá de los costos estándar de tokens.

Para llamar a la búsqueda web directamente, sin filtrado dinámico, establece allowed_callers: ["direct"]. Los modelos que no admiten la llamada programática de herramientas requieren esta configuración. Sin ella, la API devuelve un error 400 que te indica que la establezcas.

Los siguientes ejemplos usan web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)

Cómo usar la búsqueda web

Para saber cómo se aplica la configuración de búsqueda web de tu organización en las sesiones de Claude Managed Agents, consulta Restringir los dominios de búsqueda web y obtención web.

Proporciona la herramienta de búsqueda 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": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

Definición de la herramienta

La herramienta de búsqueda web admite los siguientes parámetros:

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Todas las versiones de la herramienta de búsqueda web aceptan allowed_callers, que controla si Claude llama a la búsqueda web directamente o desde la ejecución de código mediante el filtrado dinámico. En web_search_20260209 y posteriores, su valor predeterminado es ["code_execution_20260120"] en lugar de ["direct"]. Consulta ZDR y allowed_callers para saber cómo configurarlo. web_search_20260318 y posteriores también aceptan response_inclusion.

Usos máximos

El parámetro max_uses limita el número de búsquedas en un solo turno. Las consultas sobre un solo hecho suelen usar de 1 a 3 búsquedas; la investigación comparativa o sobre varias entidades puede usar 10 o más.

Las búsquedas fallidas cuentan para el límite. Si Claude llama a la búsqueda web directamente más veces de las permitidas, el web_search_tool_result es un error con el código de error max_uses_exceeded. Si Claude llama a la búsqueda web desde la ejecución de código más veces de las permitidas, la ejecución de código termina con un error.

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 búsquedas 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 el filtrado dinámico.

Filtrado de dominios

Proporciona allowed_domains o blocked_domains, no ambos. Si una solicitud incluye ambos, la API devuelve un error 400. Las entradas son dominios simples con una ruta opcional, por ejemplo example.com o example.com/blog, sin esquema.

Para conocer todas las reglas de filtrado de dominios, consulta Filtrado de dominios en la guía de Herramientas de servidor.

En Claude Managed Agents, establece estos campos en la entrada web_search del conjunto de herramientas del agente; consulta Restringir los dominios de búsqueda web y obtención web.

Localización

El parámetro user_location te permite localizar los resultados de búsqueda según la ubicación de un usuario. Proporciona al menos uno de city, region, country o timezone.

• type: El tipo de ubicación (debe ser approximate)
• city: El nombre de la ciudad
• region: La región o estado
• country: El código de país de dos letras ISO 3166-1 alpha-2 (la API rechaza un código no admitido con un error 400)
• timezone: El ID de zona horaria de IANA

En Claude Managed Agents, la entrada web_search del conjunto de herramientas del agente también acepta user_location; consulta la configuración de las herramientas web.

Inclusión en la respuesta

El parámetro response_inclusion controla cómo aparecen los bloques de resultados de búsqueda 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, para los flujos de trabajo agénticos que no necesitan el contenido de búsqueda sin procesar. 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_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

Respuesta

Este es un ejemplo de la estructura de respuesta:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Este ejemplo muestra una búsqueda directa. Cuando una búsqueda se ejecuta mediante el filtrado dinámico, la respuesta también contiene los bloques de resultados de la herramienta de ejecución de código, y cada par anidado de server_tool_use y web_search_tool_result lleva un campo caller que identifica la llamada de ejecución de código que lo realizó.

Resultados de búsqueda

Los resultados de búsqueda incluyen:

• url: La URL de la página de origen
• title: El título de la página de origen
• page_age: Cuándo se actualizó el sitio por última vez
• encrypted_content: Contenido cifrado que debes devolver en conversaciones de varios turnos

Para continuar una conversación que contiene resultados de búsqueda, envía de vuelta los bloques de contenido del asistente exactamente como los recibiste, incluido el encrypted_content de cada resultado. La API descifra ese contenido en solicitudes posteriores para restaurar los resultados de búsqueda en el contexto de Claude. Si encrypted_content falta o se modifica, la solicitud falla con un error de validación 400.

Citas

Las citas siempre están habilitadas para la búsqueda web, y cada web_search_result_location incluye:

• url: La URL de la fuente citada
• title: El título de la fuente citada
• encrypted_index: Una referencia que debe devolverse en conversaciones de varios turnos
• cited_text: Hasta 150 caracteres del contenido citado

Los campos de citas de búsqueda web cited_text, title y url no cuentan para el uso de tokens de entrada ni de salida.

Errores

Cuando la herramienta de búsqueda web encuentra un error (como alcanzar los límites de velocidad), la Claude API aun así devuelve una respuesta 200 (éxito). El error se representa dentro del cuerpo de la respuesta con la siguiente estructura:

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

En caso de error, content es un único objeto de error en lugar de una lista de bloques de resultados. Una búsqueda que se realiza correctamente pero no obtiene resultados devuelve una lista content vacía, no un error.

Estos son los posibles códigos de error:

• too_many_requests: Se superó el límite de velocidad
• invalid_tool_input: Parámetro de consulta de búsqueda no válido
• max_uses_exceeded: Se superó el número máximo de usos de la herramienta de búsqueda web
• query_too_long: La consulta supera la longitud máxima
• request_too_large: La solicitud de búsqueda es demasiado grande, normalmente debido a una lista larga de filtros de dominio
• unavailable: Ocurrió un error interno

Motivo de detención pause_turn

La API puede pausar un turno de búsqueda de larga duración y devolver stop_reason: "pause_turn". Para continuar, envía de vuelta el mensaje pausado del asistente sin cambios en una nueva solicitud.

Si Claude llama a la búsqueda web y a una de tus herramientas de cliente en el mismo grupo de llamadas paralelas a herramientas, la API devuelve stop_reason: "tool_use" en su lugar y aún no ejecuta la búsqueda. Para continuar, devuelve los resultados de las herramientas de cliente, y la API ejecuta la búsqueda en la siguiente solicitud. Consulta Combinar herramientas de servidor y herramientas de cliente en un turno.

Para el bucle del lado del servidor y el manejo de pause_turn, consulta El bucle del lado del servidor y pause_turn en la guía de Herramientas de servidor.

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, recibes eventos de búsqueda como parte del stream. Hay una pausa mientras se ejecuta la búsqueda:

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 search

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search runs

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)

Solicitudes por lotes

Puedes incluir la herramienta de búsqueda web en la Message Batches API. Las llamadas a la herramienta de búsqueda web a través de la Message Batches API tienen el mismo precio que las de las solicitudes normales a la Messages API.

Para proteger la capacidad compartida, la Batches API limita las solicitudes de búsqueda web de cada organización, por lo que los lotes grandes con muchas búsquedas pueden tardar más en completarse. Puedes ver el límite de velocidad de búsqueda web de tu organización en la página Límites de frecuencia de la Claude Console. Para solicitar un límite más alto, contacta al equipo de ventas desde esa página.

Uso y precios

El uso de la búsqueda web se cobra además del uso de tokens:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

La búsqueda web está disponible en la API de Claude por $10 USD por cada 1,000 búsquedas, más los costos estándar de tokens por el contenido generado por la búsqueda. Los resultados de búsqueda web obtenidos a lo largo de una conversación se cuentan como tokens de entrada, tanto en las iteraciones de búsqueda ejecutadas durante un solo turno como en los turnos posteriores de la conversación.

Cada búsqueda web cuenta como un uso, independientemente del número de resultados devueltos. Una búsqueda web que falla con un error no se factura.

Próximos pasos