Resultados de búsqueda

Los bloques de contenido de resultados de búsqueda habilitan citas naturales con atribución adecuada de fuentes, llevando citas con calidad de búsqueda web a tus aplicaciones personalizadas. Esta función es particularmente potente para aplicaciones de "Retrieval-Augmented Generation" (generación aumentada por recuperación), o RAG, donde necesitas que Claude cite fuentes con precisión.

La función de resultados de búsqueda está disponible en los siguientes modelos:

• Claude Opus 4.8 (claude-opus-4-8)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (obsoleto) (claude-opus-4-1-20250805)
• Claude Opus 4 (obsoleto) (claude-opus-4-20250514)
• Claude Sonnet 4 (obsoleto) (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (retirado, excepto en Bedrock y Vertex AI) (claude-3-5-haiku-20241022)



Beneficios clave

• Citas naturales: Logra la misma calidad de citas que la búsqueda web para cualquier contenido
• Integración flexible: Úsalo en retornos de herramientas para RAG dinámico o como contenido de nivel superior para datos obtenidos previamente
• Atribución adecuada de fuentes: Cada resultado incluye información de fuente y título para una atribución clara
• Sin necesidad de soluciones alternativas con documentos: Elimina la necesidad de soluciones alternativas basadas en documentos
• Formato de citas consistente: Coincide con la calidad y el 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 a 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 obtenido previamente o almacenado en caché

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



Esquema de resultados de búsqueda

Los resultados de búsqueda usan la siguiente estructura:

{
  "type": "search_result",
  "source": "https://example.com/article", // Required: Source URL or identifier
  "title": "Article Title", // Required: Title of the result
  "content": [
    // Required: Array of text blocks
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {
    // Optional: Citation configuration
    "enabled": true // Enable/disable citations for this result
  }
}



Campos obligatorios



Campos opcionales

Cada elemento en el arreglo 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 a herramientas

El caso de uso más potente 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 conocimientos

from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam,
)

client = Anthropic()

# Define una herramienta de búsqueda en la base de conocimientos
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Search the company knowledge base for information",
    "input_schema": {
        "type": "object",
        "properties": {"query": {"type": "string", "description": "The search query"}},
        "required": ["query"],
    },
}


# Función para gestionar la llamada a la herramienta
def search_knowledge_base(query):
    # Tu lógica de búsqueda aquí
    # Devuelve los resultados de búsqueda en el formato correcto
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Product Configuration Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.",
                )
            ],
            citations={"enabled": True},
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Troubleshooting Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.",
                )
            ],
            citations={"enabled": True},
        ),
    ]


# Crea un mensaje con la herramienta
response = client.messages.create(
    model="claude-opus-4-8",  # Works with all supported models
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(role="user", content="How do I configure the timeout settings?")
    ],
)

# 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 de vuelta el resultado de la herramienta
    final_response = client.messages.create(
        model="claude-opus-4-8",  # Works with all supported models
        max_tokens=1024,
        messages=[
            MessageParam(
                role="user", content="How do I configure the timeout settings?"
            ),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result,  # Search results go here
                    )
                ],
            ),
        ],
    )



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 obtenido previamente desde tu infraestructura de búsqueda
• Resultados de búsqueda almacenados en caché de consultas anteriores
• Contenido de servicios de búsqueda externos
• Pruebas y desarrollo



Ejemplo: Resultados de búsqueda directos

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Proporciona los resultados de búsqueda directamente en el mensaje del usuario
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="API Reference - Authentication",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Getting Started Guide",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="Based on these search results, how do I authenticate API requests and what are the rate limits?",
                ),
            ],
        )
    ],
)

print(response)



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": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\nTo set this up from scratch, you'll need to "
    },
    {
      "type": "text",
      "text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.",
          "source": "https://docs.company.com/quickstart",
          "title": "Getting Started Guide",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}



Campos de citas

Cada cita incluye:

