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 extraídas de los resultados de búsqueda.

La versión más reciente de la herramienta de búsqueda web (web_search_20260318) admite filtrado dinámico con Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 y Claude Sonnet 4.6. Claude puede escribir y ejecutar código para filtrar los resultados de búsqueda antes de que lleguen a la ventana de contexto, conservando solo la información relevante y descartando el resto. Esto produce respuestas más precisas a la vez que reduce el consumo de tokens. web_search_20260318 también agrega control de inclusión de respuesta para flujos de trabajo agénticos. Las versiones anteriores (web_search_20260209 solo para filtrado dinámico, web_search_20250305 para búsqueda básica) siguen disponibles.

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 búsqueda web

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

1. Claude decide cuándo buscar según el prompt.
2. La API ejecuta las búsquedas y 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 las fuentes citadas.



Cuándo busca Claude

Claude busca cuando la solicitud depende de información que es actual, cambiante o 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 dirigir 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 por cada solicitud.



Filtrado dinámico

La búsqueda web es una tarea que consume muchos tokens. Con la búsqueda web básica, Claude necesita incorporar los resultados de búsqueda al contexto, obtener el HTML completo de varios sitios web y razonar sobre todo ello antes de llegar a una respuesta. A menudo, gran parte de este contenido es irrelevante, lo que puede degradar la calidad de la respuesta.

Con web_search_20260209 o posterior, Claude puede escribir y ejecutar código para posprocesar los resultados de la consulta. En lugar de razonar sobre archivos HTML completos, Claude filtra dinámicamente los resultados de búsqueda antes de cargarlos en el contexto, conservando solo lo relevante y descartando el resto.

El filtrado dinámico es particularmente eficaz para:

• Buscar en documentación técnica
• Revisión de literatura y verificación de citas
• Investigación técnica
• Fundamentación y verificación de respuestas

Para habilitar el filtrado dinámico, usa web_search_20260209 o cualquier versión posterior. Los siguientes ejemplos usan web_search_20260209:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20260209", "name": "web_search"}],
)
print(response)



Cómo usar la búsqueda web

Proporciona la herramienta de búsqueda 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": "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
  "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"
  }
}



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 consultas sensibles a la latencia, max_uses: 3 limita el costo y rara vez trunca. Para agentes de investigación, establece max_uses entre 15 y 20 u omítelo por completo.



Filtrado de dominios

Para el filtrado de dominios con allowed_domains y blocked_domains, consulta Herramientas de servidor.



Localización

El parámetro user_location te permite localizar los resultados de búsqueda según la ubicación de un usuario.

• type: El tipo de ubicación (debe ser approximate)
• city: El nombre de la ciudad
• region: La región o estado
• country: El país
• timezone: El ID de zona horaria IANA.



Inclusión de 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 resultados, reduciendo 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

Aquí tienes 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"
}



Resultados de búsqueda

Los resultados de búsqueda incluyen:

• url: La URL de la página fuente
• title: El título de la página fuente
• page_age: Cuándo se actualizó el sitio por última vez
• encrypted_content: Contenido cifrado que debe devolverse en conversaciones de múltiples turnos para las citas



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 para conversaciones de múltiples 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 API de Claude aún devuelve una respuesta 200 (éxito). El error se representa dentro del cuerpo de la respuesta usando 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"
  }
}

Estos son los posibles códigos de error:

• too_many_requests: Se excedió el límite de velocidad
• invalid_input: Parámetro de consulta de búsqueda no válido
• max_uses_exceeded: Se excedió el número máximo de usos de la herramienta de búsqueda web
• query_too_long: La consulta excede la longitud máxima
• unavailable: Ocurrió un error interno



Motivo de detención pause_turn

Para continuar después de un motivo de detención pause_turn, consulta 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 flujo. 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 regulares de la Messages API.

Para proteger la capacidad compartida, la Batches API limita 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 Limits de la Claude Console; contacta a ventas desde esa página para solicitar un límite más alto. Las cargas de trabajo típicas de búsqueda web por lotes incluyen enriquecer registros con datos web actuales, investigar una lista grande de entidades y fundamentar o verificar un corpus de contenido contra fuentes en vivo.



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