Search Results come knowledge base

In questa lezione esploreremo l'uso dei “Search Results” non soltanto come semplici risposte a interrogazioni, ma come una vera e propria base di conoscenza integrata per Claude. Per “Search Results come knowledge base” intendiamo quell’approccio in cui i risultati di ricerca non sono solo restituiti, ma vengono presentati in forma strutturata affinché il modello possa citarli in modo naturale, preciso e affidabile, come se stessimo consultando un’enciclopedia interna.
Questa capacità è particolarmente utile nelle applicazioni di tipo RAG, ossia Retrieval-Augmented Generation, dove Claude attinge a informazioni esterne ma le gestisce come se fossero parte del suo contesto interno. Risultati di ricerca strutturati permettono citazioni autentiche, attributi chiari delle fonti e coerenza nel formato delle risposte

Metodi di utilizzo

Quando si costruiscono applicazioni basate su Claude che devono integrare contenuti esterni o knowledge base, la documentazione ufficiale propone due strategie principali per gestire i risultati di ricerca: il Metodo 1, in cui i risultati vengono ottenuti dinamicamente tramite strumenti personalizzati (ideale per applicazioni RAG in tempo reale), e il Metodo 2, in cui i risultati vengono invece passati direttamente come contenuto di input (più adatto a test, prototipi o casi in cui i dati sono già disponibili). Entrambi i metodi permettono a Claude di generare risposte corredate da citazioni, ma differiscono per grado di flessibilità, complessità e contesto d’uso.

Schema di un “search_result”

Qualunque sia il metodo adoperato e che vedremo meglio di seguito, quello che dobbiamo sapere è che i risultati di ricerca, quando vengono utilizzati come knowledge base, devono rispettare uno schema strutturato ben definito. Ogni risultato è tenuto a seguire una forma standardizzata che possiamo rappresentare nel modo seguente:

{
  "type": "search_result",
  "source": "https://example.com/article",
  "title": "Article Title",
  "content": [
    {
      "type": "text",
      "text": "Il contenuto effettivo del risultato di ricerca..."
    }
  ],
  "citations": {
    "enabled": true
  }
}

“type” è sempre "search_result"; “source” è l’URL o identificatore della fonte; “title” è un titolo descrittivo; “content” è un array di blocchi di testo (text blocks) con almeno un elemento; “citations” è facoltativo ma, se presente, gestisce l’abilitazione delle citazioni.

Metodo 1: Search results da tool calls

In questo approccio, i risultati di ricerca provengono direttamente da strumenti personalizzati, tipicamente tool che abbiamo definito o integrato nel nostro sistema, e vengono restituiti dinamicamente durante l’esecuzione. Claude può usarli in tempo reale per creare risposte arricchite con citazioni (RAG dinamico).

Workflow:

1. Definiamo un tool (es. search_knowledge_base) con nome, descrizione e schema di input.
2. Claude decide di usare il tool in risposta a una domanda.

3. Il tool esegue la ricerca (ad esempio nella nostra knowledge base) e restituisce risultanze strutturate come array di blocchi SearchResultBlockParam, con campi come source, title, content (testo) e citations.enabled.

4. Claude riceve il risultato e genera la risposta con citazioni automatiche basate su quei risultati.

Vantaggi:

• Altamente dinamico: utile per integrare ricerche real-time.

• RAG efficace: Claude può costruire risposte con citazioni raffinate.

• Integrazione personalizzata: ideale per le nostre knowledge base interne o tool dedicati.

Definire un tool in Python

Quando impostiamo un tool custom, per esempio un “knowledge_base_search”, possiamo restituire risultati strutturati in grado di alimentare Claude in tempo reale. In Python potremmo definire un tool così:

knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Cerca nella knowledge base aziendale",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Query di ricerca"}
        },
        "required": ["query"]
    }
}
def search_knowledge_base(query):
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/guide-config",
            title="Guida alla Configurazione",
            content=[
                TextBlockParam(type="text", text="Per configurare, accedere a Impostazioni > Configurazione. Il timeout di default è 30 s..."),
            ],
            citations={"enabled": True}
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshoot",
            title="Guida alla Risoluzione",
            content=[TextBlockParam(type="text", text="Se si verificano errori di timeout, verificare la latenza di rete e i valori di timeout.")],
            citations={"enabled": True}
        )
    ]

