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-schemaMetti 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_datequando 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 è la CEO di API Pick. Scrive sulla creazione di API pronte per la produzione per agenti IA e flussi di lavoro con LLM.