Los bloques de contenido de resultados de búsqueda están actualmente en beta. Usa el encabezado beta search-results-2025-06-09 para habilitar esta función.

Los bloques de contenido de resultados de búsqueda habilitan citas naturales con atribución de fuente adecuada, llevando citas de calidad de búsqueda web a tus aplicaciones personalizadas. Esta función es particularmente poderosa para aplicaciones RAG (Generación Aumentada por Recuperación) donde necesitas que Claude cite fuentes con precisión.

​
Beneficios clave

  • Citas naturales - Logra la misma calidad de citas que la búsqueda web para cualquier contenido
  • Integración flexible - Úsala en retornos de herramientas para RAG dinámico o como contenido de nivel superior para datos pre-obtenidos
  • Atribución de fuente adecuada - Cada resultado incluye información de fuente y título para una atribución clara
  • No se necesitan soluciones alternativas de documentos - Elimina la necesidad de soluciones alternativas basadas en documentos
  • Formato de cita consistente - Coincide con la calidad y formato de citas de la funcionalidad de búsqueda web de Claude

​
Cómo funciona

Los resultados de búsqueda se pueden proporcionar de dos maneras:

  1. Desde llamadas de herramientas - Tus herramientas personalizadas devuelven resultados de búsqueda, habilitando aplicaciones RAG dinámicas
  2. Como contenido de nivel superior - Proporcionas resultados de búsqueda directamente en mensajes de usuario para contenido pre-obtenido o en caché

En ambos casos, Claude puede citar automáticamente información de los resultados de búsqueda con atribución de fuente adecuada.

​
Esquema de resultado de búsqueda

Los resultados de búsqueda usan la siguiente estructura:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Requerido: URL de fuente o identificador
  "title": "Título del Artículo",                  // Requerido: Título del resultado
  "content": [ // Requerido: Array de bloques de texto
    {
      "type": "text",
      "text": "El contenido real del resultado de búsqueda..."
    }
  ],
  "citations": {                             // Opcional: Configuración de citas
    "enabled": true                          // Habilitar/deshabilitar citas para este resultado
  }
}

​
Campos requeridos

CampoTipoDescripción
typestringDebe ser "search_result"
sourcestringLa URL de fuente o identificador para el contenido
titlestringUn título descriptivo para el resultado de búsqueda
contentarrayUn array de bloques de texto que contienen el contenido real

​
Campos opcionales

CampoTipoDescripción
citationsobjectConfiguración de citas con campo booleano enabled
cache_controlobjectConfiguraciones de control de caché (ej., {"type": "ephemeral"})

Cada elemento en el array content debe ser un bloque de texto con:

  • type: Debe ser "text"
  • text: El contenido de texto real (cadena no vacía)

​
Método 1: Resultados de búsqueda desde llamadas de herramientas

El caso de uso más poderoso es devolver resultados de búsqueda desde tus herramientas personalizadas. Esto habilita aplicaciones RAG dinámicas donde las herramientas obtienen y devuelven contenido relevante con citas automáticas.

​
Ejemplo: Herramienta de base de conocimiento

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

client = Anthropic()

# Define una herramienta de búsqueda de base de conocimiento
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Buscar en la base de conocimiento de la empresa para obtener información",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "La consulta de búsqueda"
            }
        },
        "required": ["query"]
    }
}

# Función para manejar la llamada de herramienta
def search_knowledge_base(query):
    # Tu lógica de búsqueda aquí
    # Devuelve resultados de búsqueda en el formato correcto
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Guía de Configuración del Producto",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Para configurar el producto, navega a Configuración > Configuración. El tiempo de espera predeterminado es de 30 segundos, pero se puede ajustar entre 10-120 segundos según tus necesidades."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Guía de Solución de Problemas",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Si encuentras errores de tiempo de espera, primero verifica la configuración. Las causas comunes incluyen latencia de red y valores de tiempo de espera incorrectos."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Crear un mensaje con la herramienta
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="¿Cómo configuro la configuración de tiempo de espera?"
        )
    ]
)

# Cuando Claude llama a la herramienta, proporciona los resultados de búsqueda
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Envía el resultado de la herramienta de vuelta
    final_response = client.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="¿Cómo configuro la configuración de tiempo de espera?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Los resultados de búsqueda van aquí
                    )
                ]
            )
        ]
    )

​
Método 2: Resultados de búsqueda como contenido de nivel superior

También puedes proporcionar resultados de búsqueda directamente en mensajes de usuario. Esto es útil para:

  • Contenido pre-obtenido de tu infraestructura de búsqueda
  • Resultados de búsqueda en caché de consultas anteriores
  • Contenido de servicios de búsqueda externos
  • Pruebas y desarrollo

​
Ejemplo: Resultados de búsqueda directos

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Proporcionar resultados de búsqueda directamente en el mensaje del usuario
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Referencia de API - Autenticación",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Todas las solicitudes de API deben incluir una clave de API en el encabezado de Autorización. Las claves se pueden generar desde el panel de control. Límites de velocidad: 1000 solicitudes por hora para el nivel estándar, 10000 para premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Guía de Inicio Rápido",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Para comenzar: 1) Regístrate para obtener una cuenta, 2) Genera una clave de API desde el panel de control, 3) Instala nuestro SDK usando pip install company-sdk, 4) Inicializa el cliente con tu clave de API."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="Basándome en estos resultados de búsqueda, ¿cómo autentico las solicitudes de API y cuáles son los límites de velocidad?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Respuesta de Claude con citas

