Herramienta de búsqueda web

La herramienta de búsqueda web le da 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.

La herramienta de búsqueda web le da 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, comunícate 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.1 (claude-opus-4-1-20250805)
• 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 agregas 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 múltiples veces durante una sola solicitud.
3. Al final de su turno, Claude proporciona una respuesta final con 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:

Shell

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-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "¿Cómo actualizo una aplicación web a TypeScript 5.5?"
            }
        ],
        "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:

JSON

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

  // Opcional: Limitar 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 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 subpaths (example.com/blog)
• Puedes usar allowed_domains o blocked_domains, pero no ambos en la misma solicitud.

Las restricciones de dominio a nivel de solicitud deben ser compatibles con las restricciones de dominio a nivel de organización configuradas en la Consola. Los dominios a nivel de solicitud solo pueden restringir más los dominios, no anular o expandir más allá de la lista a nivel de organización. Si tu solicitud incluye dominios que entran en conflicto con la configuración de la organización, la API devolverá un error de validación.

Localización

El parámetro user_location te permite localizar los resultados de búsqueda basándose en 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í hay un ejemplo de estructura de respuesta:

{
  "role": "assistant",
  "content": [
    // 1. Decisión de Claude de buscar
    {
      "type": "text",
      "text": "Buscaré cuándo nació Claude Shannon."
    },
    // 2. La consulta de búsqueda utilizada
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon fecha de nacimiento"
      }
    },
    // 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": "30 de abril de 2025"
        }
      ]
    },
    {
      "text": "Basándome en los resultados de búsqueda, ",
      "type": "text"
    },
    // 4. Respuesta de Claude con citas
    {
      "text": "Claude Shannon nació el 30 de abril de 1916, en 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 (30 de abril de 1916 – 24 de febrero de 2001) fue un matemático estadounidense, ingeniero eléctrico, científico de la computación, criptógrafo e 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 encriptado que debe pasarse de vuelta 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 pasarse de vuelta 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 resultados web o información contenida en resultados web a los usuarios finales, las citas en línea deben hacerse claramente visibles y clicables en tu interfaz de usuario.

Errores

Cuando la herramienta de búsqueda web encuentra un error (como alcanzar límites de velocidad), la API de Anthropic aún devuelve una respuesta 200 (éxito). El error se representa dentro del cuerpo de 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: Usos máximos de herramienta de búsqueda web excedidos
• 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.

Caché de prompts

La búsqueda web funciona con caché de prompts. Para habilitar el caché de prompts, agrega al menos un punto de interrupción cache_control en tu solicitud. El sistema automáticamente almacenará 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 contenido en caché.

Por ejemplo, para usar caché de prompts 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": "¿Cuál es el clima actual en San Francisco hoy?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    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"
        }
    }]
)

# Agregar 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": "¿Debería esperar lluvia más tarde esta semana?",
    "cache_control": {"type": "ephemeral"}  # Caché hasta este punto
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    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 en caché
# mientras aún puede realizar nuevas búsquedas si es necesario
print(f"Tokens de lectura de caché: {response2.usage.get('cache_read_input_tokens', 0)}")

Streaming

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

// 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\":\"últimos avances en computación cuántica 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": "Avances en Computación Cuántica en 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 tienen el mismo precio 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 Anthropic 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.