Risultati di ricerca

I blocchi di contenuto dei risultati di ricerca abilitano citazioni naturali con una corretta attribuzione della fonte, portando citazioni di qualità pari alla ricerca web nelle tue applicazioni personalizzate. Questa funzionalità è particolarmente potente per le applicazioni "RAG" (Retrieval-Augmented Generation, generazione aumentata dal recupero) in cui hai bisogno che Claude citi le fonti in modo accurato.

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

• Claude Opus 4.8 (claude-opus-4-8)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 5 (claude-sonnet-5)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (deprecato) (claude-opus-4-1-20250805)
• Claude Opus 4 (ritirato, tranne su Google Cloud) (claude-opus-4-20250514)
• Claude Sonnet 4 (ritirato, tranne su Bedrock e Google Cloud) (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (ritirato, tranne su Bedrock e Google Cloud) (claude-3-5-haiku-20241022)



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
• Corretta attribuzione della fonte: Ogni risultato include informazioni su fonte e titolo per un'attribuzione chiara
• Nessuna soluzione alternativa basata su documenti necessaria: Elimina la necessità di soluzioni alternative basate 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. 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 nella cache

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



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



Campi opzionali

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

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



Metodo 1: Risultati di ricerca dalle chiamate agli strumenti

Il caso d'uso più potente è restituire risultati di ricerca dai tuoi strumenti personalizzati. Questo abilita applicazioni RAG dinamiche in cui gli strumenti recuperano e restituiscono contenuti rilevanti con citazioni automatiche.



Esempio: Strumento 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 della 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},
        ),
    ]


# Crea un messaggio con lo strumento
response = client.messages.create(
    model="claude-opus-4-8",  # Works with all supported models
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(role="user", content="How do I configure the timeout settings?")
    ],
)

# Quando Claude chiama lo strumento, fornisci i risultati della ricerca
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])

    # Invia il risultato dello strumento
    final_response = client.messages.create(
        model="claude-opus-4-8",  # Works with all supported models
        max_tokens=1024,
        messages=[
            MessageParam(
                role="user", content="How do I configure the timeout settings?"
            ),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result,  # Search results go here
                    )
                ],
            ),
        ],
    )



Metodo 2: Risultati di ricerca come contenuto di primo livello

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

• Contenuti pre-recuperati dalla tua infrastruttura di ricerca
• Risultati di ricerca memorizzati nella 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-4-8",
    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)



Risposta di Claude con citazioni

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

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 del tuo risultato 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."
    }
  ]
}

Una citazione che fa riferimento al blocco dei 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 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 utilizzare sia i risultati di ricerca basati su strumenti che quelli di primo livello nella stessa conversazione:

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# Primo messaggio con risultati di ricerca di primo livello
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(
                        type="text", text="Our product helps teams collaborate..."
                    )
                ],
                citations={"enabled": True},
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information",
            ),
        ],
    )
]

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



Combinare con altri tipi di contenuto

Entrambi i metodi supportano la combinazione di risultati di ricerca con altri contenuti:

from anthropic.types import SearchResultBlockParam, TextBlockParam

# Nei risultati degli strumenti
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True},
    ),
    TextBlockParam(
        type="text", text="Additional context: This applies to version 2.0 and later."
    ),
]

# Nel contenuto di primo livello
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True},
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"},
    },
    TextBlockParam(
        type="text", text="How does the chart relate to the research findings?"
    ),
]



Controllo della cache

Aggiungi il controllo della cache per prestazioni migliori:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "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": "User Guide",
  "content": [{ "type": "text", "text": "Important documentation..." }],
  "citations": {
    "enabled": true // Enable citations for this result
  }
}

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

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



Best practice



Per la 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 l'overflow del contesto



Per la ricerca di primo livello (Metodo 2)

• Contenuto pre-recuperato: Usa quando hai già i risultati di ricerca
• Elaborazione batch: Ideale per elaborare più risultati di ricerca contemporaneamente
• Test: Ottimo per testare il comportamento delle citazioni con contenuto noto



Best practice generali

1. Struttura i risultati in modo efficace:

   • Usa URL di fonte chiari e permanenti
   • Fornisci titoli descrittivi
   • Suddividi contenuti lunghi in blocchi di testo logici per offrire a Claude confini di citazione più precisi

2. Mantieni la coerenza:

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

3. Gestisci gli errori con eleganza:

   def search_with_fallback(query):
       try:
           results = perform_search(query)
           if not results:
               return {"type": "text", "text": "No results found."}
           return format_as_search_results(results)
       except Exception as e:
           return {"type": "text", "text": f"Search error: {str(e)}"}

   



Limitazioni

• I blocchi di contenuto dei risultati di ricerca sono disponibili su Claude API, Amazon Bedrock e Google Cloud
• Solo il contenuto testuale è supportato all'interno dei risultati di ricerca (nessuna immagine o altro media)
• L'array content deve contenere almeno un blocco di testo



Passaggi successivi