Resultados de búsqueda

Los bloques de contenido de resultados de búsqueda permiten que Claude cite tu propio contenido de la misma manera en que cita los resultados de búsqueda web: cada cita incluye la fuente y el título que proporcionaste. Úsalos en aplicaciones “Retrieval-Augmented Generation” (generación aumentada por recuperación), o RAG, donde Claude necesita atribuir las respuestas a tus documentos.

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, lo que te permite crear aplicaciones RAG dinámicas.
2. Como contenido de nivel superior: Proporcionas resultados de búsqueda directamente en los mensajes del usuario para contenido obtenido previamente o almacenado en caché.

En ambos casos, Claude cita los resultados de búsqueda automáticamente cuando las citas están habilitadas. No se necesitan indicaciones especiales: haz tu pregunta y las citas aparecerán en los bloques de texto que se basan en tu contenido. Sin embargo, si tu prompt solicita únicamente JSON, la respuesta podría contener pocas citas o ninguna. Para extraer datos estructurados con una cita para cada valor, consulta Obtener datos estructurados con citas.

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 del arreglo content debe ser un bloque de texto con:

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

Los resultados de búsqueda contienen solo texto. Las imágenes y otros medios no se admiten dentro del arreglo content.

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

Devolver resultados de búsqueda desde tus herramientas personalizadas te permite crear aplicaciones RAG dinámicas: las herramientas obtienen contenido en tiempo de ejecución y Claude lo cita en la respuesta. El siguiente ejemplo fuerza la llamada a la herramienta con tool_choice, de modo que el paso de recuperación se ejecuta siempre.

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 manejar 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},
        ),
    ]


# Construye la conversación en una lista, empezando por la pregunta del usuario
messages: list[MessageParam] = [
    {"role": "user", "content": "How do I configure the timeout settings?"}
]

# Crea un mensaje con la herramienta
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    tool_choice={
        "type": "tool",
        "name": "search_knowledge_base",
        "disable_parallel_tool_use": True,
    },
    messages=messages,
)

# Cuando Claude llame a la herramienta, proporciona los resultados de búsqueda.
# El bloque tool_use no siempre es el primero: itera para encontrarlo.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
    tool_result = search_knowledge_base(tool_use.input["query"])

    # Agrega el turno de Claude y luego el resultado de la herramienta a la conversación en curso
    messages.append({"role": "assistant", "content": response.content})
    messages.append(
        {
            "role": "user",
            "content": [
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id=tool_use.id,
                    content=tool_result,  # Search results go here
                )
            ],
        }
    )

    # Envía de vuelta el resultado de la herramienta
    final_response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
    )
    print(final_response)

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

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

• Contenido obtenido previamente de 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 TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Proporciona los resultados de búsqueda directamente en el mensaje del usuario
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "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 citas automáticamente 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 las citas

Cada cita incluye:

Los índices de bloque identifican una porción del arreglo content del resultado de búsqueda, y cited_text es el texto completo de esa porción. 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 detalladas, divide el contenido de tus resultados 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."
    }
  ],
  "citations": { "enabled": true }
}

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 qué bloques cubre la cita, y cited_text contiene exactamente el texto de esos bloques. Dividir el contenido en bloques más pequeños y específicos le da a Claude límites de cita más precisos; combinar el contenido en un solo bloque significa que cada cita devuelve el texto completo. Este es el mismo modelo que usan los documentos de contenido personalizado en la función de Citas.

Uso avanzado

Combinar ambos métodos

Puedes mezclar ambos métodos en la misma conversación. Claude cita de cualquiera de las dos fuentes, y search_result_index cuenta todos los bloques search_result en el orden de la solicitud, independientemente de la fuente.

El siguiente ejemplo reproduce una conversación completa. El primer mensaje del usuario contiene un resultado de búsqueda obtenido previamente, el turno del asistente llama a una herramienta de base de conocimientos y el resultado de la herramienta devuelve un segundo resultado de búsqueda. La respuesta de Claude cita ambas fuentes:

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

client = Anthropic()

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"],
    },
}

