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 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 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 (
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:
- Claude decide cuándo buscar basándose en el prompt.
- La API ejecuta las búsquedas y proporciona a Claude los resultados. Este proceso puede repetirse múltiples veces durante una sola solicitud.
- 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 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:
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 dehttps://example.com
) - Los subdominios se incluyen automáticamente (
example.com
cubredocs.example.com
) - Se admiten subpaths (
example.com/blog
) - Puedes usar
allowed_domains
oblocked_domains
, pero no ambos en la misma solicitud.
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 serapproximate
)city
: El nombre de la ciudadregion
: La región o estadocountry
: El paístimezone
: El ID de zona horaria IANA.
Respuesta
Aquí hay un ejemplo de estructura de respuesta:
Resultados de búsqueda
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 encriptado que debe pasarse de vuelta 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 citadatitle
: El título de la fuente citadaencrypted_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 usuarios finales, las citas en línea deben hacerse claramente visibles y clicables en tu interfaz de usuario.
Errores
Si ocurre un error durante la búsqueda web, recibirás una respuesta que toma la siguiente forma:
Estos son los posibles códigos de error:
too_many_requests
: Límite de velocidad excedidoinvalid_input
: Parámetro de consulta de búsqueda inválidomax_uses_exceeded
: Usos máximos de herramienta de búsqueda web excedidosquery_too_long
: La consulta excede la longitud máximaunavailable
: 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:
Streaming
Con streaming habilitado, recibirás eventos de búsqueda como parte del stream. Habrá una pausa mientras se ejecuta la búsqueda:
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 aquellas en solicitudes regulares de la API de Mensajes.
Uso y precios
Web search usage is charged in addition to token usage:
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.