Herramientas del servidor

Esta página cubre la mecánica compartida de las herramientas ejecutadas por el servidor: el bloque server_tool_use, la continuación pause_turn, consideraciones de ZDR y filtrado de dominios. Para herramientas individuales, consulta la referencia de herramientas.

El bloque server_tool_use

El bloque server_tool_use aparece en la respuesta de Claude cuando se ejecuta una herramienta ejecutada por el servidor. Su campo id utiliza el prefijo srvtoolu_ para distinguirlo de las llamadas de herramientas del cliente:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

La API ejecuta la herramienta internamente. Ves la llamada y su resultado en la respuesta, pero no manejas la ejecución. A diferencia de los bloques tool_use del cliente, no necesitas responder con un tool_result. El bloque de resultado aparece inmediatamente después del bloque server_tool_use en el mismo turno del asistente.

El bucle del lado del servidor y pause_turn

Cuando se utilizan herramientas del servidor como búsqueda web, la API puede devolver una razón de parada pause_turn, indicando que la API ha pausado un turno de larga duración.

Aquí se explica cómo manejar la razón de parada pause_turn:

Al manejar pause_turn:

Continúa la conversación: Pasa la respuesta pausada tal como está en una solicitud posterior para permitir que Claude continúe su turno
Modifica si es necesario: Opcionalmente puedes modificar el contenido antes de continuar si deseas interrumpir o redirigir la conversación
Preserva el estado de la herramienta: Incluye las mismas herramientas en la solicitud de continuación para mantener la funcionalidad

ZDR y allowed_callers

Las versiones básicas de búsqueda web (web_search_20250305) y obtención web (web_fetch_20250910) son elegibles para Retención Cero de Datos (ZDR).

Las versiones _20260209 con filtrado dinámico no son elegibles para ZDR por defecto porque el filtrado dinámico se basa en la ejecución de código internamente.

Para usar una herramienta de servidor _20260209 con ZDR, deshabilita el filtrado dinámico estableciendo "allowed_callers": ["direct"] en la herramienta:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

Esto restringe la herramienta solo a invocación directa, omitiendo el paso de ejecución de código interno.

Aunque la herramienta de obtención web en sí es elegible para ZDR, los editores de sitios web pueden retener cualquier parámetro pasado a la URL si Claude obtiene contenido de su sitio.

Filtrado de dominios

Las herramientas del servidor que acceden a la web aceptan parámetros allowed_domains y blocked_domains para controlar qué dominios puede alcanzar Claude.

Cuando se utilizan 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 devuelven un error de herramienta invalid_tool_input.

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 aún más los dominios, no anular ni 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 devuelve un error de validación.

Ten en cuenta que los caracteres Unicode en nombres de dominio pueden crear vulnerabilidades de seguridad a través de ataques de homografía, donde caracteres visualmente similares de diferentes scripts pueden eludir filtros de dominio. Por ejemplo, аmazon.com (usando la 'а' cirílica) puede parecer idéntico a amazon.com pero representa un dominio diferente.

Al configurar listas de permitidos/bloqueados de dominios:

Usa nombres de dominio solo ASCII cuando sea posible
Ten en cuenta que los analizadores de URL pueden manejar la normalización Unicode de manera diferente
Prueba tus filtros de dominio con variaciones potenciales de homografía
Audita regularmente tus configuraciones de dominio para caracteres Unicode sospechosos

Filtrado dinámico con ejecución de código

Las versiones _20260209 de búsqueda web y obtención web utilizan ejecución de código internamente para aplicar filtros dinámicos contra resultados de búsqueda.

Incluir una herramienta code_execution independiente junto con versiones _20260209 de herramientas web crea dos entornos de ejecución, lo que puede confundir al modelo. Usa uno u otro, o fija ambos a la misma versión.

Transmisión de eventos de herramientas del servidor

Los eventos de herramientas del servidor se transmiten como parte del flujo SSE normal. El bloque server_tool_use y su resultado llegan como eventos content_block_start y content_block_delta, de la misma manera que el texto y las llamadas de herramientas del cliente se transmiten.

Consulta Transmisión para la referencia completa de eventos. Las páginas de herramientas individuales documentan nombres de eventos específicos de herramientas donde difieren.

Solicitudes por lotes

Todas las herramientas del servidor admiten procesamiento por lotes. Consulta Procesamiento por lotes.

Próximos pasos

Búsqueda web

Busca en la web y cita resultados.

Obtención web

Recupera contenido de URLs específicas.

Ejecución de código

Ejecuta Python en un contenedor aislado.

Búsqueda de herramientas

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)