Tutorial Botpress: crea e distribuisci chatbot AI

Le aziende stanno correndo ad automatizzare assistenza clienti, qualificazione dei lead e flussi di lavoro interni con agenti AI. La tecnologia ora funziona abbastanza bene da essere utile, ma creare chatbot da zero significa assemblare framework come LangChain e fare debugging delle integrazioni API. Funziona e ha i suoi lati positivi, ma il ciclo di sviluppo sarà lento. 

Piattaforme come Botpress offrono un flusso di lavoro diverso. Hai strumenti visivi per progettare i flussi di conversazione. I modelli di AI sottostanti possono essere gli stessi, ma l'infrastruttura per creare, testare e distribuire è già pronta.

In questo articolo ti guiderò nella creazione di agenti AI con Botpress. Imparerai l'architettura della piattaforma, costruirai il tuo primo bot, lo collegherai a servizi reali e lo distribuirai in produzione. Condividerò anche alcune tecniche e best practice che ho imparato lavorando con la piattaforma, così puoi risparmiare tempo.

Che cos'è Botpress?

Botpress è una piattaforma per creare agenti AI che dialogano con gli utenti, attivano azioni in base a ciò che viene detto e si connettono a strumenti come Shopify, Google Sheets o alle tue REST API. Tra i concorrenti ci sono Dialogflow, Rasa, Microsoft Bot Framework e Amazon Lex.

Panoramica della piattaforma

Botpress offre sia un ambiente di sviluppo visivo (Botpress Studio) sia il controllo programmatico tramite API. L'interfaccia visiva consente ai membri del team non tecnici di progettare i flussi di conversazione, mentre gli sviluppatori possono scrivere codice. Alcune piattaforme come Rasa sono code-first, il che può essere più lineare se sei uno sviluppatore solista a tuo agio con YAML e Python.

Con Botpress definisci cosa deve fare il tuo bot (istruzioni e workflow), ciò che sa (knowledge base e tabelle) e quali azioni può compiere (integrazioni e codice personalizzato). La piattaforma gestisce l'infrastruttura: hosting, scaling e orchestrazione.

L'architettura e i livelli di Botpress. Immagine dell'autore

Rispetto alla creazione da zero con framework come LangChain, Botpress fornisce componenti pronti per la produzione. Rispetto alle piattaforme puramente no-code, ti dà la possibilità di scrivere vero codice quando gli strumenti visivi predefiniti non bastano

Chi usa Botpress?

La piattaforma serve tutti, dagli sviluppatori solisti che costruiscono il loro primo chatbot alle aziende che distribuiscono agenti su più canali. I casi d'uso comuni includono automazione del supporto clienti, qualificazione dei lead, prenotazione appuntamenti e sistemi di help desk interni.

Secondo una customer story di Botpress, Ruby Labs ha riportato un tasso di risoluzione del 98% dopo l'adozione della soluzione. Queste cifre provengono da case study del fornitore e vanno interpretate nel contesto.

Configurare Botpress

Ora ti mostro come configurare Botpress, cioè come impostare la CLI e l'SDK di Botpress per un flusso di lavoro "bot-as-code".

Installazione

Per iniziare, ti serviranno:

• Node.js versione 18 o superiore (consigliata LTS)

• Gestore pacchetti: npm, pnpm o yarn

• Un editor di codice. VS Code o Cursor sono fortemente consigliati per il supporto TypeScript

Per installare, segui questi passaggi:

1. Apri il terminale o il prompt dei comandi

2. Installa la CLI di Botpress globalmente usando npm:

npm install -g @botpress/cliOfferto da

3. Verifica l'installazione controllando la versione:

bp --versionOfferto da

Consiglio di eseguire Node.js e la CLI di Botpress all'interno di WSL2 (Windows Subsystem for Linux) per evitare i comuni problemi di path e permessi su Windows.

Se ricevi un errore eseguendo bp in PowerShell, potresti dover regolare la policy di esecuzione. Avvia PowerShell come Amministratore ed esegui: Set-ExecutionPolicy RemoteSigned.

Sviluppo locale

