Risultati di ricerca
Ottieni citazioni naturali per le applicazioni RAG fornendo risultati di ricerca con attribuzione della fonte
L’utilizzo varia in base al prodotto
search_result in un risultato di uno strumento o direttamente in un messaggio dell’utente.user.custom_tool_result, non negli eventi user.message.I blocchi di contenuto dei risultati di ricerca consentono a Claude di citare i tuoi contenuti nello stesso modo in cui cita i risultati della ricerca web: ogni citazione riporta la fonte e il titolo che hai fornito. Usali nelle applicazioni RAG (“Retrieval-Augmented Generation”, generazione aumentata dal recupero) in cui Claude deve attribuire le risposte ai tuoi documenti.
Come funziona
I risultati di ricerca possono essere forniti in due modi:
- Dalle chiamate agli strumenti: i tuoi strumenti personalizzati restituiscono risultati di ricerca, il che ti consente di creare applicazioni RAG dinamiche.
- Come contenuto di primo livello: fornisci i risultati di ricerca direttamente nei messaggi dell’utente per contenuti pre-recuperati o memorizzati nella cache.
In entrambi i casi, Claude cita automaticamente i risultati di ricerca quando le citazioni sono abilitate. Non è necessario alcun prompt speciale: poni la tua domanda e le citazioni compaiono sui blocchi di testo che attingono ai tuoi contenuti. Tuttavia, se il tuo prompt richiede solo JSON, la risposta potrebbe contenere poche citazioni o nessuna. Per estrarre dati strutturati con una citazione per ogni valore, consulta Ottenere dati strutturati con citazioni.
Schema dei risultati di ricerca
I risultati di ricerca utilizzano la seguente struttura:
{
"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
}
}Campi obbligatori
| Campo | Tipo | Descrizione |
|---|---|---|
type | string | Deve essere "search_result" |
source | string | La fonte del contenuto. Va bene qualsiasi stringa stabile: un URL o un identificatore interno come kb://article-1234 |
title | string | Un titolo descrittivo per il risultato di ricerca |
content | array | Un array di blocchi di testo contenenti il contenuto effettivo |
Campi facoltativi
| Campo | Tipo | Descrizione |
|---|---|---|
citations | object | Configurazione delle citazioni con il campo booleano enabled. Le citazioni sono disabilitate per impostazione predefinita; ogni esempio in questa pagina imposta "enabled": true esplicitamente. Tutti i risultati di ricerca in una richiesta devono usare la stessa impostazione (consulta Controllo delle citazioni) |
cache_control | object | Impostazioni di controllo della cache (ad esempio, {"type": "ephemeral"}) |
Ogni elemento dell’array content deve essere un blocco di testo con:
type: deve essere"text"text: il contenuto testuale effettivo (stringa non vuota)
I risultati di ricerca contengono solo testo. Immagini e altri media non sono supportati all’interno dell’array content.
Metodo 1: Risultati di ricerca dalle chiamate agli strumenti
Restituire risultati di ricerca dai tuoi strumenti personalizzati ti consente di creare applicazioni RAG dinamiche: gli strumenti recuperano i contenuti in fase di esecuzione e Claude li cita nella risposta. L’esempio seguente forza la chiamata allo strumento con tool_choice, in modo che la fase di recupero venga eseguita ogni volta.
Esempio: Strumento di knowledge base
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam,
)
client = Anthropic()
# Definisci uno strumento di ricerca nella knowledge base
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"],
},
}
# Funzione per gestire la chiamata allo strumento
def search_knowledge_base(query):
# La tua logica di ricerca qui
# Restituisce i risultati di ricerca nel formato corretto
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},
),
]
# Costruisci la conversazione in una lista, iniziando dalla domanda dell'utente
messages: list[MessageParam] = [
{"role": "user", "content": "How do I configure the timeout settings?"}
]
# Crea un messaggio con lo strumento
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,
)
# Quando Claude chiama lo strumento, fornisci i risultati di ricerca.
# Il blocco tool_use non è sempre il primo: itera per trovarlo.
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"])
# Aggiungi il turno di Claude, poi il risultato dello strumento, alla conversazione in corso
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
)
],
}
)
# Rimanda indietro il risultato dello strumento
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)Metodo 2: Risultati di ricerca come contenuto di primo livello
Puoi anche fornire i risultati di ricerca direttamente nei messaggi dell’utente. Questo è utile per:
- Contenuti pre-recuperati dalla tua infrastruttura di ricerca
- Risultati di ricerca memorizzati nella cache da query precedenti
- Contenuti provenienti da servizi di ricerca esterni
- Test e sviluppo
Esempio: Risultati di ricerca diretti
from anthropic.types import TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Fornisci i risultati di ricerca direttamente nel messaggio dell'utente
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)Risposta di Claude con citazioni
Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente le citazioni quando utilizza le informazioni in essi contenute:
{
"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
}
]
}
]
}Campi delle citazioni
Ogni citazione include:
| Campo | Tipo | Descrizione |
|---|---|---|
type | string | Sempre "search_result_location" per le citazioni dei risultati di ricerca |
source | string | La fonte del risultato di ricerca originale |
title | string o null | Il titolo del risultato di ricerca originale |
cited_text | string | Il testo completo del blocco o dei blocchi citati, concatenato. Corrisponde al contenuto di content[start_block_index:end_block_index] unito. Non viene conteggiato nei token di output. |
search_result_index | integer | Indice a base 0 del risultato di ricerca citato tra tutti i blocchi search_result nella richiesta, nell’ordine in cui compaiono (in tutti i messaggi e i risultati degli strumenti). |
start_block_index | integer | Indice a base 0 del primo blocco citato nell’array content del risultato di ricerca. |
end_block_index | integer | Indice finale esclusivo dell’intervallo di blocchi citati nell’array content del risultato di ricerca. Sempre maggiore di start_block_index. |
Gli indici dei blocchi identificano una porzione dell’array content del risultato di ricerca, e cited_text è il testo completo di quella porzione. Il blocco di testo è l’unità minima citabile: Claude cita blocchi interi, non sottostringhe all’interno di un blocco. Per ottenere citazioni più granulari, suddividi il contenuto dei risultati di ricerca in blocchi più piccoli (consulta Blocchi di contenuto multipli).
Blocchi di contenuto multipli
I risultati di ricerca possono contenere più blocchi di testo nell’array 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 citazione che fa riferimento al blocco sui limiti di velocità ha questo aspetto:
{
"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
}Quando questo risultato di ricerca viene citato, start_block_index e end_block_index identificano quali di questi blocchi sono coperti dalla citazione, e cited_text contiene esattamente il testo di quei blocchi. Suddividere il contenuto in blocchi più piccoli e mirati offre a Claude confini di citazione più precisi; combinare il contenuto in un unico blocco significa che ogni citazione restituisce il testo completo. Questo è lo stesso modello utilizzato dai documenti con contenuto personalizzato nella funzionalità Citazioni.
Utilizzo avanzato
Combinare entrambi i metodi
Puoi combinare entrambi i metodi nella stessa conversazione. Claude cita da entrambe le fonti, e search_result_index conta tutti i blocchi search_result nell’ordine della richiesta, indipendentemente dalla fonte.
L’esempio seguente riproduce una conversazione completa. Il primo messaggio dell’utente contiene un risultato di ricerca pre-recuperato, il turno dell’assistente chiama uno strumento di knowledge base e il risultato dello strumento restituisce un secondo risultato di ricerca. La risposta di Claude cita entrambe le fonti:
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"],
},
}
# Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
# messaggio utente contiene un risultato già recuperato e il risultato dello strumento ne restituisce un altro
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 risposta cita entrambe le fonti. Il risultato pre-recuperato è search_result_index: 0 e il risultato restituito dallo strumento è search_result_index: 1, in corrispondenza dell’ordine in cui i blocchi search_result compaiono nella conversazione:
{
"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
}
]
}
]
}Combinazione con altri tipi di contenuto
Nei messaggi dell’utente, i blocchi search_result possono trovarsi accanto a qualsiasi altro blocco di contenuto. L’esempio del Metodo 2 abbina i risultati di ricerca a una domanda text, e i blocchi di immagini o documenti possono unirsi allo stesso modo.
I risultati degli strumenti sono più rigidi: se un qualsiasi blocco nell’array di contenuto di un tool_result è un search_result, tutti i suoi blocchi devono essere search_result. Combinare risultati di ricerca con altri tipi di blocchi nello stesso risultato dello strumento restituisce un errore di convalida. Per restituire testo di supporto insieme ai risultati di ricerca provenienti dagli strumenti, includilo come blocco di testo all’interno dell’array content di uno dei risultati di ricerca, dove diventa anch’esso citabile.
Controllo della cache
Aggiungi cache_control sul blocco del risultato di ricerca per memorizzarlo nella cache e riutilizzarlo tra le richieste. Si trova accanto a citations sullo stesso blocco:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"citations": { "enabled": true },
"cache_control": { "type": "ephemeral" }
}Consulta Cache dei prompt per le lunghezze minime memorizzabili nella cache e gli altri requisiti.
Controllo delle citazioni
Per impostazione predefinita, le citazioni sono disabilitate per i risultati di ricerca. Puoi abilitare le citazioni impostando esplicitamente la configurazione 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
}
}Quando citations.enabled è impostato su true, Claude allega riferimenti di citazione ai blocchi di testo che attingono al risultato di ricerca.
Best practice
Per la ricerca basata su strumenti (Metodo 1)
- Contenuti dinamici: usala per ricerche in tempo reale e applicazioni RAG dinamiche
- Gestione degli errori: restituisci messaggi appropriati quando le ricerche non riescono
- Limiti dei risultati: restituisci solo i risultati più pertinenti per evitare l’overflow del contesto
Per la ricerca di primo livello (Metodo 2)
- Contenuti pre-recuperati: usala quando disponi già di risultati di ricerca
- Elaborazione in batch: usala per elaborare più risultati di ricerca contemporaneamente
- Test: usala per testare il comportamento delle citazioni con contenuti noti
Best practice generali
-
Struttura i risultati in modo efficace:
- Usa URL di origine chiari e permanenti
- Fornisci titoli descrittivi
- Suddividi i contenuti lunghi in blocchi di testo logici per offrire a Claude confini di citazione più precisi
-
Mantieni la coerenza:
- Usa formati di origine coerenti in tutta la tua applicazione
- Assicurati che i titoli riflettano accuratamente il contenuto
- Mantieni una formattazione coerente
-
Gestisci gli errori con eleganza: quando una ricerca non riesce o non restituisce nulla, restituisci un semplice blocco di testo che descrive l’esito (ad esempio,
{"type": "text", "text": "No results found."}) invece di generare un errore: Claude spiega il risultato vuoto all’utente e la conversazione prosegue.
Limitazioni
- All’interno dei risultati di ricerca è supportato solo il contenuto testuale (niente immagini o altri media).
- I blocchi
search_resultpossono comparire solo nei messaggi dell’utente (anche all’interno dei risultati degli strumenti). I messaggi dell’assistente con risultati di ricerca vengono rifiutati. - Quando lo strumento di ricerca web è abilitato nella stessa richiesta, le citazioni devono essere abilitate su tutti i blocchi
search_result.
Passaggi successivi
Rileva e gestisci i motivi di interruzione per rifiuto nelle risposte in streaming e riprova le richieste rifiutate su un modello di fallback.
Basa le risposte di Claude sui tuoi documenti di origine. Le citazioni restituiscono i passaggi esatti che supportano ogni affermazione, così puoi verificare le risposte e mostrare le fonti ai tuoi utenti.
Offri a Claude l’accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico facoltativo e controlli sui domini.
Consulta la documentazione completa della Messages API, inclusi i tipi di blocchi di contenuto.
Memorizza nella cache i risultati di ricerca con cache_control per ridurre costi e latenza nelle richieste ripetute.
Disponibilità
Claude API
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Amazon Bedrock
- API
- Messages API
- Modelli
- Tutti i modelli
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelli
- Tutti i modelli
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelli
- Tutti i modelli
Microsoft Foundry
- API
- Messages API
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/messagescon sorgentesearch_results
Esclude Modelli coperti
Questa pagina ti è stata utile?