I blocchi di contenuto dei risultati di ricerca sono attualmente in beta. Usa l’header beta search-results-2025-06-09 beta header per abilitare questa funzionalità.

I blocchi di contenuto dei risultati di ricerca abilitano citazioni naturali con attribuzione corretta della fonte, portando citazioni di qualità da ricerca web alle tue applicazioni personalizzate. Questa funzionalità è particolarmente potente per applicazioni RAG (Retrieval-Augmented Generation) dove hai bisogno che Claude citi le fonti accuratamente.

La funzionalità dei risultati di ricerca è disponibile sui seguenti modelli:

  • Claude 3.5 Haiku (claude-3-5-haiku-20241022)
  • Claude 3.5 Sonnet (claude-3-5-sonnet-20241022)
  • Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)

​
Vantaggi principali

  • Citazioni naturali - Ottieni la stessa qualità di citazione della ricerca web per qualsiasi contenuto
  • Integrazione flessibile - Usa nei ritorni degli strumenti per RAG dinamico o come contenuto di primo livello per dati pre-recuperati
  • Attribuzione corretta della fonte - Ogni risultato include informazioni sulla fonte e sul titolo per un’attribuzione chiara
  • Nessun workaround di documenti necessario - Elimina la necessità di workaround basati su documenti
  • Formato di citazione coerente - Corrisponde alla qualità e al formato delle citazioni della funzionalità di ricerca web di Claude

​
Come funziona

I risultati di ricerca possono essere forniti in due modi:

  1. Da chiamate di strumenti - I tuoi strumenti personalizzati restituiscono risultati di ricerca, abilitando applicazioni RAG dinamiche
  2. Come contenuto di primo livello - Fornisci risultati di ricerca direttamente nei messaggi utente per contenuto pre-recuperato o memorizzato in cache

In entrambi i casi, Claude può automaticamente citare informazioni dai risultati di ricerca con attribuzione corretta della fonte.

​
Schema dei risultati di ricerca

I risultati di ricerca utilizzano la seguente struttura:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Richiesto: URL della fonte o identificatore
  "title": "Titolo dell'Articolo",                  // Richiesto: Titolo del risultato
  "content": [ // Richiesto: Array di blocchi di testo
    {
      "type": "text",
      "text": "Il contenuto effettivo del risultato di ricerca..."
    }
  ],
  "citations": {                             // Opzionale: Configurazione delle citazioni
    "enabled": true                          // Abilita/disabilita citazioni per questo risultato
  }
}

​
Campi richiesti

CampoTipoDescrizione
typestringDeve essere "search_result"
sourcestringL’URL della fonte o identificatore per il contenuto
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 campo booleano enabled
cache_controlobjectImpostazioni di controllo della cache (es. {"type": "ephemeral"})

Ogni elemento nell’array content deve essere un blocco di testo con:

  • type: Deve essere "text"
  • text: Il contenuto di testo effettivo (stringa non vuota)

​
Metodo 1: Risultati di ricerca da chiamate di strumenti

Il caso d’uso più potente è restituire risultati di ricerca dai tuoi strumenti personalizzati. Questo abilita applicazioni RAG dinamiche dove gli strumenti recuperano e restituiscono contenuto rilevante con citazioni automatiche.

​
Esempio: Strumento di base di conoscenza

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

client = Anthropic()

# Definisci uno strumento di ricerca della base di conoscenza
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Cerca nella base di conoscenza aziendale per informazioni",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "La query di ricerca"
            }
        },
        "required": ["query"]
    }
}

# Funzione per gestire la chiamata dello strumento
def search_knowledge_base(query):
    # La tua logica di ricerca qui
    # Restituisce risultati di ricerca nel formato corretto
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Guida di Configurazione del Prodotto",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Per configurare il prodotto, naviga su Impostazioni > Configurazione. Il timeout predefinito è di 30 secondi, ma può essere regolato tra 10-120 secondi in base alle tue esigenze."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Guida alla Risoluzione dei Problemi",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Se incontri errori di timeout, controlla prima le impostazioni di configurazione. Le cause comuni includono latenza di rete e valori di timeout incorretti."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Crea un messaggio con lo strumento
response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",  # Funziona con tutti i modelli supportati
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="Come configuro le impostazioni di timeout?"
        )
    ]
)

# Quando Claude chiama lo strumento, fornisci i risultati di ricerca
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Invia il risultato dello strumento indietro
    final_response = client.beta.messages.create(
        model="claude-sonnet-4-20250514",  # Funziona con tutti i modelli supportati
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Come configuro le impostazioni di timeout?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # I risultati di ricerca vanno qui
                    )
                ]
            )
        ]
    )

​
Metodo 2: Risultati di ricerca come contenuto di primo livello

Puoi anche fornire risultati di ricerca direttamente nei messaggi utente. Questo è utile per:

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

​
Esempio: Risultati di ricerca diretti

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Fornisci risultati di ricerca direttamente nel messaggio utente
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Riferimento API - Autenticazione",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Tutte le richieste API devono includere una chiave API nell'header Authorization. Le chiavi possono essere generate dal dashboard. Limiti di velocità: 1000 richieste per ora per il livello standard, 10000 per premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Guida Introduttiva",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Per iniziare: 1) Registrati per un account, 2) Genera una chiave API dal dashboard, 3) Installa il nostro SDK usando pip install company-sdk, 4) Inizializza il client con la tua chiave API."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="Basandoti su questi risultati di ricerca, come autentico le richieste API e quali sono i limiti di velocità?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Risposta di Claude con citazioni

