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 de corte de conocimiento. La respuesta incluye citas de las fuentes extraídas 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 los modelos Claude 4.6 y 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 Zero Data Retention y la configuración relacionada de allowed_callers, consulta Herramientas de servidor.

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



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 a Claude los resultados. 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 que es actual, cambiante o que está 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 científicos 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

La activación se puede orientar mediante tu indicación del sistema: puedes animar a Claude a buscar con más facilidad o a preferir responder directamente. Para una restricción estricta, usa max_uses para limitar el número de búsquedas en cada solicitud.



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 filtra primero 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",
    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

Estas configuraciones a nivel de organización en la Claude Console se aplican solo a las solicitudes de la Messages API. Las sesiones de Claude Managed Agents usan únicamente las listas allowed_domains y blocked_domains por herramienta en el conjunto de herramientas del agente; 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",
    max_tokens=1024,
    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 per request
  "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 Herramientas de servidor 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 realizadas. Si Claude intenta más búsquedas de las permitidas, el web_search_tool_result es un error con el código de error max_uses_exceeded.

Las consultas factuales simples suelen usar de 1 a 3 búsquedas; la investigación comparativa o de múltiples entidades puede usar 10 o más. Para obtener orientación sobre cómo elegir un valor, consulta Herramientas de servidor.



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 las reglas completas 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 el estado
• country: El código de país de dos letras ISO 3166-1 alpha-2. La API rechaza los códigos de país no admitidos 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 acepta un objeto user_location con los mismos campos. La API rechaza un código country no admitido con un error 400 cuando creas o actualizas el agente, o cuando creas o actualizas una sesión que proporciona la configuración. Consulta Restringir los dominios de búsqueda web y obtención 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 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 server_tool_use y bloques de resultado, lo que reduce los costos de tokens de salida para flujos de trabajo agénticos que no necesitan devolver el contenido de búsqueda sin procesar 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_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}



Respuesta

Este es un ejemplo de 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 resultado 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 enviar de vuelta 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 turnos posteriores para restaurar los resultados de búsqueda en el contexto de Claude. Si encrypted_content falta o se modificó, 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 enviarse de vuelta en conversaciones de varios turnos
• cited_text: Hasta 150 caracteres del contenido citado

Los campos de cita de la 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 aún 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 resultado. Una búsqueda que tiene éxito pero no coincide con ningún resultado devuelve una lista content vacía, no un error.

Estos son los posibles códigos de error:

• too_many_requests: Se excedió el "rate limit" (límite de velocidad)
• invalid_tool_input: Parámetro de consulta de búsqueda no válido
• max_uses_exceeded: Se excedió el máximo de usos de la herramienta de búsqueda web
• query_too_long: La consulta excede 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 del asistente pausado 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 de herramientas paralelas, la API devuelve en su lugar stop_reason: "tool_use" y aún no ejecuta la búsqueda. Para continuar, devuelve los resultados de la herramienta 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 conocer 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, recibirás eventos de búsqueda como parte del stream. Habrá 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 executes

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

Para proteger la capacidad compartida, la Batches API regula las solicitudes de búsqueda web por organización, por lo que los lotes grandes con muchas búsquedas podrían 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 velocidad de la Claude Console. Para solicitar un límite más alto, contacta a 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 por cada 1,000 búsquedas, más los costos estándar de tokens por el contenido generado a partir de las búsquedas. 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. Si ocurre un error durante la búsqueda web, esta no se facturará.



Próximos pasos