Claude Platform Docs
MessagesCapacità del modello

Risultati di ricerca

Abilita citazioni naturali per applicazioni RAG fornendo risultati di ricerca con attribuzione della fonte

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 della Messages API standard.

Come funziona

I risultati di ricerca possono essere forniti in due modi:

  1. Dalle chiamate agli strumenti: I tuoi strumenti personalizzati restituiscono risultati di ricerca, abilitando applicazioni RAG dinamiche
  2. Come contenuto di primo livello: Fornisci i risultati di ricerca direttamente nei messaggi utente per contenuti pre-recuperati o memorizzati in 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 nei blocchi di testo che attingono ai tuoi contenuti.

Schema dei risultati di ricerca

I risultati di ricerca usano 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

CampoTipoDescrizione
typestringDeve essere "search_result"
sourcestringLa fonte del contenuto. Qualsiasi stringa stabile funziona: un URL o un identificatore interno come kb://article-1234
titlestringUn titolo descrittivo per il risultato di ricerca
contentarrayUn array di blocchi di testo contenenti il contenuto effettivo

Campi opzionali

CampoTipoDescrizione
citationsobjectConfigurazione delle citazioni con il 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_controlobjectImpostazioni 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.

Metodo 1: Risultati di ricerca dalle chiamate agli strumenti

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 la fase di recupero venga eseguita ogni volta.

Esempio: Strumento per base di conoscenza

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):
    # Inserisci 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 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 utente. Questo è utile per:

  • Contenuti pre-recuperati dalla tua infrastruttura di ricerca
  • Risultati di ricerca memorizzati in cache da query precedenti
  • Contenuti da servizi di ricerca esterni
  • Test e sviluppo

Esempio: Risultati di ricerca diretti

from anthropic.types import MessageParam, 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=[
        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)

La risposta di Claude con citazioni

Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente le citazioni quando usa 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
        }
      ]
    }
  ]
}

Campi delle citazioni

Ogni citazione include:

CampoTipoDescrizione
typestringSempre "search_result_location" per le citazioni dei risultati di ricerca
sourcestringLa fonte del risultato di ricerca originale
titlestring o nullIl titolo del risultato di ricerca originale
cited_textstringIl testo completo del blocco o dei blocchi citati, concatenato. Equivale al contenuto di content[start_block_index:end_block_index] unito insieme. Non conteggiato nei token di output.
search_result_indexintegerIndice a base 0 del risultato di ricerca citato tra tutti i blocchi search_result nella richiesta, nell'ordine in cui compaiono (attraverso tutti i messaggi e i risultati degli strumenti).
start_block_indexintegerIndice a base 0 del primo blocco citato nell'array content del risultato di ricerca.
end_block_indexintegerIndice 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 tuoi risultati di ricerca in blocchi più piccoli (vedi 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à 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 e end_block_index identificano quali di questi blocchi copre la 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 usato dai documenti con contenuto personalizzato nella funzionalità Citazioni.

Uso 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 utente contiene un risultato di ricerca pre-recuperato, il turno dell'assistente chiama uno strumento per base di conoscenza 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 già recuperato, 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=[
        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, 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 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 blocchi immagine o documento possono unirsi a essi nello stesso modo.

I risultati degli strumenti sono più restrittivi: 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 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.

Controllo della cache

Aggiungi cache_control al blocco del risultato di ricerca per memorizzarlo in 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 in cache e 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)

  • Contenuto dinamico: Usala per ricerche in tempo reale e applicazioni RAG dinamiche
  • Gestione degli errori: Restituisci messaggi appropriati quando le ricerche falliscono
  • Limiti dei risultati: Restituisci solo i risultati più rilevanti per evitare l'overflow del contesto

Per la ricerca di primo livello (Metodo 2)

  • Contenuto pre-recuperato: Usala quando disponi già dei risultati di ricerca
  • Elaborazione in batch: Ideale per elaborare più risultati di ricerca contemporaneamente
  • Test: Ottima per testare il comportamento delle citazioni con contenuti noti

Best practice generali

  1. 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
  2. Mantieni la coerenza:

    • Usa formati di origine coerenti in tutta la tua applicazione
    • Assicurati che i titoli riflettano accuratamente il contenuto
    • Mantieni la formattazione coerente
  3. Gestisci gli errori con eleganza: quando una ricerca fallisce o non restituisce nulla, restituisci un semplice blocco di testo che descrive l'esito (ad esempio, {"type": "text", "text": "No results found."}) invece di sollevare un errore: Claude spiega il risultato vuoto all'utente e la conversazione continua.

Limitazioni

  • I blocchi di contenuto dei risultati di ricerca sono disponibili su Claude API, Amazon Bedrock e Google Cloud.
  • All'interno dei risultati di ricerca è supportato solo contenuto testuale (niente immagini o altri media).
  • I blocchi search_result possono comparire solo nei messaggi utente (inclusi quelli 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.

Prossimi passi

Rileva e gestisci i motivi di arresto per rifiuto nelle risposte in streaming, e riprova le richieste rifiutate su un modello di fallback.

Fonda 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.

Dai a Claude accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico opzionale e controlli sui domini.

Consulta la documentazione completa della Messages API, inclusi i tipi di blocchi di contenuto.

Memorizza in cache i risultati di ricerca con cache_control per ridurre costi e latenza nelle richieste ripetute.

Was this page helpful?