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

Por favor, contáctanos a través de nuestro formulario de comentarios para compartir tu experiencia con la herramienta de búsqueda web.

​
Modelos compatibles

La búsqueda web está disponible en:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (nuevo) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (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 basándose en el prompt.
  2. La API ejecuta las búsquedas y proporciona a Claude los resultados. Este proceso puede repetirse varias veces durante una sola solicitud.
  3. Al final de su turno, Claude proporciona una respuesta final con las fuentes citadas.

​
Cómo usar la búsqueda web

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

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-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "How do I update a web app to TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Definición de la 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 incluir resultados de estos dominios
  "allowed_domains": ["example.com", "trusteddomain.org"],

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

  // Opcional: Localizar resultados de búsqueda
  "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 realizar 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

Al usar 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)
  • Se admiten las subrutas (example.com/blog)
  • Puedes usar allowed_domains o blocked_domains, pero no ambos en la misma solicitud.

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

​
Respuesta

Aquí tienes un ejemplo de estructura de respuesta:

{
  "role": "assistant",
  "content": [
    // 1. La 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 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 varios turnos para citas

​
Citas

Las citas están siempre 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 varios turnos.
  • cited_text: Hasta 150 caracteres del contenido citado

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

Al mostrar resultados web o información contenida en resultados web a los usuarios finales, las citas en línea deben ser claramente visibles y se debe poder hacer clic en ellas en tu interfaz de usuario.

​
Errores

Si ocurre un error durante la búsqueda web, recibirás una respuesta que tiene la siguiente forma:

{
  "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 tasa excedido
  • invalid_input: Parámetro de consulta de búsqueda no válido
  • max_uses_exceeded: Usos máximos de la herramienta de búsqueda web excedidos
  • query_too_long: La consulta excede la longitud máxima
  • unavailable: Ocurrió un error interno

​
Motivo de parada pause_turn

La respuesta puede incluir un motivo de parada pause_turn, que indica que la API pausó un turno de larga duración. Puedes proporcionar la respuesta tal cual 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 prompts

La búsqueda web funciona con almacenamiento en caché de prompts. Para habilitar el almacenamiento en caché de prompts, agrega 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 varios 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 el almacenamiento en caché de prompts con búsqueda web para una conversación de varios 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-20250514",
    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ñadir 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"}  # Almacenar en caché hasta este punto
})

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

​
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": ""}}

// 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 a la herramienta de búsqueda web a través de la API de Lotes de Mensajes tienen el mismo precio que las de las solicitudes regulares de la API de Mensajes.

​
Uso y precios

El uso de 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 Anthropic por $10 por cada 1,000 búsquedas, más los costos estándar de tokens para el contenido generado por la búsqueda. Los resultados de búsqueda web recuperados 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 de conversación posteriores.

Cada búsqueda web cuenta como un uso, independientemente del número de resultados devueltos. Si ocurre un error durante la búsqueda web, la búsqueda web no se facturará.