Lo sviluppo locale ti permette di usare GitHub per il controllo versione, TypeScript per la sicurezza dei tipi e strumenti come GitHub Copilot per generare automaticamente il codice. Questo approccio tratta il tuo chatbot come qualsiasi altro progetto software.

Configurazione iniziale

Una volta installata la CLI, devi collegare l'ambiente locale al tuo account Botpress Cloud.

1. Autenticati

Accedi al tuo account per collegare la chiave della CLI.

bp loginOfferto da

Si aprirà una finestra del browser per autorizzare la CLI.

2. Inizializza un progetto 

Crea una nuova directory per il tuo bot e inizializza la struttura.

mkdir my-first-bot
cd my-first-bot
bp initOfferto da

Segui i prompt per selezionare un template TypeScript.

3. Imposta le variabili d'ambiente 

Crea un file .env nella root del progetto per archiviare chiavi sensibili (come credenziali del database o chiavi API di terze parti). Non effettuare mai il commit di questo file su Git.

4. Distribuisci per test 

Carica il tuo bot locale sul cloud per testarlo nello Studio.

bp deployOfferto da

Primi passi con Botpress Studio

Botpress Studio è dove costruisci effettivamente i tuoi bot. 

Ambiente di sviluppo visivo

Lo Studio si apre con una canvas che mostra il flusso di conversazione del tuo bot. I nodi rappresentano i passaggi della conversazione e le connessioni tra i nodi mostrano come gli utenti si muovono all'interno del bot. Clic destro ovunque sulla canvas per creare un nuovo nodo.

La barra laterale sinistra mostra workflow, flussi di sistema, variabili e schemi. La barra laterale destra visualizza l'inspector per il nodo selezionato, dove puoi configurare istruzioni e azioni collegate. Usa l'emulatore in basso per testare il bot in tempo reale.

Template Botpress

Il Botpress Hub contiene template pronti per la produzione per supporto clienti, prenotazione appuntamenti, qualificazione lead e altro. Il template Kitchen Sink dimostra concetti avanzati come il caricamento dei dati utente, l'instradamento dei workflow e il passaggio a un operatore umano. Personalizza le istruzioni, sostituisci la tua knowledge base e distribuisci.

Creare il tuo primo bot

Costruiamo un semplice bot di supporto clienti. Crea un nuovo bot e chiamalo "support-bot". Salta la procedura guidata e vai direttamente allo Studio.

Nella scheda Home (se non è visibile, collega il nodo di avvio a un nuovo nodo autonomo), aggiungi le istruzioni:

You are a helpful customer support agent. Answer questions about our products and services using the knowledge base. Be friendly, concise, and professional. If you can't answer a question, offer to connect the user with a human agent.Offerto da

Ora aggiungi una knowledge base. Clicca su Knowledge Bases nella barra laterale sinistra, poi Create Knowledge Base. Scegli Website come tipo di sorgente e inserisci l'URL del sito della tua azienda. Botpress effettuerà il crawl del sito ed estrarrà le informazioni.

Torna nella scheda Home, scorri fino a Knowledge Bases e attiva la knowledge base appena creata. Questo dà accesso a quell'informazione al tuo nodo autonomo.

Provalo nell'emulatore. Chiedi "Quali sono i vostri orari di apertura?" oppure "Come posso restituire un prodotto?" Il bot cerca nella tua knowledge base e risponde con info pertinenti.

Test di un bot di supporto clienti nell'emulatore di Botpress con risposte in tempo reale

Questo bot di base gestisce già una sorprendente quantità di supporto clienti. Risponde alle domande dal tuo sito, mantiene il contesto della conversazione e risponde in modo naturale. Lo hai costruito in circa cinque minuti.

Natural Language Understanding

Se hai costruito chatbot prima del 2023, potresti aver notato qualcosa di diverso in ciò che hai appena fatto: non hai addestrato alcun classificatore di intenti né scritto regole di estrazione di entità, come con un sistema NLU (pre-LLM). (E se sei nuovo a tutto questo, sappi solo che le piattaforme più vecchie richiedono molto lavoro di training iniziale che Botpress salta del tutto.)

