Herramienta de búsqueda web

La herramienta de búsqueda web proporciona a Claude acceso directo a contenido web en tiempo real, permitiéndole 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.

La última versión de la herramienta de búsqueda web (web_search_20260209) admite filtrado dinámico con 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 los resultados de búsqueda antes de que lleguen a la ventana de contexto, manteniendo solo la información relevante y descartando el resto. Esto conduce a respuestas más precisas mientras se reduce el consumo de tokens. La versión anterior de la herramienta (web_search_20250305) sigue disponible sin filtrado dinámico.

Para Claude Mythos Preview, la búsqueda web es compatible con la API de Claude, Microsoft Foundry y Google Vertex AI. La búsqueda web no está disponible para Mythos Preview en Amazon Bedrock.

Para la elegibilidad de Retención Cero de Datos y la solución alternativa allowed_callers, consulta Herramientas de servidor.

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

Cómo funciona la búsqueda web

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

Claude decide cuándo buscar basándose en el mensaje.
La API ejecuta las búsquedas y proporciona a Claude los resultados. Este proceso puede repetirse varias veces durante una única solicitud.
Al final de su turno, Claude proporciona una respuesta final con fuentes citadas.

Filtrado dinámico

La búsqueda web es una tarea que consume muchos tokens. Con la búsqueda web básica, Claude necesita extraer los resultados de búsqueda al contexto, obtener HTML completo de múltiples sitios web y razonar sobre todo 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 la versión de herramienta web_search_20260209, Claude puede escribir y ejecutar código para post-procesar los resultados de consultas. En lugar de razonar sobre archivos HTML completos, Claude filtra dinámicamente los resultados de búsqueda antes de cargarlos en el contexto, manteniendo solo lo relevante y descartando el resto.

El filtrado dinámico es particularmente efectivo 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

El filtrado dinámico requiere que la herramienta de ejecución de código esté habilitada. La herramienta de búsqueda web mejorada está disponible en la API de Claude y Microsoft Azure. En Google Vertex AI, la herramienta de búsqueda web básica (sin filtrado dinámico) está disponible.

Para habilitar el filtrado dinámico, utiliza la versión de herramienta web_search_20260209:

Cómo usar la búsqueda web

El administrador de tu organización debe habilitar la búsqueda web en la Claude Console.

Proporciona la herramienta de búsqueda web en tu solicitud de API:

Definición de herramienta

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

JSON

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

  // Opcional: Limita el número de búsquedas por solicitud
  "max_uses": 5,

  // Opcional: Solo incluye resultados de estos dominios
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Opcional: Nunca incluyas resultados de estos dominios
  "blocked_domains": ["untrustedsource.com"],

  // Opcional: Localiza los resultados de búsqueda
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Máximo de usos

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.

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 basándose en la ubicación del 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.

Respuesta

Aquí hay una estructura de respuesta de ejemplo:

Output

{
  "role": "assistant",
  "content": [
    // 1. Decisión de Claude de buscar
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. La consulta de búsqueda utilizada
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Resultados de búsqueda
    {
      "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. Respuesta de Claude con citas
    {
      "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 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 debe pasarse en conversaciones de múltiples turnos para 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 pasarse para conversaciones de múltiples turnos.
cited_text: Hasta 150 caracteres del contenido citado

Los campos de cita de búsqueda web cited_text, title y url no cuentan hacia el uso de tokens de entrada o salida.

Al mostrar las salidas de la API directamente a los usuarios finales, las citas deben incluirse a la fuente original. Si realizas modificaciones en las salidas de la API, incluyendo reprocesamiento y/o combinación con tu propio material antes de mostrarlas a los usuarios finales, muestra las citas según corresponda basándote en consulta con tu equipo legal.

Errores

Cuando la herramienta de búsqueda web encuentra un error (como alcanzar 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:

Output

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

Estos son los posibles códigos de error:

too_many_requests: Límite de velocidad excedido
invalid_input: Parámetro de consulta de búsqueda inválido
max_uses_exceeded: Máximo de usos de herramienta de búsqueda web excedido
query_too_long: La consulta excede la longitud máxima
unavailable: Ocurrió un error interno

Razón de parada `pause_turn`

Para continuar después de una razón de parada pause_turn, consulta Herramientas de servidor.

Almacenamiento en caché de mensajes

Para almacenar en caché definiciones de herramientas entre turnos, consulta Uso de herramientas con almacenamiento en caché de mensajes.

Transmisión

Con la transmisión habilitada, recibirás eventos de búsqueda como parte de la transmisión. Habrá una pausa mientras se ejecuta la búsqueda:

Output

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 API de Lotes de Mensajes. Las llamadas de herramienta de búsqueda web a través de la API de Lotes de Mensajes se cotizan igual que las solicitudes de la API de Mensajes regular.

Uso y precios

Web search usage is charged in addition to token usage:

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

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Próximos pasos

Herramientas de servidor

Mecánicas compartidas para herramientas ejecutadas por Anthropic.

Referencia de herramientas

Directorio de todas las herramientas proporcionadas por Anthropic.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

Cómo funciona la búsqueda web

Filtrado dinámico

Cómo usar la búsqueda web

Definición de herramienta

Máximo de usos

Filtrado de dominios

Localización

Respuesta

Resultados de búsqueda

Citas

Errores

Razón de parada pause_turn

Almacenamiento en caché de mensajes

Transmisión

Solicitudes por lotes

Uso y precios

Próximos pasos

Razón de parada `pause_turn`