Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 de corte de conocimiento. La respuesta incluye citas de las fuentes extraídas de los resultados de búsqueda.
Con web_search_20260209 y versiones posteriores, Claude puede escribir y ejecutar código que filtra los resultados de búsqueda antes de que lleguen a la ventana de contexto (filtrado dinámico), conservando solo la información relevante. El filtrado dinámico está disponible con Claude 4.6 y modelos posteriores, y con Claude Mythos Preview.
Hay tres versiones de la herramienta de búsqueda web disponibles:
web_search_20250305: búsqueda web básicaweb_search_20260209: agrega filtrado dinámicoweb_search_20260318: agrega control de inclusión de respuesta para flujos de trabajo agénticosLos ejemplos de esta página usan web_search_20250305 para la búsqueda básica y web_search_20260318 para el filtrado dinámico.
Para conocer la elegibilidad de la búsqueda web para Zero Data Retention y la configuración relacionada de allowed_callers, consulta Herramientas de servidor.
Para conocer la compatibilidad de modelos, consulta la Referencia de herramientas.
Cuando agregas la herramienta de búsqueda web a tu solicitud de API:
Claude busca cuando la solicitud depende de información que es actual, cambiante o está fuera de sus datos de entrenamiento:
Claude responde directamente sin buscar cuando la solicitud se basa en conocimiento estable:
La activación se puede orientar a través de 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.
Con la búsqueda web básica, cada resultado de búsqueda se carga en la ventana de contexto de Claude, y gran parte de ese contenido puede ser irrelevante para la solicitud. Con web_search_20260209 o posterior, Claude en su lugar escribe y ejecuta código que filtra primero los resultados, de modo que solo el contenido relevante llega a la ventana de contexto. Esto reduce el uso de tokens en solicitudes con muchas búsquedas.
El filtrado dinámico ejecuta la búsqueda web desde dentro de la ejecución de código: en web_search_20260209 y versiones posteriores, el campo allowed_callers de la herramienta tiene como valor predeterminado ["code_execution_20260120"], y cuando se ejecuta el filtrado dinámico, la API aprovisiona automáticamente la ejecución de código que necesita para la solicitud. No necesitas agregar tú mismo la herramienta de ejecución de código a tools. No hay cargos adicionales por las llamadas de ejecución de código realizadas de esta manera más allá de los costos estándar de tokens.
Para llamar a la búsqueda web directamente, sin filtrado dinámico, establece allowed_callers: ["direct"]. Los modelos que no admiten llamadas programáticas a herramientas requieren esta configuración. Sin ella, la API devuelve un error 400 que te indica que la establezcas.
Los siguientes ejemplos usan web_search_20260318:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
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_20260318", "name": "web_search"}],
)
print(response)Proporciona la herramienta de búsqueda web en tu solicitud de API:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
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)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.
// Use allowed_domains or blocked_domains, not both.
"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"
}
}Todas las versiones de la herramienta de búsqueda web aceptan allowed_callers, que controla si Claude llama a la búsqueda web directamente o desde la ejecución de código a través del filtrado dinámico. En web_search_20260209 y versiones posteriores, el valor predeterminado es ["code_execution_20260120"] en lugar de ["direct"]. Consulta Herramientas de servidor para saber cómo configurarlo. web_search_20260318 y versiones posteriores también aceptan response_inclusion.
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 obtener orientación sobre cómo elegir un valor, consulta Herramientas de servidor.
Proporciona allowed_domains o blocked_domains, no ambos. Si una solicitud incluye ambos, la API devuelve un error 400. Las entradas son dominios simples con una ruta opcional, por ejemplo example.com o example.com/blog, sin esquema.
Para conocer las reglas completas de filtrado de dominios, consulta Filtrado de dominios en la guía de Herramientas de servidor.
El parámetro user_location te permite localizar los resultados de búsqueda según la ubicación de un usuario. Proporciona al menos uno de city, region, country o timezone.
type: El tipo de ubicación (debe ser approximate)city: El nombre de la ciudadregion: La región o estadocountry: El código de país de dos letras ISO 3166-1 alpha-2. La API rechaza los códigos de país no admitidos con un error 400.timezone: El ID de zona horaria de IANA.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, lo que reduce 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"
}
]
}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"
}Este ejemplo muestra una búsqueda directa. Cuando una búsqueda se ejecuta a través del filtrado dinámico, la respuesta también contiene los bloques de resultados de la herramienta de ejecución de código, y cada par anidado de server_tool_use y web_search_tool_result lleva un campo caller que identifica la llamada de ejecución de código que lo realizó.
Los resultados de búsqueda incluyen:
url: La URL de la página fuentetitle: El título de la página fuentepage_age: Cuándo se actualizó el sitio por última vezencrypted_content: Contenido cifrado que debes devolver en conversaciones de múltiples turnosPara continuar una conversación que contiene resultados de búsqueda, envía los bloques de contenido del asistente exactamente como los recibiste, incluido el encrypted_content de cada resultado. La API descifra ese contenido en turnos posteriores para restaurar los resultados de búsqueda en el contexto de Claude. Si encrypted_content falta o está modificado, la solicitud falla con un error de validación 400.
Las citas siempre están habilitadas para la búsqueda web, y cada web_search_result_location incluye:
url: La URL de la fuente citadatitle: El título de la fuente citadaencrypted_index: Una referencia que debe devolverse para conversaciones de múltiples turnoscited_text: Hasta 150 caracteres del contenido citadoLos campos de cita de búsqueda web cited_text, title y url no cuentan para el uso de tokens de entrada ni de salida.
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"
}
}En caso de error, content es un único objeto de error en lugar de una lista de bloques de resultados. Una búsqueda que tiene éxito pero no coincide con ningún resultado devuelve una lista content vacía, no un error.
Estos son los posibles códigos de error:
too_many_requests: Se excedió el límite de velocidadinvalid_tool_input: Parámetro de consulta de búsqueda no válidomax_uses_exceeded: Se excedió el número máximo de usos de la herramienta de búsqueda webquery_too_long: La consulta excede la longitud máximarequest_too_large: La solicitud de búsqueda es demasiado grande, normalmente debido a una lista larga de filtros de dominiounavailable: Ocurrió un error internopause_turnLa API puede pausar un turno de búsqueda de larga duración y devolver stop_reason: "pause_turn". Para continuar, envía el mensaje del asistente pausado sin cambios en una nueva solicitud.
Si Claude llama a la búsqueda web y a una de tus herramientas de cliente en el mismo grupo de llamadas paralelas a herramientas, la API devuelve stop_reason: "tool_use" en su lugar y aún no ejecuta la búsqueda. Para continuar, devuelve los resultados de la herramienta de cliente, y la API ejecuta la búsqueda en la siguiente solicitud. Consulta Combinar herramientas de servidor y herramientas de cliente en un turno.
Para el bucle del lado del servidor y el manejo de pause_turn, consulta El bucle del lado del servidor y pause_turn en la guía de Herramientas de servidor.
Para almacenar en caché las definiciones de herramientas entre turnos, consulta Uso de herramientas con almacenamiento en caché de prompts.
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)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.
Para proteger la capacidad compartida, la API de lotes 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 Límites de velocidad de la Claude Console. Para solicitar un límite más alto, contacta con ventas desde esa página.
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á.
Obtén y lee contenido de URLs específicas para aumentar el contexto de Claude con contenido web en vivo.
Trabaja con herramientas ejecutadas por Anthropic: bloques server_tool_use, continuación de pause_turn y filtrado de dominios.
Directorio de herramientas proporcionadas por Anthropic y referencia de propiedades opcionales de definición de herramientas.
Was this page helpful?