Ecco cosa succede: Botpress usa modelli linguistici di grandi dimensioni per la comprensione del linguaggio naturale. Tu scrivi istruzioni che spiegano cosa deve fare il tuo bot e l'LLM gestisce riconoscimento degli intenti, estrazione delle entità e comprensione contestuale a runtime. 

Questo cambia ciò che configuri effettivamente. Entità comuni come date, orari e informazioni di contatto funzionano subito perché l'LLM comprende già comodamente questi schemi. Le entità specifiche di dominio richiedono un trattamento diverso: descrivi ciò di cui hai bisogno nelle tue istruzioni e, facoltativamente, definisci schemi. L'LLM interpreta questi requisiti allo stesso modo in cui interpreta tutto il resto.

Costruire logiche di conversazione avanzate

I bot semplici rispondono alle domande. I bot avanzati prendono decisioni e si integrano con sistemi esterni. Botpress fornisce gli strumenti per costruire entrambi, anche se direi che molti team complicano troppo le cose all'inizio. Spesso non ti serve logica di workflow finché non hai dimostrato che il semplice Q&A funziona davvero.

Architettura dei workflow

I workflow organizzano la logica del tuo bot in segmenti gestibili. Il workflow principale gestisce il flusso di conversazione primario. I sotto-workflow gestiscono attività specifiche. Possono essere, ad esempio, prenotare appuntamenti o gestire resi.

I nodi all'interno dei workflow rappresentano passaggi distinti. Un nodo standard esegue una sequenza di azioni dall'alto verso il basso. Un nodo autonomo usa l'LLM per decidere quali azioni compiere e in quale ordine. I nodi di ingresso e uscita indicano dove gli utenti entrano ed escono dai sotto-workflow.

Architettura modulare dei workflow di Botpress. Immagine dell'autore

La logica conversazionale modulare significa scomporre attività complesse in parti più piccole e riutilizzabili. Crea una volta un workflow per raccogliere le informazioni di pagamento, poi riutilizzalo in checkout, abbonamenti e donazioni. Questo riduce la duplicazione e semplifica la manutenzione.

Il pattern router indirizza gli utenti ai workflow appropriati in base alle esigenze. Dopo un saluto iniziale, classifica l'intento dell'utente e instradalo al sotto-workflow giusto. Questo mantiene ogni workflow focalizzato su un singolo compito.

Best practice di conversation design

Il salto di qualità nella comprensione del linguaggio è reale, ma non riparerà un bot strutturato male. Servono comunque flussi di conversazione chiari e un design intenzionale. La vera differenza è che progetti a un livello più alto definendo cosa deve fare il bot invece di addestrarlo a riconoscere frasi specifiche.

Inizia con un saluto chiaro che imposti le aspettative. Progetta prima il percorso ideale, poi aggiungi la gestione degli errori. Mantieni i nodi autonomi focalizzati su un singolo compito concettuale. Usa passaggi di conferma per azioni importanti come i pagamenti. Mappa il percorso utente prima di costruire i workflow per identificare i punti decisionali e le informazioni richieste.

Ho anche letto che troppi prompt del tipo "sei sicuro?" condizionano gli utenti a cliccare avanti senza elaborare ciò che leggono. "Quando ogni azione richiede una conferma, nessuna conferma è efficace" è probabilmente una buona euristica. Riserva le conferme per operazioni davvero irreversibili: pagamenti, eliminazione account, perdita di dati.

Automazione dei workflow

Oltre alle basi trattate qui, Botpress supporta hook per l'automazione del ciclo di vita (esecuzione di codice all'avvio delle conversazioni, all'invio dei messaggi, ecc.) e workflow pianificati per attività ricorrenti come promemoria degli appuntamenti. Sono strumenti potenti, ma è anche qui che la complessità cresce rapidamente.

Integrazioni ed ecosistema di plugin

I bot Botpress diventano potenti quando si connettono a servizi esterni. Il Botpress Hub fornisce integrazioni predefinite per gli strumenti più comuni e puoi creare integrazioni personalizzate per sistemi proprietari.

Integrazioni predefinite

L'Hub include integrazioni per piattaforme di messaggistica (WhatsApp, Slack, Microsoft Teams, Telegram), CRM (HubSpot, Salesforce), strumenti di produttività (Google Calendar, Google Drive, SharePoint) e processori di pagamento (Stripe). Se devi connetterti a un servizio popolare, probabilmente esiste già un'integrazione disponibile.

