[ blog · tutorial ]7 min read

Come aggiungere la Web Search in tempo reale a un agente OpenAI o Claude in 4 passi

Sarah ChoyPubblicato il 2 maggio 20267 min di lettura
Come aggiungere la Web Search in tempo reale a un agente OpenAI o Claude in 4 passi

Vuoi che il tuo agente fondi le risposte su informazioni aggiornate? Ti servono esattamente due cose: un'API di ricerca che restituisca snippet pronti per un LLM e una definizione di strumento che il modello possa richiamare. Questa guida fa entrambe in 4 passi.

In breve

  • Passo 1: ottieni una API key (gratis) e prova l'endpoint con curl.
  • Passo 2: scarica il tool schema OpenAI/Claude direttamente dall'API — niente JSON scritto a mano.
  • Passo 3: registra lo strumento nel tuo agente (OpenAI Assistants, Anthropic Messages, LangChain o n8n).
  • Passo 4: implementa l'handler dello strumento che chiama /api/search/web e restituisce i risultati al modello.

Perché è breve

La maggior parte dei tutorial \"aggiungi la Web Search al tuo LLM\" è lunga perché in realtà sono tutorial su un SDK di API di ricerca o su un framework di agente pesante. Questo no. Tutto il lavoro è: scegliere un endpoint, registrarlo come strumento, scrivere un handler da 5 righe.

1Ottieni una API key (gratis) e chiama l'endpoint

Registrati su apipick.com/dashboard/api-keys. I nuovi account ricevono 100 crediti gratis — nessuna carta di credito. Crea una key e prova l'endpoint:

curl -X POST https://www.apipick.com/api/search/web \
  -H "x-api-key: pk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"query": "what is retrieval augmented generation"}'

Riceverai una piccola lista ordinata di titoli, URL e snippet. Verificare che funzioni con curl fa risparmiare tempo di debugging più avanti.

2Scarica il tool schema (non scriverlo a mano)

API Pick espone tool schema pronti da incollare su GET /api/search/web/tool-schema. La risposta include sia una definizione di funzione in stile OpenAI sia una definizione di tool use di Claude.

curl https://www.apipick.com/api/search/web/tool-schema

Metti in cache il risultato — non cambia tra una chiamata e l'altra. Scrivere i function schema a mano è la fonte più comune di bug nel codice degli agenti (tipo sbagliato, campi required sbagliati, descrizione mancante).

3Registra lo strumento nel tuo agente

OpenAI Assistants

from openai import OpenAI
import requests

client = OpenAI()
schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()

assistant = client.beta.assistants.create(
    name="Research Agent",
    model="gpt-4o",
    instructions="Use web_search whenever the user asks about current events or anything that changes after your training cutoff.",
    tools=[{"type": "function", "function": schema["openai"]}],
)

Anthropic Claude

import anthropic
import requests

schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[schema["claude"]],
    messages=[{"role": "user", "content": "Summarise this week's RAG research."}],
)

LangChain

from langchain.tools import tool
import requests

@tool
def web_search(query: str) -> dict:
    """Real-time web search. Use for any question that needs current information."""
    return requests.post(
        "https://www.apipick.com/api/search/web",
        headers={"x-api-key": "pk_yourkey"},
        json={"query": query},
    ).json()

n8n

Aggiungi un nodo HTTP Request: metodo POST, URL https://www.apipick.com/api/search/web, header x-api-key: pk_yourkey, body JSON {"query": "{{ $json.query }}"}. Collegalo al tuo nodo agente o LLM Chain. Nessun SDK necessario.

4Gestisci la chiamata allo strumento

Per OpenAI Assistants, quando il run si mette in pausa con stato requires_action, esegui la ricerca e invia l'output:

import json, time, requests
from openai import OpenAI

client = OpenAI()
KEY = "pk_yourkey"

def run_with_tool(thread_id: str, assistant_id: str):
    run = client.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant_id)
    while True:
        run = client.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
        if run.status == "requires_action":
            outputs = []
            for call in run.required_action.submit_tool_outputs.tool_calls:
                if call.function.name == "web_search":
                    args = json.loads(call.function.arguments)
                    result = requests.post(
                        "https://www.apipick.com/api/search/web",
                        headers={"x-api-key": KEY},
                        json=args,
                    ).json()
                    outputs.append({"tool_call_id": call.id, "output": json.dumps(result)})
            client.beta.threads.runs.submit_tool_outputs(
                thread_id=thread_id, run_id=run.id, tool_outputs=outputs,
            )
        elif run.status in ("completed", "failed", "cancelled", "expired"):
            return run
        time.sleep(0.5)

Il loop dell'API Messages di Anthropic è simile — quando la risposta contiene un blocco tool_use, chiama l'API e poi rimanda il risultato come blocco di contenuto tool_result nel turno successivo.

Stringere il loop

  • Imposta la descrizione dello strumento dalla prospettiva del modello: \"Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.\" Non dire \"questa è un'API di Web Search\".
  • Metti in cache i risultati nel tuo handler quando la stessa query compare due volte in una sessione. I risultati della Web Search sono stabili per ~minuti; non serve pagare 15 crediti due volte nella stessa conversazione.
  • Aggiungi un filtro start_date quando la freschezza conta. \"Le notizie di questa settimana\" senza filtro per data spesso restituisce titoli dell'anno scorso.

Dove andare dopo

Una volta che il tuo agente sa cercare, il passo naturale successivo è leggere le pagine collegate. Aggiungi la URL Content Extraction API come secondo strumento — stessa autenticazione, stessa forma JSON, fino a 25 URL per chiamata. La combinazione \"search + extract\" è il più piccolo agente di research utile.

Domande frequenti

Posso usarlo con la OpenAI Responses API invece di Assistants?

Sì. Lo stesso tool schema funziona in client.responses.create() — passalo tramite tools=[{...}] esattamente come mostrato nella documentazione OpenAI. La forma dell'handler è identica: fai il parsing di tool_calls, esegui POST /api/search/web, restituisci il JSON.

Devo formattare i risultati prima di restituirli al modello?

No. POST /api/search/web restituisce titolo + URL + snippet LLM-friendly già ordinati. Restituisci il JSON grezzo come risultato dello strumento. Il modello citerà gli snippet e collegherà le URL.

Quanto costa ogni turno di agente?

Ogni chiamata di Web Search costa 15 crediti (~0,015 $ a 5 $/5.000 crediti). Un turno tipico che usa lo strumento una volta resta ben sotto un centesimo di dollaro di costo di ricerca — sono i token dell'LLM a dominare.

E se il modello non chiama mai lo strumento?

Rendi la descrizione dello strumento specifica. "Use this for any question that requires current or post-training information" funziona molto meglio di "web search". I modelli instradano verso gli strumenti di cui capiscono lo scopo.

Posso limitare i risultati a un paese o a un intervallo di date?

Sì. Passa country_code (ISO 3166-1 alpha-2) e/o start_date / end_date (YYYY-MM-DD). Aggiungili come parametri nel tuo tool schema se vuoi che li scelga il modello; oppure fissali nell'handler se il tuo agente ha un locale o un requisito di freschezza fisso.

API usate in questo articolo

Sarah Choy
Scritto da
Sarah Choy
CEO, API Pick

Sarah Choy è la CEO di API Pick. Scrive sulla creazione di API pronte per la produzione per agenti IA e flussi di lavoro con LLM.