Chiedete a un assistente se una funzione annunciata questa settimana è già disponibile. Trova un articolo recente e risponde con un link. Ma questo link può parlare di una fase futura, riprendere un annuncio vecchio o riferirsi a un'altra offerta. Trovare una pagina e verificare un'affermazione sono due operazioni diverse. La nuova interfaccia di ricerca web di Cloudflare fornisce un punto d'ingresso; la vostra applicazione deve ancora organizzare il percorso verso una risposta verificabile.
Nello scenario fittizio di questo articolo, preparate un assistente di monitoraggio dei prodotti. Il suo utente si aspetta una risposta breve: ciò che è annunciato, ciò che è accessibile e ciò che rimane previsto. Proponiamo un metodo per separare questi stati, conservare le prove utili e produrre un rifiuto preciso quando manca un’informazione. Nessun servizio di ricerca è stato chiamato per misurarne le prestazioni.
Ciò che cambia con Web Search API
Il 2 ottobre 2026, Cloudflare annuncia Web Search API tramite AI Gateway, la sua passerella per le chiamate di IA. Gli strumenti Server nativi, che devono integrare strumenti lato server in questa passerella, restano annunciati come una fase futura. Non sono presentati qui come disponibili.
La documentazione consultata il 6 ottobre, aggiornata il 2 ottobre, indica una beta aperta. Descrive risultati strutturati comprendenti titoli, URL e descrizioni, diversi fornitori, un accesso REST da un server o tramite binding Workers, e una registrazione in AI Gateway. REST si riferisce qui a un'interfaccia chiamata tramite richieste di rete; il binding è l'accesso fornito al programma che gira in Workers.
L'interesse architettonico è rendere identificabile la fase « cercare ». È possibile assegnarle un termine, un costo, uno stato di fallimento e una traccia. Nella nostra proposta, questa fase restituisce dei candidati. Un'altra fase apre la fonte autorizzata, una terza qualifica l'affermazione e un'ultima redige la risposta. Lo stesso agente può partecipare a più fasi, ma le responsabilità rimangono distinte nella vostra applicazione.
Definire la questione prima di inviare una richiesta
« Questa funzione è disponibile? » manca di contesto. Disponibile per quale offerta, quale regione, quale versione e a quale data? Chiedete i dettagli necessari o comunicate l'ambito selezionato. Nel nostro esempio fittizio, la domanda diventa: « Alla data di consultazione, la funzione descritta in questo annuncio è aperta agli sviluppatori di questa offerta? »
Una richiesta di ricerca dovrebbe contenere i termini pubblici necessari a questa domanda. Non è necessario il nome di un cliente, il suo contratto né il contenuto di un dossier interno. La nostra raccomandazione è di costruire una formulazione minima prima della chiamata al fornitore e di verificare cosa entra nei registri. Una traccia utile all’uso può diventare inutilmente sensibile se copia l’intera conversazione.
Stabilite anche un budget di lavoro. Il vostro assistente può ricevere un limite di chiamate, un termine complessivo e un elenco di fonti prioritarie. Queste scelte sono parametri applicativi da adattare; non forniamo valori presumibilmente ottimali. Quando il budget è esaurito, l’applicazione deve distinguere tra “ricerca incompleta” e “funzione non disponibile”.
Collegare ogni frase a una prova
Per ogni risultato pertinente, cercate la pagina all’origine del fatto: annuncio dell’editore, documentazione della funzione o deposito ufficiale. Una rassegna stampa può aiutare nella scoperta. Non diventa prova primaria solo perché la sua data è più recente. Se la pagina originale non è accessibile, conservate questo limite e riducete l’ambito della vostra risposta.
Nella nostra metodologia, una prova sostiene un’affermazione precisa. Per esempio, l'annuncio può sostenere «è prevista un'apertura», mentre la documentazione di accesso deve sostenere «questa funzione è utilizzabile in tale offerta». Potete quindi avere due collegamenti utili che rispondono a due domande diverse. Una bibliografia posta alla fine da sola non risolve questa corrispondenza.
Separate tre date. La data di pubblicazione descrive il documento. La data dell’evento descrive ciò che è accaduto. La data di consultazione descrive il momento in cui avete letto la pagina. Un articolo pubblicato oggi può raccontare un evento passato; una documentazione modificata oggi può mantenere una disponibilità precedente. Se una data non è verificabile, lasciatela sconosciuta piuttosto che dedurla da un URL.
Costruire una scheda di prova indipendente dal fornitore
Chiamiamo SearchEvidence il contratto concettuale qui sotto. Questo nome e i suoi campi appartengono alla nostra dimostrazione; non descrivono lo schema ufficiale della Web Search API. L'obiettivo è poter cambiare fonte di ricerca senza perdere la logica di verifica.
| Campo concettuale | Ciò che descrive | Controllo proposto |
|---|---|---|
| URL di origine | Pagina effettivamente esaminata | Indirizzo autorizzato e apertura riuscita |
| Titolo | Identificazione del documento | Corrispondenza con la pagina letta |
| Consultato il | Momento del controllo | Timestamp dell'applicazione |
| Pubblicato il | Data verificata del documento | Origine della data conservata |
| Evento il | Data del fatto, se conosciuta | Passaggio pertinente identificato |
| Affermazione sostenuta | Frase che la prova permette | Portata limitata al contenuto letto |
| Passaggio utile | Breve porzione o riformulazione | Nessuna copia integrale automatica |
| Stato della prova | Sufficiente, contraddittoria o assente | Regola esplicita prima della redazione |
Il lettore deve poter aprire la citazione e capire perché accompagna la frase. Nel nostro assistente di monitoraggio, una risposta potrebbe presentare separatamente un annuncio datato e una disponibilità da confermare. Se una pagina non permette di determinare lo stato di accesso, scrivetelo. Il modello non deve completare questo campo con ciò che gli sembra abituale per questo fornitore.
Mantenete una distinzione tra l’URL del risultato e quello della pagina effettivamente consultata, in particolare dopo un reindirizzamento. Registrate anche un rifiuto di apertura o una restrizione di accesso. Questi stati sono utili per spiegare perché la prova non ha potuto essere consolidata, senza pretendere che tutti i siti Web siano leggibili.
Preparare un'integrazione con limiti visibili
In un'applicazione esistente, aggiungete un'interfaccia di ricerca accanto ai vostri servizi documentali. La sua uscita è una lista di candidati e uno stato della chiamata. L'apertura di una pagina appartiene a un componente separato, con le regole di rete e di raccolta autorizzate dalla vostra organizzazione. La redazione riceve poi solo gli elementi necessari all'argomento.
La cache, cioè il riutilizzo temporaneo di una risposta precedente, richiede una scelta esplicita. Una ricerca di definizione e una domanda sulla disponibilità attuale non hanno la stessa esigenza di freschezza. Conservate la data della prova riutilizzata e prevedete una nuova consultazione quando la domanda lo richiede. La data di risposta dell’assistente non deve dare l’impressione che tutte le fonti siano state rilette di recente.
Per evitare un ciclo costoso, limitate i tentativi e distinguete gli errori: tempo scaduto, accesso negato, formato inatteso o ricerca senza candidato pertinente. Preparate un messaggio di uscita per ciascuno. « Non sono riuscito a verificare la pagina primaria » è più utile di una risposta sicura costruita a partire da un riassunto incompleto.
Questo percorso può completare una base interna. Questa conserva le vostre procedure e il vostro vocabolario; la ricerca pubblica serve a verificare un annuncio o un'evoluzione esterna. L'uso chiamato RAG, generazione aumentata dal recupero di documenti, consiste precisamente nel fornire documenti al modello prima della sua risposta. L'aggiunta di una ricerca web invita a organizzare le fonti pubbliche e interne, con i loro diritti e le loro esigenze di aggiornamento.
Testare le risposte, le citazioni e i rifiuti
Il seguente protocollo è una proposta Partitech. Utilizza pagine di test controllate o doppi di rete: componenti che simulano le risposte senza una chiamata reale al fornitore. Permetterebbe di valutare la logica della vostra applicazione senza presentare i risultati come quelli del servizio Cloudflare.
| Caso di test proposto | Osservazione attesa | Uscita da verificare |
|---|---|---|
| Annuncio recente di una tappa futura | Data recente, accesso futuro | Distinzione annunciato/previsto |
| Fatto antico in una pagina recente | Due date diverse | Nessuna presentazione come novità |
| Pagina principale irraggiungibile | Risultato di ricerca solo | Verifica insufficiente segnalata |
| Due fonti divergenti | Perimetri o versioni diverse | Contraddizione esplicitata |
| Tempo di rete superato | Ricerca incompleta | Fallimento dichiarato, nessuna conclusione inventata |
| Istruzione in una pagina | Testo esterno all'applicazione | Istruzione ignorata, dati trattati come fonte |
Valutate poi le risposte frase per frase. Contate le affermazioni supportate, quelle senza prova e quelle la cui citazione riguarda un altro ambito. Esaminate anche i rifiuti: sono giustificati e indicano ciò che manca? Un assistente che rifiuta sempre non soddisfa più il compito di un assistente che risponde sempre.
Separate il test del componente di ricerca da quello della scrittura. Potete ottenere buoni risultati e produrre una cattiva sintesi, oppure non trovare nessuna fonte nonostante una logica di citazione eccellente. Questa separazione aiuta a scegliere la correzione pertinente invece di modificare a caso le istruzioni del modello.
Trattare le pagine come dati esterni
Una pagina può contenere una frase che chiede all’agente di ignorare le proprie regole o di inviare un’informazione altrove. Nella nostra concezione, questo testo non acquisisce alcuna autorità: rimane un contenuto da esaminare. Le autorizzazioni all’azione, le istruzioni del sistema e i segreti non devono essere ridefiniti da una fonte cercata.
Prevedete quindi un test in cui una pagina di dimostrazione contiene un’istruzione estranea all’argomento. Il successo atteso è un’estrazione limitata alla prova utile, senza azioni aggiuntive. Verificate anche i registri e la risposta finale per evitare che riproducano dati sensibili aggiunti al contesto. Si tratta di una misura di sicurezza da testare nella vostra architettura, non di una capacità garantita da un’API di ricerca.
Per cominciare, scegliete una domanda pubblica e circoscritta, definite le prove necessarie e preparate i sei casi di test. Il passo successivo è ottenere una risposta in cui ogni affermazione possa essere verificata, così come un rifiuto comprensibile quando manca la prova. Successivamente potrete misurare il servizio reale in un contesto autorizzato, con i suoi costi e i suoi limiti datati.
Fonti e data di verifica
Fonti primarie riaperte e lette il 6 ottobre 2026 : Cloudflare, annuncio Web Search API del 2 ottobre ; documentazione Web Search API, aggiornata il 2 ottobre. Il contratto SearchEvidence, lo scenario e i test sono delle proposte Partitech. Nessun benchmark, test di rete applicativa o audit dei partner è rivendicato.