Installare un'integrazione aggiunge nuove schede al tuo vassoio delle carte. Ad esempio, un'integrazione CRM fornisce schede per creare contatti, aggiornare deal e cercare record. Trascina queste schede nei tuoi workflow per connettere il bot.

La configurazione avviene nelle impostazioni dell'integrazione. Fornisci le credenziali API, selezioni quali dati accedere e mappi le variabili del bot ai campi esterni. L'integrazione gestisce autenticazione, rate limiting e ripristino dagli errori.

Integrazioni personalizzate

Per sistemi proprietari o requisiti unici, crea integrazioni personalizzate usando l'SDK di integrazione. Definisci l'interfaccia, implementa la logica di connessione e gestisci l'autenticazione. L'SDK fornisce helper per i flussi OAuth e la gestione dei webhook. Testa in locale con le utility incluse prima del deploy. Archivia le credenziali in variabili di configurazione, valida tutti gli input e implementa una corretta gestione degli errori.

Modelli di prezzo e opzioni di deployment

Il pricing di Botpress è strutturato sull'uso dell'AI piuttosto che su costi per messaggio o conversazione. Che sia costoso dipende dal tuo volume e caso d'uso. Il semplice bot di supporto clienti che abbiamo costruito prima—che risponde alle domande da una knowledge base—effettua una o due chiamate LLM per messaggio dell'utente e costa molto poco, il che non sorprende visto che lo abbiamo costruito in fretta ed è solo un esempio. 

Un bot più complesso che cerca anche nel tuo CRM, controlla l'inventario e calcola i costi di spedizione effettua ulteriori chiamate LLM per elaborare quei dati, aumentando proporzionalmente i costi AI. La piattaforma trasferisce i costi AI alle tariffe del provider senza ricarichi, quindi la spesa effettiva dipende da quante chiamate LLM richiede ogni conversazione e da quale modello scegli.

Struttura dei prezzi

Botpress offre più piani di abbonamento con diverse funzionalità e casi d'uso.

Il bot per ristoranti che ho costruito prima usava il tier gratuito. Il modello pay-as-you-go ti permette di sperimentare senza impegno mensile e inizi a pagare solo quando il tuo bot gestisce davvero conversazioni.

Deployment e scaling

Botpress scala automaticamente all'aumentare del traffico, gestendo 10 o 10.000 conversazioni in modo coerente. Gli add-on estendono le funzionalità con storage aggiuntivo, limiti aumentati e integrazioni premium. Le funzionalità Enterprise includono SSO, audit log, controllo degli accessi basato sui ruoli e supporto dedicato.

Community e supporto

La documentazione ufficiale include esempi di codice, video tutorial e materiale di riferimento. 

Il server Discord di Botpress conta oltre 30.000 membri che fanno domande, condividono bot e imparano da altri sviluppatori. Il team di Botpress partecipa attivamente. Le discussioni su GitHub offrono spazio per richieste di funzionalità e segnalazioni di bug. Troverai anche template creati dalla community che coprono casi d'uso comuni, così non devi sempre partire da zero.

Conclusione

Il bot per ristoranti che abbiamo costruito è semplice, ma lo stesso approccio funziona per progetti più complessi. L'editor visuale dei workflow e il sistema di integrazione scalano bene sia che tu stia costruendo un semplice bot FAQ sia qualcosa di più sofisticato.

La chiave è partire in piccolo. Crea un bot che faccia bene una cosa, distribuiscilo, impara dall'uso reale ed espandi da lì. Non cercare di automatizzare tutto in una volta. Concentrati sull'attività che offrirà il maggior valore con la minore complessità.

Per sviluppare le tue competenze in AI e chatbot, dai un'occhiata al nostro corso Building Chatbots in Python e al percorso ChatGPT Fundamentals. Per tecniche di prompt engineering che migliorano le risposte del tuo bot, vedi Understanding Prompt Engineering. Per automazione dei workflow e agenti AI oltre i chatbot, esplora il tutorial n8n: A Guide With Practical Examples e il code-along Building Your First AI Agent with n8n.