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. Claude cita automáticamente las fuentes de los resultados de búsqueda como parte de su respuesta.

La última versión de la herramienta de búsqueda web (web_search_20260209) admite filtrado dinámico con Claude Opus 4.6 y 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.

Modelos compatibles

La búsqueda web está disponible en:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (deprecado) (claude-3-7-sonnet-20250219)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (deprecado) (claude-3-5-haiku-latest)

Cómo funciona la búsqueda web

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

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

Filtrado dinámico con Opus 4.6 y Sonnet 4.6

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 consulta. 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

Para habilitar el filtrado dinámico, usa la versión de herramienta web_search_20260209 con el encabezado beta code-execution-web-tools-2026-02-09:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-web-tools-2026-02-09" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

Cómo usar la búsqueda web

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What is the weather in NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

Definición de herramienta

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

{
  "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"
  }
}

Max uses

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 será un error con el código de error max_uses_exceeded.

Filtrado de dominios

Cuando uses filtros de dominio:

• Los dominios no deben incluir el esquema HTTP/HTTPS (usa example.com en lugar de https://example.com)
• Los subdominios se incluyen automáticamente (example.com cubre docs.example.com)
• Los subdominios específicos restringen los resultados solo a ese subdominio (docs.example.com devuelve solo resultados de ese subdominio, no de example.com o api.example.com)
• Se admiten subrutas y coinciden con cualquier cosa después de la ruta (example.com/blog coincide con example.com/blog/post-1)
• Puedes usar allowed_domains o blocked_domains, pero no ambos en la misma solicitud.

Soporte de comodín:

• Solo se permite un comodín (*) por entrada de dominio, y debe aparecer después de la parte del dominio (en la ruta)
• Válido: example.com/*, example.com/*/articles
• Inválido: *.example.com, ex*.com, example.com/*/news/*

Los formatos de dominio inválidos devolverán un error de herramienta invalid_tool_input.

Localización

El parámetro user_location te permite localizar los resultados de búsqueda según 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:

{
  "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 nuevamente 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 nuevamente 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.

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:

{
  "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

La respuesta puede incluir una razón de parada pause_turn, que indica que la API pausó un turno de larga duración. Puedes proporcionar la respuesta tal como está en una solicitud posterior para permitir que Claude continúe su turno, o modificar el contenido si deseas interrumpir la conversación.

Almacenamiento en caché de mensajes

La búsqueda web funciona con almacenamiento en caché de mensajes. Para habilitar el almacenamiento en caché de mensajes, añade al menos un punto de interrupción cache_control en tu solicitud. El sistema almacenará automáticamente en caché hasta el último bloque web_search_tool_result al ejecutar la herramienta.

Para conversaciones de múltiples turnos, establece un punto de interrupción cache_control en o después del último bloque web_search_tool_result para reutilizar el contenido almacenado en caché.

Por ejemplo, para usar almacenamiento en caché de mensajes con búsqueda web para una conversación de múltiples turnos:

import anthropic

client = anthropic.Anthropic()

# Primera solicitud con búsqueda web y punto de interrupción de caché
messages = [
    {"role": "user", "content": "What's the current weather in San Francisco today?"}
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles",
            },
        }
    ],
)

# Añade la respuesta de Claude a la conversación
messages.append({"role": "assistant", "content": response1.content})

# Segunda solicitud con punto de interrupción de caché después de los resultados de búsqueda
messages.append(
    {
        "role": "user",
        "content": "Should I expect rain later this week?",
        "cache_control": {"type": "ephemeral"},  # Cache up to this point
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "user_location": {
                "type": "approximate",
                "city": "San Francisco",
                "region": "California",
                "country": "US",
                "timezone": "America/Los_Angeles",
            },
        }
    ],
)
# La segunda respuesta se beneficiará de los resultados de búsqueda almacenados en caché
# mientras aún puede realizar nuevas búsquedas si es necesario
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Transmisión en directo

Con la transmisión en directo habilitada, recibirás eventos de búsqueda como parte de la transmisión. 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": ""}}

// Decisión de Claude de buscar

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

// Consulta de búsqueda transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pausa mientras se ejecuta la búsqueda

// Resultados de búsqueda transmitidos
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"}]}}

// Respuesta de Claude con citas (omitida en este ejemplo)

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 de las solicitudes regulares de la API de Mensajes.

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.