Independientemente de cómo se proporcionen los resultados de búsqueda, Claude incluye automáticamente citas cuando usa información de ellos:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Para autenticar solicitudes de API, necesitas incluir una clave de API en el encabezado de Autorización",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referencia de API - Autenticación",
          "cited_text": "Todas las solicitudes de API deben incluir una clave de API en el encabezado de Autorización",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Puedes generar claves de API desde tu panel de control",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referencia de API - Autenticación",
          "cited_text": "Las claves se pueden generar desde el panel de control",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Los límites de velocidad son 1,000 solicitudes por hora para el nivel estándar y 10,000 solicitudes por hora para el nivel premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referencia de API - Autenticación",
          "cited_text": "Límites de velocidad: 1000 solicitudes por hora para el nivel estándar, 10000 para premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Campos de cita

Cada cita incluye:

CampoTipoDescripción
typestringSiempre "search_result_location" para citas de resultados de búsqueda
sourcestringLa fuente del resultado de búsqueda original
titlestring o nullEl título del resultado de búsqueda original
cited_textstringEl texto exacto que se está citando
search_result_indexintegerÍndice del resultado de búsqueda (basado en 0)
start_block_indexintegerPosición inicial en el array de contenido
end_block_indexintegerPosición final en el array de contenido

Nota: El search_result_index se refiere al índice del bloque de contenido del resultado de búsqueda (basado en 0), independientemente de cómo se proporcionaron los resultados de búsqueda (llamada de herramienta o contenido de nivel superior).

​
Múltiples bloques de contenido

Los resultados de búsqueda pueden contener múltiples bloques de texto en el array content:

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "Documentación de API",
  "content": [
    {
      "type": "text",
      "text": "Autenticación: Todas las solicitudes de API requieren una clave de API."
    },
    {
      "type": "text",
      "text": "Límites de Velocidad: La API permite 1000 solicitudes por hora por clave."
    },
    {
      "type": "text",
      "text": "Manejo de Errores: La API devuelve códigos de estado HTTP estándar."
    }
  ]
}

Claude puede citar bloques específicos usando los campos start_block_index y end_block_index.

​
Uso avanzado

​
Combinando ambos métodos

Puedes usar tanto resultados de búsqueda basados en herramientas como de nivel superior en la misma conversación:

# Primer mensaje con resultados de búsqueda de nivel superior
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Resumen del Producto",
                content=[
                    BetaTextBlockParam(type="text",text="Nuestro producto ayuda a los equipos a colaborar...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Cuéntame sobre este producto y busca información de precios"
            )
        ]
    )
]

# Claude podría responder y llamar a una herramienta para buscar precios
# Luego proporcionas resultados de herramientas con más resultados de búsqueda

​
Combinando con otros tipos de contenido

Ambos métodos soportan mezclar resultados de búsqueda con otro contenido:

# En resultados de herramientas
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Guía del Usuario",
        content=[BetaTextBlockParam(type="text", text="Detalles de configuración...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Contexto adicional: Esto se aplica a la versión 2.0 y posteriores."
    )
]

# En contenido de nivel superior
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Artículo de Investigación",
        content=[BetaTextBlockParam(type="text", text="Hallazgos clave...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="¿Cómo se relaciona el gráfico con los hallazgos de la investigación?"
    )
]

​
Control de caché

Agrega control de caché para mejor rendimiento:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Guía del Usuario",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

​
Control de citas

Por defecto, las citas están deshabilitadas para los resultados de búsqueda. Puedes habilitar citas estableciendo explícitamente la configuración citations:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Guía del Usuario",
  "content": [{"type": "text", "text": "Documentación importante..."}],
  "citations": {
    "enabled": true  // Habilitar citas para este resultado
  }
}

Cuando citations.enabled se establece en true, Claude incluirá referencias de citas al usar información del resultado de búsqueda. Esto habilita:

  • Citas naturales para tus aplicaciones RAG personalizadas
  • Atribución de fuente al interfaz con bases de conocimiento propietarias
  • Citas de calidad de búsqueda web para cualquier herramienta personalizada que devuelva resultados de búsqueda

Si se omite el campo citations, las citas están deshabilitadas por defecto.

Las citas son todo o nada: todos los resultados de búsqueda en una solicitud deben tener citas habilitadas, o todos deben tenerlas deshabilitadas. Mezclar resultados de búsqueda con diferentes configuraciones de citas resultará en un error. Si necesitas deshabilitar citas para algunas fuentes, debes deshabilitarlas para todos los resultados de búsqueda en esa solicitud.

​
Mejores prácticas

​
Para búsqueda basada en herramientas (Método 1)

  • Contenido dinámico: Úsalo para búsquedas en tiempo real y aplicaciones RAG dinámicas
  • Manejo de errores: Devuelve mensajes apropiados cuando las búsquedas fallan
  • Límites de resultados: Devuelve solo los resultados más relevantes para evitar desbordamiento de contexto

​
Para búsqueda de nivel superior (Método 2)

  • Contenido pre-obtenido: Úsalo cuando ya tienes resultados de búsqueda
  • Procesamiento por lotes: Ideal para procesar múltiples resultados de búsqueda a la vez
  • Pruebas: Excelente para probar comportamiento de citas con contenido conocido

​
Mejores prácticas generales

  1. Estructura los resultados efectivamente

    • Usa URLs de fuente claras y permanentes
    • Proporciona títulos descriptivos
    • Divide contenido largo en bloques de texto lógicos

  2. Mantén consistencia

    • Usa formatos de fuente consistentes en tu aplicación
    • Asegúrate de que los títulos reflejen con precisión el contenido
    • Mantén el formato consistente

  3. Maneja errores con gracia

    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "No se encontraron resultados."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Error de búsqueda: {str(e)}"}

​
Limitaciones

  • Los bloques de contenido de resultados de búsqueda solo están disponibles con el encabezado beta
  • Solo se soporta contenido de texto dentro de los resultados de búsqueda (no imágenes u otros medios)
  • El array content debe contener al menos un bloque de texto