6 errori comuni nell'integrazione di API di web scraping e ricerca web per agenti AI

Te lo dipingo, perché l'hai vissuto anche tu. Martedì pomeriggio, sala riunioni: il tuo agente AI dà spettacolo, chiedi i prezzi dei concorrenti, lui cerca sul web, apre le pagine, ti consegna una tabella pulita. Il cliente applaude, il progetto è approvato. Due settimane dopo, in produzione, lo stesso agente risponde a singhiozzo: a volte trova tutto, a volte si blocca in silenzio, e la fattura del provider cresce più in fretta del caffè che offri al team.

Ti anticipo la diagnosi, perché nella maggior parte dei casi è sempre la stessa: il problema non è l'intelligenza dell'agente, è il modo in cui gli hai cucito intorno le API di ricerca web e di scraping. E gli errori, quando si passa dal demo al mondo reale, si riducono quasi sempre a sei: nessun fallback tra provider, chiamate duplicate senza idempotenza, spesa senza un tetto per query, tre API separate dove ne basterebbe una, selettori CSS fragili e nessun monitoraggio di latenza, errori e costi. Vediamoli uno per uno, con calma, come si raccontano i guai davanti a un caffè.

Un solo provider, zero vie di fuga

L'agente ha una cosa da fare, prendere dati dal web, e per farla chiama sempre la stessa API di scraping. Poi un giorno il sito target banna gli indirizzi del provider, cosa che succede, è il gioco del gatto e del topo, oppure la chiamata va in timeout sotto carico. E lì il tuo agente rivela di che pasta è fatto: se ha un solo provider, può solo rincorrere lo stesso muro, ritentare la chiamata che già fallisce, o arrendersi con un errore in mano.

Ti suona familiare? È l'equivalente di avere un unico fornitore per la materia prima più critica: il giorno che il suo camion si guasta, si ferma tutta la produzione, e tu al telefono a scusarti coi clienti.

Il fallback non è un lusso da aggiungere "più avanti, quando scala". È una decisione del primo giorno: un secondo provider sul percorso critico, un cambio automatico quando il primo risponde male, e una pausa di respiro tra i tentativi invece di martellare, che spesso peggiora il blocco. Due provider con IP e comportamenti diversi significano quasi sempre che, quando uno è chiuso fuori, l'altro passa. E un timeout, in un agente ben fatto, è un bivio, "provo l'altra strada?", non una riga da loggare e dimenticare.

Soldi che evaporano: chiamate doppie e nessun freno

Il secondo e il terzo errore vanno a braccetto, perché riguardano entrambi il portafoglio.

Prima le chiamate duplicate senza idempotenza. Durante una ricerca, due sotto-task del tuo agente hanno entrambi bisogno di "prezzi pannelli solari 2026". Oppure una chiamata va in timeout, lui riprova, e la prima in realtà era arrivata a destinazione. Se non esiste una chiave che dica "questa richiesta l'ho già fatta", paghi due volte lo stesso dato. E c'è di peggio: due chiamate a pochi minuti di distanza restituiscono due fotografie leggermente diverse della stessa pagina. L'agente mescola i numeri delle due istantanee, l'utente nota la contraddizione, e la fiducia, quella sì, non la ricompri con nessun credito.

Poi la spesa senza controllo. Basta un prompt ambizioso e una logica di deep research troppo zelante: una domanda semplice si gonfia in decine di ricerche e centinaia di pagine scaricate, e tu lo scopri solo a fine mese, leggendo la fattura con il fiato corto. È come consegnare la carta di credito al factotum appena assunto dicendogli "compra quello che serve", senza un tetto: prima o poi la parola "serve" diventa generosa.

Il rimedio si racconta in una frase: una chiave univoca per ogni richiesta, così le ripetizioni si riconoscono e non si ripagano; una cache per le ricerche identiche; e un budget cap per query, oltre il quale l'agente si ferma e risponde con quello che ha. Meglio una risposta onesta e incompleta che una fattura a sorpresa.

Tre API, tre manuali, un solo agente

Quarto errore, quello architetturale. La ricerca web la prendi da un provider, lo scraping da un altro, la deep research da un terzo. Tre chiavi, tre cruscotti di fatturazione, tre formati di errore, tre SDK da tenere aggiornate. Funziona, certo. Ma prova a guardare il codice del tuo agente con onestà: quanta parte è ragionamento e quanta è nastro adesivo per tenere insieme le tubature?

Il costo non si vede subito. Si vede quando un provider cambia il formato di risposta e passi un pomeriggio a fare debugging su tre integrazioni per capire chi si è rotto. Si vede quando vuoi aggiungere un fallback e ti accorgi di doverlo scrivere tre volte, con tre logiche diverse. Si vede quando l'agente "sembra lento" e tu non sai se incolpare la ricerca, lo scraping o la ricerca profonda.