Se forniamo questo tool insieme alla richiesta dell’utente, lasciamo a Claude la decisione se utilizzarlo o meno. Nel caso in cui Claude lo impieghi, il nostro codice restituisce i risultati nel formato strutturato previsto, permettendo a Claude di integrarli nelle risposte con citazioni precise e coerenti. Una richiesta di questo tipo potrebbe essere così composta:

# Invio del messaggio a Claude con il tool
response = client.messages.create(
    model="claude-2",
    messages=[
        {
            "role": "user",
            "content": "Come posso configurare il timeout delle richieste?"
        }
    ],
    tools=[knowledge_base_tool]
)

Metodo 2: Search results come top-level content

Questo metodo prevede l’inclusione diretta di risultati di ricerca precostruiti, ovvero già recuperati o memorizzati, all’interno del messaggio che inviamo a Claude. Possiamo usarlo nei flussi di test, per contenuti in cache o per integrazioni con infrastrutture di ricerca esterne.

Workflow:

1. Pre-fetchiamo i risultati della ricerca (es. da un motore esterno).
2. Li includiamo manualmente nel messaggio che inviamo a Claude, strutturati usando lo schema di search_result.
3. Abilitiamo citations.enabled: true per permettere a Claude di generare risposte citando correttamente queste fonti.

Vantaggi:

• Ottimo per pre-elaborazione: utile se i risultati sono già disponibili (cache, test automatizzati).
• Perfetto in fase di sviluppo o test: ci consente di controllare i dati senza chiamate dinamiche.
• Citazioni naturali: Claude risponde utilizzando le citazioni presenti.

Inviare a Claude dei risultati di ricerca

Con questo metodo, quindi, possiamo fornire a Claude i risultati già pre-recuperati direttamente nel contenuto della richiesta, senza usare tool dinamici. Questo è utile per test o per contenuti già disponibili nello scenario d'uso.

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)
client = Anthropic()
# Provide search results directly in the user message
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    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.model_dump_json(indent=2))

Commento al codice

Il codice mostra come inviare a Claude dei risultati di ricerca direttamente all’interno del messaggio dell’utente, trattandoli come una knowledge base strutturata. Inizialmente importiamo le classi necessarie (Anthropic, MessageParam, TextBlockParam, SearchResultBlockParam) e creiamo un’istanza del client che ci permette di interagire con il modello.

Definiamo poi i messaggi da inviare: in particolare, due blocchi SearchResultBlockParam contengono informazioni prelevate da fonti esterne, con source e title che identificano la fonte e content che include i blocchi di testo veri e propri; abilitiamo inoltre le citazioni con citations={"enabled": True} in modo che Claude possa riferirsi correttamente alle fonti.

Dopo questi blocchi di ricerca inseriamo la domanda dell’utente tramite un TextBlockParam, consentendo a Claude di leggere prima i dati strutturati e poi di rispondere alla richiesta basandosi su di essi. Infine, inviamo il tutto tramite client.messages.create(), specificando il modello e il limite di token, e stampiamo la risposta in formato JSON leggibile che conterrà il testo generato da Claude eventualmente corredato dalle citazioni dei blocchi di ricerca.

Conclusione

L'’uso dei “Search Results” come knowledge base consente di integrare informazioni esterne in Claude in modo strutturato, permettendo al modello di generare risposte accurate e corredate di citazioni precise. Attraverso il Metodo 1, basato su tool dinamici, possiamo ottenere risultati in tempo reale dalle nostre knowledge base o da sistemi esterni, mentre il Metodo 2, che utilizza contenuti pre-recuperati inclusi direttamente nei messaggi, è ideale per test, prototipi o scenari in cui i dati sono già disponibili.

In entrambi i casi è fondamentale rispettare lo schema standard dei blocchi search_result, definendo chiaramente fonte, titolo, contenuto e abilitando le citazioni, in modo che Claude possa consultare questi dati come una vera e propria enciclopedia interna e rispondere alle domande dell’utente in modo coerente e affidabile.