Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Los bloques de contenido de resultados de búsqueda permiten que Claude cite tu propio contenido de la misma manera que cita los resultados de búsqueda web: cada cita lleva la fuente y el título que proporcionaste. Úsalos en aplicaciones RAG ("Retrieval-Augmented Generation", generación aumentada por recuperación) donde Claude necesita atribuir respuestas a tus documentos.
Todos los modelos activos admiten resultados de búsqueda con citas, con la excepción de Claude Haiku 3. No se requiere ningún encabezado beta: los resultados de búsqueda son parte de la API de Messages estándar.
Los resultados de búsqueda se pueden proporcionar de dos maneras:
En ambos casos, Claude cita los resultados de búsqueda automáticamente cuando las citas están habilitadas. No se necesita ninguna indicación especial: haz tu pregunta, y las citas aparecen en los bloques de texto que se basan en tu contenido.
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
}
}| Campo | Tipo | Descripción |
|---|---|---|
type | string | Debe ser "search_result" |
source | string | La fuente del contenido. Cualquier cadena estable funciona: una URL, o un identificador interno como kb://article-1234 |
title | string | Un título descriptivo para el resultado de búsqueda |
content | array | Un arreglo de bloques de texto que contienen el contenido real |
| Campo | Tipo | Descripción |
|---|---|---|
citations | object | Configuración de citas con el campo booleano enabled. Las citas están deshabilitadas de forma predeterminada; cada ejemplo en esta página establece "enabled": true explícitamente. Todos los resultados de búsqueda en una solicitud deben usar la misma configuración (consulta Control de citas) |
cache_control | object | Configuración de control de caché (por ejemplo, {"type": "ephemeral"}) |
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)Los resultados de búsqueda solo contienen texto. Las imágenes y otros medios no son compatibles dentro del arreglo content.
Devolver resultados de búsqueda desde tus herramientas personalizadas habilita 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 cada vez.
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, comenzando con la pregunta del usuario
messages = [
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"},
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(MessageParam(role="assistant", content=response.content))
messages.append(
MessageParam(
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)También puedes proporcionar resultados de búsqueda directamente en los mensajes del usuario. Esto es útil para:
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-5",
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)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
}
]
}
]
}Cada cita incluye:
| Campo | Tipo | Descripción |
|---|---|---|
type | string | Siempre "search_result_location" para citas de resultados de búsqueda |
source | string | La fuente del resultado de búsqueda original |
title | string o null | El título del resultado de búsqueda original |
cited_text | string | El texto completo del bloque o bloques citados, concatenado. Es igual al contenido de content[start_block_index:end_block_index] unido. No se cuenta para los output_tokens. |
search_result_index | integer | Índice basado en 0 del resultado de búsqueda citado entre todos los bloques search_result en la solicitud, en el orden en que aparecen (a través de todos los mensajes y resultados de herramientas). |
start_block_index | integer | Índice basado en 0 del primer bloque citado en el arreglo content del resultado de búsqueda. |
end_block_index | integer | Índice final exclusivo del rango de bloques citados en el arreglo content del resultado de búsqueda. Siempre mayor que start_block_index. |
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 citable mínima: 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).
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 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 cita 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 funcionalidad de Citas.
Puedes mezclar ambos métodos en la misma conversación. Claude cita desde cualquiera de las 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 lleva un resultado de búsqueda precargado, 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 (
MessageParam,
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 de usuario lleva un resultado precargado, el resultado de la herramienta devuelve otro
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
MessageParam(
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?",
),
],
),
MessageParam(
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"},
),
],
),
MessageParam(
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 precargado es search_result_index: 0 y el resultado devuelto por la herramienta es search_result_index: 1, coincidiendo con el orden en que los bloques search_result aparecen 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
}
]
}
]
}En los mensajes del usuario, los bloques search_result pueden coexistir con cualquier otro bloque de contenido. El ejemplo del Método 2 empareja resultados de búsqueda con una pregunta de tipo text, y los bloques de imagen o documento pueden unirse de la misma manera.
Los resultados de herramientas son más estrictos: si algún bloque en un arreglo de contenido de 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 de apoyo junto con resultados de búsqueda provenientes de herramientas, inclúyelo como un bloque de texto dentro de uno de los arreglos content de los resultados de búsqueda, donde también se vuelve citable.
Agrega cache_control en el bloque de resultado de búsqueda para almacenarlo en caché y reutilizarlo entre solicitudes. Se ubica 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.
De forma predeterminada, las citas están deshabilitadas para los resultados de búsqueda. Puedes habilitar las citas estableciendo explícitamente la configuración de 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.
Estructura los resultados de manera efectiva:
Mantén la consistencia:
Maneja los errores con elegancia: cuando una búsqueda falla o no devuelve 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 explica el resultado vacío al usuario, y la conversación continúa.
search_result solo pueden aparecer en mensajes del usuario (incluso dentro de resultados de herramientas). Los mensajes del asistente con resultados de búsqueda son rechazados.search_result.Detecta y maneja las razones de detención por rechazo en respuestas de streaming, y reintenta las solicitudes rechazadas en un modelo alternativo.
Fundamenta las respuestas de Claude en tus documentos fuente. Las citas devuelven los pasajes exactos que respaldan cada afirmación, para que puedas verificar las respuestas y mostrar las fuentes a tus usuarios.
Dale a Claude acceso a contenido web actual con fuentes citadas, filtrado dinámico opcional y controles de dominio.
Consulta la documentación completa de la API de Messages, incluidos los tipos de bloques de contenido.
Almacena en caché los resultados de búsqueda con cache_control para reducir el costo y la latencia en solicitudes repetidas.
Was this page helpful?