L'alternativa è un endpoint unico che copra search, scraping e deep research, con i provider multipli nascosti sotto il tappeto. Non a caso è lo stesso ragionamento che abbiamo fatto in NestD quando abbiamo disegnato NestD API: portare le tre funzioni su un solo endpoint, con i fallback già cuciti dentro, così chi costruisce agenti lavora sull'agente e non sul nastro adesivo.

Il selettore CSS che muore a ogni restyling

Quinto errore, il mio preferito da raccontare perché è di una prevedibilità disarmante. Per estrarre il prezzo da un sito, qualcuno scrive un selettore affilato come un rasoio, div.product > span.price > em, e funziona. Poi il sito si rinnova, che è il suo mestiere, il prezzo finisce dentro un nuovo componente, e il tuo selettore muore.

Fin qui il danno è fastidioso ma visibile: l'estrattore non trova nulla, te ne accorgi. Il caso davvero cattivo è un altro: il selettore smette di puntare al prezzo e inizia a puntare a qualcos'altro, le spese di spedizione, il prezzo di un prodotto correlato, un testo che gli somiglia. L'agente riceve un numero, lo prende per oro colato, e lo mette nel report che leggerà il tuo cliente.

Un selettore CSS è come dare indicazioni per un negozio dicendo "terza porta a destra dopo il bar": perfette finché il bar non chiude. La gerarchia giusta è un'altra: prima i dati strutturati che il sito pubblica apposta per le macchine (JSON-LD, Open Graph), poi un'estrazione che legge la pagina come la leggerebbe una persona, e il selettore CSS come ultima spiaggia. Sempre accompagnato da una domanda di controllo: questo valore assomiglia davvero a un prezzo? È coerente col resto della pagina?

A luci spente: nessuno guarda latenza, errori e spesa

Sesto errore, il più silenzioso: nessun monitoraggio. Così scopri i problemi dall'email arrabbiata di un cliente, settimane dopo. Senza numeri non puoi distinguere "l'agente è rallentato" da "il provider è peggiorato", né capire se quel piccolo picco di errori è un ban, un limite di traffico o un sito che ha cambiato vestito. E non puoi presentarti dal fornitore dicendo "secondo me sei peggiorato" senza uno straccio di dato: ti ascoltano, ma non ti prendono sul serio.

La buona notizia è che ti servono tre numeri, non un reparto di analisi:

• la latenza media, dalla domanda dell'utente alla risposta completa;
• il tasso di chiamate fallite o bloccate, per capire se il problema è tuo o del mondo là fuori;
• il costo medio per risposta, quello che il tuo commercialista vorrebbe sempre sapere.

Misurali per una settimana, prima di cambiare qualsiasi cosa: il colpevole salta fuori quasi sempre da solo, e spesso non è quello che sospettavi.

Il lieto fine è che sono tutti errori di integrazione, non di intelligenza: si sistemano senza toccare il cuore del tuo agente. E se ti sei riconosciuto in due o tre di questi sei, tranquillo, significa solo che stai costruendo qualcosa di vero, non che hai sbagliato mestiere.

Le domande che mi fate più spesso

Qual è l'errore più comune nell'integrazione di API di web scraping? Il mancato fallback: l'agente si ferma al primo ban o al primo timeout. Fai in modo che ogni chiamata critica possa cambiare provider al volo, e progettalo dal primo giorno, non dopo la prima emergenza.

Come evito chiamate duplicate e costi doppi? Assegna una chiave univoca a ogni richiesta, così le ripetizioni si riconoscono e non si ripagano, e affianca una cache per le ricerche identiche. Poi metti un tetto di spesa per query: risposte oneste, fatture prevedibili.

CSS o estrazione intelligente: cosa conviene? Entrambe, ma in quest'ordine: dati strutturati quando il sito li offre, estrazione che legge la pagina come una persona quando non ci sono, selettori CSS solo come ultima spiaggia. E valida sempre il risultato: un valore che non assomiglia a un prezzo non è un prezzo.

Quali tre cose dovrei monitorare da subito? Latenza media dalla domanda alla risposta, tasso di chiamate fallite o bannate, costo medio per risposta. Bastano questi tre numeri per capire da dove vengono i rallentamenti e dove finiscono i soldi.

Serve davvero un endpoint unico, o posso gestire più API? Per un prototipo, più API vanno benissimo. Ma quando l'agente va in produzione, il costo della colla diventa dominante: un endpoint unico per search, scraping e deep research semplifica fallback, fatturazione e monitoraggio, e ti ridà tempo per lavorare sull'agente.