Come connettere un chatbot AI a un'API REST senza codice
Trasforma una richiesta in linguaggio naturale in un connettore REST revisionato, quindi verifica che l'email corretta mostri solo i campi approvati mentre un'email errata non mostri nulla.
Quando si connette un chatbot a un'API REST, la validazione e l'output con privilegi minimi sono importanti tanto quanto l'invio corretto della richiesta.
Un API Connector fornisce all'assistente uno strumento ben definito per leggere o modificare dati in tempo reale. È diverso dalla knowledge base: le fonti indicizzate rispondono da contenuti elaborati in precedenza, mentre un connettore invia una nuova richiesta HTTP solo quando la richiesta dell'utente corrisponde alle istruzioni del suo strumento.
Questo esempio introduttivo usa l'API di test pubblica JSONPlaceholder senza credenziali segrete. Una richiesta GET per l'ID cliente 1 restituisce un oggetto JSON fittizio. Prima che l'assistente possa mostrare i campi approvati di nome, azienda e sito web, una regola di validazione confronta l'email del visitatore con il valore `email` presente in tale risposta.
Testerai entrambi i flussi in conversazioni separate. L'email in minuscolo `sincere@april.biz` deve corrispondere al valore di risposta `Sincere@april.biz` e mostrare esattamente Leanne Graham, Romaguera-Crona e hildegard.org. `wrong@example.com` deve restituire solo il messaggio neutro di mancata corrispondenza e non deve mostrare alcun dato del cliente.
L'approccio no-code non elimina le responsabilità di sicurezza. L'assistente AI crea una prima bozza; spetta comunque a te verificare HTTPS, autenticazione, accesso con privilegi minimi, tipi di campo, segnaposto, percorsi di risposta, messaggi di errore e comportamento sia in caso di autorizzazione sia di blocco prima dell'attivazione.
Player a due clic conforme alla privacy
Come connettere un chatbot AI a un'API REST (senza codice)
Connetti il chatbot a un'API REST senza codice: mappa campi tipizzati, valida le risposte, definisci i limiti e controlla le chiamate permesse.
Il player di YouTube rimane bloccato finché non selezioni Riproduci. Il caricamento connette il browser a YouTube e potrebbe trasferire dati tecnici a Google.
Apri direttamente su YouTubeCosa otterrai alla fine
- Un modello logico chiaro sul funzionamento di un connettore API
- Un connettore generato dall'AI e verificato campo per campo
- Input obbligatori di ID utente ed email con validazione della risposta non sensibile alle maiuscole
- Una reale ricerca su JSONPlaceholder completata con tre dati approvati esplicitamente
- Un tentativo separato con email errata bloccato senza alcuna perdita di dati del cliente
- Una checklist riutilizzabile per sicurezza, errori e pulizia in produzione
Prima di iniziare
- Piano Standard o superiore, oppure una prova attiva con accesso agli API Connector
- Un assistente non di produzione dedicato a questo tutorial
- Un endpoint HTTPS documentato con la relativa risposta JSON prevista
- Record di test non sensibili; non utilizzare mai dati reali di clienti nel tutorial
- Un risultato atteso per la richiesta consentita e uno per la richiesta bloccata
- Per la successiva messa in produzione: credenziali API dedicate con privilegi minimi archiviate all'esterno dei prompt
Raccogli, chiama, valida, rispondi
Il prompt dello strumento stabilisce quando il connettore può essere utilizzato. I campi tipizzati indicano all'assistente quali valori raccogliere dal visitatore. Segnaposto come `{user_id}` mappano tali valori nell'URL, negli header o nel corpo della richiesta. La validazione della risposta confronta quindi il valore del visitatore con un percorso JSON prima che il modello riceva il risultato consentito.
In questo esempio, l'assistente raccoglie `user_id` ed `email`, richiede `/users/1`, legge il JSON e applica `email equals response.email, ignoring case`. Una regola non soddisfatta restituisce solo il messaggio di errore configurato; i dati di risposta non devono raggiungere il visitatore.
L'API, non il modello linguistico, deve rimanere l'autorità per l'autenticazione e le autorizzazioni. Utilizza la validazione del connettore come protezione aggiuntiva a livello di presentazione, non in sostituzione dell'autorizzazione API vera e propria. Il connettore deve ricevere solo l'ambito di lettura o scrittura strettamente necessario per questo singolo compito.
01–07
Configura passo dopo passo
Apri gli API Connector e definisci un singolo compito specifico
Inizia sull'assistente non di produzione designato prima di esaminare o aggiungere uno strumento attivo.
Apri l'area di lavoro dell'assistente e seleziona API Connectors. Questo è l'elenco degli strumenti attivi assegnati esclusivamente a quell'assistente. Una scheda esistente mostra lo stato, il metodo HTTP, l'endpoint, il riepilogo del prompt e i campi richiesti al visitatore; il pulsante Add API Connector avvia una configurazione separata.
Scrivi il compito in una sola frase prima di selezionare Add: “Look up one fictional JSONPlaceholder customer after user ID and email verification.” Mantieni modifiche agli ordini, creazione di ticket o qualsiasi azione di scrittura in un altro connettore con autorizzazioni separate.
Per un primo progetto, scegli una richiesta GET di sola lettura. Le operazioni di lettura sono più facili da ispezionare e ripristinare rispetto alle azioni POST, PATCH o DELETE, ma richiedono comunque una validazione quando i dati restituiti non devono essere pubblici.
Scegli Set up with AI
Descrivi il risultato desiderato invece di trascrivere la documentazione campo per campo.
La finestra di dialogo offre Set up with AI e Set up manually. Scegli l'assistente AI quando disponi di un endpoint e di un obiettivo chiari; utilizza la configurazione manuale quando devi replicare esattamente una configurazione già approvata.
L'assistente può ricercare e compilare i campi, ma la revisione di endpoint, metodo, header, tipi di campo, validazione e prompt prima del salvataggio resta una tua responsabilità. Non incollare chiavi segrete di produzione nella chat.
Descrivi la ricerca su JSONPlaceholder e revisiona i campi generati
L'assistente AI compila una prima bozza completa e verificabile.
Richiedi `https://jsonplaceholder.typicode.com/users/{user_id}` con `user_id` obbligatorio come Number ed `email` come Email. Indica all'assistente di verificare l'email rispetto al percorso di risposta `email` senza distinzione tra maiuscole e minuscole, mostrando solo nome, `company.name` e sito web.
L'assistente verificato ha creato “JSONPlaceholder Customer Lookup”, GET, header vuoti, i due campi obbligatori e il corretto segnaposto per l'endpoint. JSONPlaceholder contiene record demo fittizi, quindi il tutorial non espone dati reali di clienti o credenziali.
Verifica la validazione e le istruzioni dello strumento
I controlli di sicurezza devono essere espliciti prima di selezionare Create.
Verifica che la validazione confronti il campo di input `email` con il percorso di risposta `email` tramite Equals (ignore case). Utilizza un messaggio neutro in caso di errore: “The email address does not match this customer profile. Please try again.”
Il prompt dello strumento deve indicare quando usare il connettore, quali campi raccogliere e quali campi della risposta possono essere mostrati. In produzione, usa credenziali dedicate di sola lettura negli header o una gestione sicura dei secret lato server, ed evita che una modifica generata dall'AI estenda le autorizzazioni senza controllo.
Crea e verifica la scheda del connettore attivo
Verifica insieme metodo, endpoint, campi e stato attivo.
Seleziona Create e torna all'elenco. La scheda attiva deve mostrare JSONPlaceholder Customer Lookup, GET, l'endpoint, il riepilogo del prompt, i campi `user_id` ed `email` e l'interruttore abilitato.
Non passare ai test in chat se la scheda è inattiva o se l'endpoint differisce dal modulo revisionato. Una configurazione salvata non garantisce ancora che la chiamata API e la regola di sicurezza funzionino correttamente.
Testa la ricerca del cliente autorizzato
Usa un record fisso e varia intenzionalmente l'uso delle maiuscole nell'email per verificare la regola di confronto selezionata.
Apri Test chatbot in una nuova anteprima e chiedi: “Look up demo customer 1. The verification email is sincere@april.biz.” La risposta dell'API contiene `Sincere@april.biz`; il valore inserito in minuscolo viene accettato perché il confronto selezionato non fa distinzione tra maiuscole e minuscole. La risposta deve restituire Leanne Graham, Romaguera-Crona e hildegard.org.
Registra l'input esatto e la risposta visibile. Questo costituisce il riferimento per i futuri test di regressione del percorso consentito. Un modello diverso potrebbe formulare il testo in modo differente, ma i tre dati autorizzati devono rimanere corretti, mentre email di risposta, username, telefono, indirizzo, coordinate, ID e JSON grezzo devono restare nascosti.
Verifica che un'email errata venga bloccata in una nuova conversazione
Il test del percorso bloccato è importante quanto il test di successo e non deve ereditare la risposta precedente.
Avvia una nuova sessione di chat per evitare che la risposta precedente su Leanne Graham rimanga nel contesto. Richiedi il cliente 1 con `wrong@example.com`. Il test è superato solo se il chatbot mostra il messaggio di mancata corrispondenza configurato e non rivela nessuno di questi valori: Leanne Graham, Sincere@april.biz, Romaguera-Crona o hildegard.org.
Questo dimostra la validazione a livello di presentazione per la demo; non trasforma JSONPlaceholder in un vero servizio di autenticazione. Un'API di produzione deve autorizzare l'accesso lato server prima di restituire dati protetti, idealmente inviando solo i campi che l'assistente è autorizzato a mostrare.
Ripeti il test di blocco dopo ogni modifica a campi, percorsi di validazione, struttura della risposta dell'endpoint, prompt o modello. Testa anche campi mancanti, tipi di input non validi, JSON non valido, timeout, 401/403, 404 e limiti di frequenza delle richieste. Disattiva immediatamente il connettore se un errore espone campi protetti.
Esempio e risultato
Guarda il test pratico e il relativo risultato
Ogni tutorial include un input definito, il risultato atteso e un riepilogo trasparente di quanto effettivamente verificato in ambiente di prova.
Esempio pratico: connettere un chatbot AI a un'API REST senza codice
Questo scenario esatto è stato completato utilizzando l'account di prova temporaneo.
Input esatto del test
Look up demo customer 1 with lowercase sincere@april.biz, then start a fresh chat and repeat with wrong@example.com.
Risultato previsto
L'email corretta mostra solo nome, azienda e sito web; l'email errata non mostra alcun record del cliente.
Cosa è stato effettivamente verificato
Il connettore reale ha restituito Leanne Graham, Romaguera-Crona e hildegard.org per l'input valido. Una sessione separata di blocco ha respinto wrong@example.com con il messaggio di validazione configurato, senza esporre alcun dato del cliente.
Consigli e suggerimenti
Rendi affidabile la configurazione
Esegui i test con esempi realistici, registra i dati di base e modifica una sola impostazione alla volta. In questo modo i miglioramenti reali risulteranno evidenti.
Usa un'identità API di sola lettura
Il chatbot non deve ricevere permessi di scrittura o eliminazione quando necessita soltanto dello stato dell'ordine.
Testa risposte con formato non corretto
Verifica timeout, campi mancanti, risposte diverse da 200 e JSON non valido in modo che i visitatori ricevano un messaggio di fallback sicuro.
Scegli un modello affidabile nell'uso degli strumenti
Confronta gli stessi prompt di autorizzazione e blocco in Model Arena. Scegli il modello più rapido ed economico che raccoglie costantemente tutti i campi, richiama il connettore una sola volta e rispetta la validazione.
Mantieni separate le sessioni di autorizzazione e di blocco
Una nuova sessione per il test di blocco garantisce che la risposta negata non riutilizzi dati del cliente presenti nel contesto della conversazione precedente.
Tratta le modifiche al connettore come modifiche al codice
Registra insieme versione dell'endpoint, prompt, campi, percorsi di validazione e risultati dei test. Richiedi una revisione prima di ampliare metodi, host o livelli di autorizzazione.
Cosa fare se qualcosa non funziona
Risoluzione dei problemi
Verifica lo stato, i permessi e i dati di test in modo sistematico prima di modificare il modello o il prompt.
Il connettore restituisce 401 o 403
Verifica l'header di autenticazione, l'ambito del token e i permessi lato API usando credenziali di test non di produzione. Non risolvere mai il problema assegnando un token con privilegi di amministratore generali.
La validazione fallisce sempre
Esamina l'effettiva risposta JSON e controlla il percorso della risposta, il tipo di valore e la modalità di confronto. I valori nidificati come `company.name` richiedono il percorso esatto.
Il chatbot espone campi non previsti
Disattiva immediatamente il connettore, limita il prompt dello strumento e la risposta API, quindi ripeti i test di blocco. Prediligi un endpoint lato server che restituisca solo i campi approvati.
L'assistente risponde a memoria invece di chiamare il connettore
Rendi il prompt dello strumento specifico riguardo all'intento e ai campi obbligatori, rimuovi connettori concorrenti dall'assistente di test e riparti da una nuova conversazione. La risposta deve riflettere la risposta API corrente, non un valore osservato in precedenza.
L'API restituisce 404 per un record mancante
Usa una risposta neutra di elemento non trovato che non confermi identificatori sensibili. Evita di effettuare nuovi tentativi con ID ipotizzati e impedisci al connettore di mostrare un risultato precedente andato a buon fine.
La richiesta va in timeout o restituisce JSON non valido
Mostra un messaggio di fallback per servizio temporaneamente non disponibile, registra il problema tecnico all'esterno della risposta per il visitatore ed evita di mostrare porzioni parziali della risposta. Effettua nuovi tentativi solo in base a criteri documentati, per evitare che una singola richiesta generi un sovraccarico di chiamate.
Pronto per un test strutturato
Controlla i log del connettore e le autorizzazioni dopo il rilascio. Aggiungi ulteriori azioni solo come connettori separati, con ambiti ben definiti e le rispettive regole di validazione.