Los índices de bloques identifican un segmento del arreglo content del resultado de búsqueda, y cited_text es el texto completo de ese segmento. El bloque de texto es la unidad mínima citable: Claude cita bloques completos, no subcadenas dentro de un bloque. Para obtener citas más granulares, divide el contenido de tu resultado de búsqueda en bloques más pequeños (consulta Múltiples bloques de contenido).



Múltiples bloques de contenido

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

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "API Documentation",
  "content": [
    {
      "type": "text",
      "text": "Authentication: All API requests require an API key."
    },
    {
      "type": "text",
      "text": "Rate Limits: The API allows 1000 requests per hour per key."
    },
    {
      "type": "text",
      "text": "Error Handling: The API returns standard HTTP status codes."
    }
  ]
}

Una cita que hace referencia al bloque de límites de velocidad se ve así:

{
  "type": "search_result_location",
  "cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
  "source": "https://docs.company.com/api-guide",
  "title": "API Documentation",
  "search_result_index": 0,
  "start_block_index": 1,
  "end_block_index": 2
}

Cuando se cita este resultado de búsqueda, start_block_index y end_block_index identifican cuáles de estos bloques cubre la cita, y cited_text contiene exactamente el texto de esos bloques. Dividir el contenido en bloques más pequeños y enfocados le da a Claude límites de citas más precisos; combinar el contenido en un solo bloque significa que cada cita devuelve el texto completo. Este es el mismo modelo usado por los documentos de contenido personalizado en la función de Citas.



Uso avanzado



Combinar ambos métodos

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

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# Primer mensaje con resultados de búsqueda de nivel superior
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(
                        type="text", text="Our product helps teams collaborate..."
                    )
                ],
                citations={"enabled": True},
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information",
            ),
        ],
    )
]

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



Combinar con otros tipos de contenido

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

from anthropic.types import SearchResultBlockParam, TextBlockParam

# En resultados de herramientas
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True},
    ),
    TextBlockParam(
        type="text", text="Additional context: This applies to version 2.0 and later."
    ),
]

# En contenido de nivel superior
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True},
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"},
    },
    TextBlockParam(
        type="text", text="How does the chart relate to the research findings?"
    ),
]



Control de caché

Agrega control de caché para un mejor rendimiento:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{ "type": "text", "text": "..." }],
  "cache_control": {
    "type": "ephemeral"
  }
}



Control de citas

De forma predeterminada, las citas están deshabilitadas para los resultados de búsqueda. Puedes habilitar las citas configurando explícitamente la configuración citations:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{ "type": "text", "text": "Important documentation..." }],
  "citations": {
    "enabled": true // Enable citations for this result
  }
}

Cuando citations.enabled se establece en true, Claude incluye referencias de citas cuando usa información del resultado de búsqueda. Esto habilita:

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



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 fallen
• 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 obtenido previamente: Úsalo cuando ya tengas resultados de búsqueda
• Procesamiento por lotes: Ideal para procesar múltiples resultados de búsqueda a la vez
• Pruebas: Excelente para probar el comportamiento de citas con contenido conocido



Mejores prácticas generales

1. Estructura los resultados de manera efectiva:

   • Usa URLs de fuente claras y permanentes
   • Proporciona títulos descriptivos
   • Divide el contenido largo en bloques de texto lógicos para darle a Claude límites de citas más precisos

2. Mantén la consistencia:

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

3. Maneja los errores con elegancia:

   def search_with_fallback(query):
       try:
           results = perform_search(query)
           if not results:
               return {"type": "text", "text": "No results found."}
           return format_as_search_results(results)
       except Exception as e:
           return {"type": "text", "text": f"Search error: {str(e)}"}

   



Limitaciones

• Los bloques de contenido de resultados de búsqueda están disponibles en la API de Claude, Amazon Bedrock y Vertex AI de Google Cloud
• Solo se admite contenido de texto dentro de los resultados de búsqueda (no imágenes ni otros medios)
• El arreglo content debe contener al menos un bloque de texto