# Reproduce una conversación que proporciona resultados de búsqueda de ambas formas: el primer
# mensaje del usuario incluye un resultado obtenido previamente y el resultado de la herramienta devuelve otro
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        {
            "role": "user",
            "content": [
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/overview",
                    title="Product Overview",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="What does Acme Dashboard do, and what plans is it available on?",
                ),
            ],
        },
        {
            "role": "assistant",
            "content": [
                TextBlockParam(
                    type="text", text="Let me check the pricing information."
                ),
                ToolUseBlockParam(
                    type="tool_use",
                    id="toolu_01A09q90qw90lq917835lq9",
                    name="search_knowledge_base",
                    input={"query": "Acme Dashboard pricing plans"},
                ),
            ],
        },
        {
            "role": "user",
            "content": [
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id="toolu_01A09q90qw90lq917835lq9",
                    content=[
                        SearchResultBlockParam(
                            type="search_result",
                            source="https://docs.company.com/pricing",
                            title="Pricing Plans",
                            content=[
                                TextBlockParam(
                                    type="text",
                                    text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
                                )
                            ],
                            citations={"enabled": True},
                        )
                    ],
                )
            ],
        },
    ],
)

print(response)

La respuesta cita ambas fuentes. El resultado obtenido previamente es search_result_index: 0 y el resultado devuelto por la herramienta es search_result_index: 1, lo que coincide con el orden en que aparecen los bloques search_result en la conversación:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
          "source": "https://docs.company.com/overview",
          "title": "Product Overview",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\n**Available plans:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
          "source": "https://docs.company.com/pricing",
          "title": "Pricing Plans",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Mezclar con otros tipos de contenido

En los mensajes del usuario, los bloques search_result pueden ir junto a cualquier otro bloque de contenido. El ejemplo del Método 2 combina resultados de búsqueda con una pregunta text, y los bloques de imagen o documento pueden unirse a ellos de la misma manera.

Los resultados de herramientas son más estrictos: si algún bloque del arreglo de contenido de un tool_result es un search_result, todos sus bloques deben ser search_result. Mezclar resultados de búsqueda con otros tipos de bloques en el mismo resultado de herramienta devuelve un error de validación. Para devolver texto complementario junto con resultados de búsqueda obtenidos por herramientas, inclúyelo como un bloque de texto dentro del arreglo content de uno de los resultados de búsqueda, donde también se vuelve citable.

Control de caché

Agrega cache_control en el bloque del resultado de búsqueda para almacenarlo en caché y reutilizarlo entre solicitudes. Va junto a citations en el mismo bloque:

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

Consulta Almacenamiento en caché de prompts para conocer las longitudes mínimas almacenables en caché y otros requisitos.

Control de citas

De forma predeterminada, las citas están deshabilitadas para los resultados de búsqueda. Puedes habilitar las citas estableciendo 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 adjunta referencias de cita a los bloques de texto que se basan en el resultado de búsqueda.

Mejores prácticas

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

• Contenido dinámico: Úsala 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 el desbordamiento del contexto

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

• Contenido obtenido previamente: Úsala cuando ya tengas resultados de búsqueda
• Procesamiento por lotes: Úsala para procesar múltiples resultados de búsqueda a la vez
• Pruebas: Úsala para probar el comportamiento de las citas con contenido conocido

Mejores prácticas generales

1. Estructura los resultados de forma eficaz:

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

2. Mantén la coherencia:

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

3. Maneja los errores con elegancia: cuando una búsqueda falle o no devuelva nada, devuelve un bloque de texto simple que describa el resultado (por ejemplo, {"type": "text", "text": "No results found."}) en lugar de generar un error: Claude le explica el resultado vacío al usuario y la conversación continúa.

Limitaciones

• Solo se admite contenido de texto dentro de los resultados de búsqueda (no imágenes ni otros medios).
• Los bloques search_result solo pueden aparecer en mensajes del usuario (incluso dentro de resultados de herramientas). Los mensajes del asistente con resultados de búsqueda se rechazan.
• Cuando la herramienta de búsqueda web está habilitada en la misma solicitud, las citas deben estar habilitadas en todos los bloques search_result.

Próximos pasos