Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
I blocchi di contenuto dei risultati di ricerca consentono a Claude di citare i tuoi contenuti nello stesso modo in cui cita i risultati di 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.
Tutti i modelli attivi supportano i risultati di ricerca con citazioni, ad eccezione di Claude Haiku 3. Non è richiesto alcun header beta: i risultati di ricerca fanno parte dell'API Messages standard.
I risultati di ricerca possono essere forniti in due modi:
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 appaiono sui blocchi di testo che attingono ai tuoi contenuti.
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
}
}| Campo | Tipo | Descrizione |
|---|---|---|
type | string | Deve essere "search_result" |
source | string | La fonte del contenuto. Qualsiasi stringa stabile funziona: 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 |
| Campo | Tipo | Descrizione |
|---|---|---|
citations | object | Configurazione delle citazioni con campo booleano enabled. Le citazioni sono disabilitate per impostazione predefinita; ogni esempio in questa pagina imposta esplicitamente "enabled": true. Tutti i risultati di ricerca in una richiesta devono usare la stessa impostazione (vedi Controllo delle citazioni) |
cache_control | object | Impostazioni di controllo della cache (ad esempio, {"type": "ephemeral"}) |
Ogni elemento nell'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.
Restituire risultati di ricerca dai tuoi strumenti personalizzati abilita 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 il passaggio di recupero venga eseguito ogni volta.
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):
# Qui la tua logica di ricerca
# 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, partendo dalla domanda dell'utente
messages = [
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"},
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(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
)
],
)
)
# Invia indietro il risultato dello strumento
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)Puoi anche fornire i risultati di ricerca direttamente nei messaggi utente. Questo è utile per:
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Fornisci i risultati di ricerca direttamente nel messaggio utente
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)Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente le citazioni quando utilizza informazioni provenienti da essi:
{
"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
}
]
}
]
}Ogni citazione include:
| Campo | Tipo | Descrizione |
|---|---|---|
type | string | Sempre "search_result_location" per le citazioni dei risultati di ricerca |
source | string | La fonte dal risultato di ricerca originale |
title | string o null | Il titolo dal risultato di ricerca originale |
cited_text | string | Il testo completo del blocco o dei blocchi citati, concatenato. Equivale al contenuto di content[start_block_index:end_block_index] unito insieme. 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 appaiono (attraverso 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 di fine 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à citabile minima: Claude cita blocchi interi, non sottostringhe all'interno di un blocco. Per ottenere citazioni più granulari, suddividi il contenuto del risultato di ricerca in blocchi più piccoli (vedi 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à appare così:
{
"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 ed end_block_index identificano quali di questi blocchi la citazione copre, 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.
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 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 (
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"],
},
}
# Riproduci una conversazione che fornisce risultati di ricerca in entrambi i modi: il primo
# messaggio utente contiene un risultato pre-caricato, il tool_result ne restituisce un altro
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 risposta cita entrambe le fonti. Il risultato pre-recuperato è search_result_index: 0 e il risultato restituito dallo strumento è search_result_index: 1, corrispondenti all'ordine in cui i blocchi search_result appaiono 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
}
]
}
]
}Nei messaggi 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 immagine o documento possono unirsi a essi nello 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. Mescolare risultati di ricerca con altri tipi di blocco nello stesso risultato dello strumento restituisce un errore di validazione. Per restituire testo di supporto insieme ai risultati di ricerca provenienti dagli strumenti, includilo come blocco di testo all'interno di uno degli array content dei risultati di ricerca, dove diventa anch'esso citabile.
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 altri requisiti.
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.
Struttura i risultati in modo efficace:
Mantieni la coerenza:
Gestisci gli errori con eleganza: quando una ricerca fallisce o non restituisce nulla, restituisci un blocco di testo semplice che descriva 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 continua.
search_result possono apparire solo nei messaggi utente (inclusi quelli all'interno dei risultati degli strumenti). I messaggi dell'assistente con risultati di ricerca vengono rifiutati.search_result.Rileva e gestisci i motivi di arresto per rifiuto nelle risposte in streaming e riprova le richieste rifiutate su un modello di fallback.
Ancora le risposte di Claude ai 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.
Dai a Claude accesso ai contenuti web attuali con fonti citate, filtri dinamici opzionali e controlli sui domini.
Consulta la documentazione completa dell'API Messages, 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.
Was this page helpful?