Indipendentemente da come vengono forniti i risultati di ricerca, Claude include automaticamente citazioni quando usa informazioni da essi:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Per autenticare le richieste API, devi includere una chiave API nell'header Authorization",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Riferimento API - Autenticazione",
          "cited_text": "Tutte le richieste API devono includere una chiave API nell'header Authorization",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Puoi generare chiavi API dal tuo dashboard",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Riferimento API - Autenticazione",
          "cited_text": "Le chiavi possono essere generate dal dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". I limiti di velocità sono 1.000 richieste per ora per il livello standard e 10.000 richieste per ora per il livello premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Riferimento API - Autenticazione",
          "cited_text": "Limiti di velocità: 1000 richieste per ora per il livello standard, 10000 per premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Campi delle citazioni

Ogni citazione include:

CampoTipoDescrizione
typestringSempre "search_result_location" per citazioni di risultati di ricerca
sourcestringLa fonte dal risultato di ricerca originale
titlestring o nullIl titolo dal risultato di ricerca originale
cited_textstringIl testo esatto che viene citato
search_result_indexintegerIndice del risultato di ricerca (basato su 0)
start_block_indexintegerPosizione iniziale nell’array content
end_block_indexintegerPosizione finale nell’array content

Nota: Il search_result_index si riferisce all’indice del blocco di contenuto del risultato di ricerca (basato su 0), indipendentemente da come sono stati forniti i risultati di ricerca (chiamata di strumento o contenuto di primo livello).

​
Blocchi di contenuto multipli

I risultati di ricerca possono contenere blocchi di testo multipli nell’array content:

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "Documentazione API",
  "content": [
    {
      "type": "text",
      "text": "Autenticazione: Tutte le richieste API richiedono una chiave API."
    },
    {
      "type": "text",
      "text": "Limiti di Velocità: L'API consente 1000 richieste per ora per chiave."
    },
    {
      "type": "text",
      "text": "Gestione degli Errori: L'API restituisce codici di stato HTTP standard."
    }
  ]
}

Claude può citare blocchi specifici usando i campi start_block_index e end_block_index.

​
Uso avanzato

​
Combinare entrambi i metodi

Puoi usare sia risultati di ricerca basati su strumenti che di primo livello nella stessa conversazione:

# Primo messaggio con risultati di ricerca di primo livello
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Panoramica del Prodotto",
                content=[
                    BetaTextBlockParam(type="text", text="Il nostro prodotto aiuta i team a collaborare...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Dimmi di questo prodotto e cerca informazioni sui prezzi"
            )
        ]
    )
]

# Claude potrebbe rispondere e chiamare uno strumento per cercare i prezzi
# Poi fornisci risultati dello strumento con più risultati di ricerca

​
Combinare con altri tipi di contenuto

Entrambi i metodi supportano la combinazione di risultati di ricerca con altro contenuto:

# Nei risultati dello strumento
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Guida Utente",
        content=[BetaTextBlockParam(type="text", text="Dettagli di configurazione...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Contesto aggiuntivo: Questo si applica alla versione 2.0 e successive."
    )
]

# Nel contenuto di primo livello
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Documento di Ricerca",
        content=[BetaTextBlockParam(type="text", text="Risultati chiave...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="Come si relaziona il grafico ai risultati della ricerca?"
    )
]

​
Controllo della cache

Aggiungi controllo della cache per prestazioni migliori:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Guida Utente",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

​
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": "Guida Utente",
  "content": [{"type": "text", "text": "Documentazione importante..."}],
  "citations": {
    "enabled": true  // Abilita citazioni per questo risultato
  }
}

Quando citations.enabled è impostato su true, Claude includerà riferimenti di citazione quando usa informazioni dal risultato di ricerca. Questo abilita:

  • Citazioni naturali per le tue applicazioni RAG personalizzate
  • Attribuzione della fonte quando si interfaccia con basi di conoscenza proprietarie
  • Citazioni di qualità da ricerca web per qualsiasi strumento personalizzato che restituisce risultati di ricerca

Se il campo citations è omesso, le citazioni sono disabilitate per impostazione predefinita.

Le citazioni sono tutto-o-niente: o tutti i risultati di ricerca in una richiesta devono avere le citazioni abilitate, o tutti devono averle disabilitate. Mescolare risultati di ricerca con impostazioni di citazione diverse risulterà in un errore. Se hai bisogno di disabilitare le citazioni per alcune fonti, devi disabilitarle per tutti i risultati di ricerca in quella richiesta.

​
Migliori pratiche

​
Per ricerca basata su strumenti (Metodo 1)

  • Contenuto dinamico: Usa 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 overflow del contesto

​
Per ricerca di primo livello (Metodo 2)

  • Contenuto pre-recuperato: Usa quando hai già risultati di ricerca
  • Elaborazione batch: Ideale per elaborare risultati di ricerca multipli in una volta
  • Test: Ottimo per testare il comportamento delle citazioni con contenuto conosciuto

​
Migliori pratiche generali

  1. Struttura i risultati efficacemente

    • Usa URL di fonte chiari e permanenti
    • Fornisci titoli descrittivi
    • Suddividi contenuto lungo in blocchi di testo logici

  2. Mantieni coerenza

    • Usa formati di fonte coerenti attraverso la tua applicazione
    • Assicurati che i titoli riflettano accuratamente il contenuto
    • Mantieni formattazione coerente

  3. Gestisci gli errori con grazia

    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "Nessun risultato trovato."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Errore di ricerca: {str(e)}"}

​
Limitazioni

  • I blocchi di contenuto dei risultati di ricerca sono disponibili solo con l’header beta
  • Solo contenuto di testo è supportato all’interno dei risultati di ricerca (nessuna immagine o altri media)
  • L’array content deve contenere almeno un blocco di testo