Come creare un chatbot Streamlit in 10 minuti

Per quanto ne so, Streamlit è il modo più veloce per creare una web-app personalizzabile. Se vuoi costruire un chatbot AI e distribuirlo sul tuo front-end, non riesco a pensare a un’opzione migliore.

L’unico limite è la libreria di elementi chat: è piuttosto specifica per l’API di OpenAI e il client Python

Ed è fantastico: bastano poche righe di codice per interagire con alcune delle tecnologie più prestigiose disponibili, il che è, beh… fantastico.

Ma non è tutto.

E se volessi avere un maggiore controllo sul tuo bot? Ad esempio, potresti desiderare un flusso di lavoro a più passaggi o la generazione aumentata dal recupero (RAG). Questi livelli aggiuntivi di funzionalità di solito comportano la gestione di librerie con varie dipendenze.

O forse no?

In questo tutorial costruirò un client chatbot ospitato su Streamlit. Ti mostrerò un’interfaccia per chatbot rapidi e altamente personalizzabili. Poi imparerai come integrare il chatbot usando un client Python in stile OpenAI creato su misura.

Se stai prototipando, dipendenze e tecnicismi non dovrebbero frenarti.

E, per chi vuole prototipare rapidamente, se vuoi saltare il tutorial e iniziare subito a sperimentare, il codice è su GitHub.

Via alle bombe 💣

Passo 1: Costruisci la logica del chatbot

Che si tratti di automatizzare flussi di lavoro o di un chatbot per la prenotazione di appuntamenti, qui le possibilità sono davvero infinite.

Ti invito a esplorare la vasta gamma di casi d'uso dei chatbot GenAI se cerchi ispirazione. Per semplicità, tornerò a parlarti della mia ormai (spero) famosa sommelier, Winona.

Il nostro bot sofisticato e utile può essere realizzato in pochi passaggi. Sarò breve, ma ci sono molti tutorial lunghi e molto utili che puoi consultare.

1. Dai istruzioni

Nello studio, andremo su Home nella barra laterale a sinistra.

Dovresti vedere la sezione Istruzioni in primo piano. Cliccaci sopra per aggiungere o modificare le istruzioni in testo semplice.

Questo fornisce al nostro bot direttive, personalità e limiti. Usando un linguaggio semplice, puoi guidare il bot in modo efficace verso il comportamento desiderato. Rendilo più umano e

2. Crea il Flow

Qui si trovano gli elementi fondamentali della personalità del bot: accesso a informazioni specifiche, passaggi rigidi, esecuzione di codice, ecc.

Non sottovalutare la potenza della semplicità. Un singolo nodo autonomo rivaleggia con le funzionalità degli agenti di ragionamento. Ne ho uno collegato alla mia Knowledge Base (KB).

3. Aggiungi la Knowledge Base

Se le istruzioni riguardano il tono, la KB riguarda i fatti concreti. Nel mio caso, i fatti sono i vini presenti nel dataset Wine Reviews, una lista di vini, descrizioni e prezzi. Lo tratterò come un inventario di vini di fatto per il nostro bot Sommelier.

Cliccherò su Tabelle nel pannello a sinistra, poi su Nuova Tabella in alto a sinistra nella pagina, e le darò un nome descrittivo.

Clicca sui tre puntini verticali (⋮) in alto a destra e seleziona Importa.

Trascina il tuo .csv nella finestra che si apre e segui i passaggi a schermo.

Per rendere la tabella accessibile al tuo bot, vai su Knowledge Bases nella barra laterale a sinistra.

Clicca sulla piccola icona della tabella verde e seleziona la fonte rilevante. Clicca su Aggiungi tabelle.

Assicurati che il tuo flow abbia accesso alla Knowledge Base e sei a posto.

Passo 2: Aggiungi l’integrazione Chat API

Il punto di contatto tra il bot e il nostro client locale è la Chat API. Per aggiungerla al nostro bot, scorro su Canali di comunicazione e clicco su … Altro.

Dai un'occhiata alle integrazioni se vuoi. Noi cerchiamo Chat. Ho dovuto scorrere un po' per trovarla.

Clicca sull’integrazione e premi Installa integrazione nella finestra che si apre.

Una volta installato, vedrai l’ID Chat API alla fine dell’URL del webhook. Ti servirà in seguito.

Passaggio 3: Scrivi il client Python

La Chat API espone diversi endpoint per eseguire operazioni CRUD su utenti, conversazioni e messaggi. Come promesso, li integrerò in un client Python che può sostituire un client OpenAI.

1. Aggiungi le tue credenziali

class BotpressClient:
   def __init__(self, api_id=None, user_key=None):
       self.api_id = api_id or os.getenv("CHAT_API_ID")
       self.user_key = user_key or os.getenv("USER_KEY")
       self.base_url = f"{BASE_URI}/{self.api_id}"
       self.headers = {
           **HEADERS,
           "x-user-key": self.user_key,
       }

Se vuoi, puoi aggiungere il tuo Chat API ID in un file .env– aiuta nel debug, ma non è strettamente necessario. Gestiremo l’API ID e la chiave utente quando costruiremo l’app Streamlit.

Tengo BASE_URI e HEADERS in un file separato constants.py, per mantenere ordine.

# constants.py

BASE_URI = "https://chat.botpress.cloud"
HEADERS = {
   "accept": "application/json",
   "Content-Type": "application/json",
}

2. Crea i metodi Request

   def _request(self, method, path, json=None):
       url = f"{self.base_url}{path}"
       try:
           response = requests.request(method, url, headers=self.headers, json=json)
           response.raise_for_status()
           return response.json()
       except requests.HTTPError:
           return response.status_code, response.text


   # --- Core API Methods ---


   def get_user(self):
       return self._request("GET", "/users/me")


   def create_user(self, name, id):
       user_data = {"name": name, "id": id}
       return self._request("POST", "/users", json=user_data)


   def set_user_key(self, key):
       self.user_key = key
       self.headers["x-user-key"] = key


   def create_and_set_user(self, name, id):
       new_user = self.create_user(name, id)
       self.set_user_key(new_user["key"])


   def create_conversation(self):
       return self._request("POST", "/conversations", json={"body": {}})


   def list_conversations(self):
       return self._request("GET", "/conversations")


   def get_conversation(self, conversation_id):
       return self._request("GET", f"/conversations/{conversation_id}")


   def create_message(self, message, conversation_id):
       payload = {
           "payload": {"type": "text", "text": message},
           "conversationId": conversation_id,
       }
       return self._request("POST", "/messages", json=payload)


   def list_messages(self, conversation_id):
       return self._request("GET", f"/conversations/{conversation_id}/messages")

Come accennato, quasi tutte queste funzioni corrispondono a un endpoint dell'API. Le sto solo racchiudendo in una classe.

3. Crea un listener SSE

Questo è il massimo dell’hack. Per ascoltare gli aggiornamenti della conversazione e collegarsi a un front-end Streamlit, il client ha bisogno di un metodo per ascoltare—e restituire—eventi inviati dal server dal nostro bot.

 def listen_conversation(self, conversation_id):
       url = f"{self.base_url}/conversations/{conversation_id}/listen"
       for event in sseclient.SSEClient(url, headers=self.headers):
           print(event.data)
           if event.data == "ping":
               continue
           data = json.loads(event.data)["data"]
	    yield {"id": data["id"], "text": data["payload"]["text"]}

Questa funzione prende l’id della conversazione (che verrà gestito a livello di codice nell’app) e restituisce i dati in arrivo man mano che si verificano.

Passaggio 4: crea l’app Streamlit

Con tutto pronto, è il momento di costruire il chatbot. Seguo la guida di Streamlit su come creare un’app di chat LLM– con alcune funzionalità aggiuntive.

1. Adatta il codice di base

In teoria, puoi far funzionare l’app con modifiche minime al boilerplate dell’esempio Streamlit.

# app.py


from client import BotpressClient
import streamlit as st
from constants import CONVERSATION_ID


st.title("Botpress Front-end for Streamlit")


client = BotpressClient(
   api_id=st.secrets["CHAT_API_ID"], user_key=st.secrets["USER_KEY"]
)


if "messages" not in st.session_state:
   messages = client.list_messages(CONVERSATION_ID)
   next_token = messages["meta"]["nextToken"]
   st.session_state.messages = messages["messages"][::-1]


for message in st.session_state.messages:
   with st.chat_message(message["userId"]):
       st.markdown(message["payload"]["text"])


if prompt := st.chat_input("*wine*-d it up"):
   st.session_state.messages.append({"role": "user", "content": prompt})


   with st.chat_message("user"):
       st.markdown(prompt)


   client.create_message(prompt, conversation_id=CONVERSATION_ID)
  
   with st.chat_message("assistant"):
response_box = st.empty()
       last_rendered = ""
	
       for message in client.listen_conversation(CONVERSATION_ID):


           message_id = message["id"]
           message_text = message["text"]


           if message_id != last_rendered:
               last_rendered = message_id
               response_box.markdown(message_text)
               st.session_state.messages.append(
                   {"role": "assistant", "content": message_text}
               )

Qui stiamo leggendo variabili segrete. Quindi crea un file .streamlit/secrets.toml e inserisci le tue variabili al suo interno:

CHAT_API_ID = ”YOUR_API_ID”
USER_KEY = ”YOUR_USER_KEY”

Il grosso del lavoro avviene in:

with st.chat_message("assistant"):
response_box = st.empty()
       last_rendered = ""
	
       for message in client.listen_conversation(CONVERSATION_ID):


           message_id = message["id"]
           message_text = message["text"]


           if message_id != last_rendered:
               last_rendered = message_id
               response_box.markdown(message_text)
               st.session_state.messages.append(
                   {"role": "assistant", "content": message_text}
               )

dove il cliente si aggancia agli elementi della chat per inviare e ricevere messaggi.

Funziona, ma non è l’ideale per alcuni motivi:

• Devi aver creato separatamente una nuova conversazione.
• I vecchi messaggi saranno formattati in modo diverso rispetto ai nuovi, perché non hanno la designazione del ruolo (utente o assistente).
• Non puoi passare da una conversazione all’altra.

2. Crea conversazioni in modo dinamico

Partendo da zero, creerò automaticamente una nuova conversazione o aprirò quella più recente:

# app.py


from client import BotpressClient
import streamlit as st


st.title("Botpress Front-end for Streamlit")


client = BotpressClient(
   api_id=st.secrets["CHAT_API_ID"], user_key=st.secrets["users"][0]["key"]
)


# user info
user = client.get_user()
user_id = user["user"]["id"]


conversations = client.list_conversations()["conversations"]
conversation_ids = [conv["id"] for conv in conversations]




# conversation
def create_conversation():
   res = client.create_conversation()
   print(f"Created new conversation: {res}")
   conversation_id = res["conversation"]["id"]
   st.session_state.active_conversation = conversation_id
   st.session_state.messages = []
   st.rerun()




if not conversations:
   create_conversation()


if "active_conversation" not in st.session_state:
   st.session_state["active_conversation"] = conversations[0]["id"]

Nota che ho modificato le chiavi segrete per poter memorizzare più utenti. Dovrai aggiornare il tuo file .streamlit/secrets.toml di conseguenza:

[[users]]
key = "your_user_key"

Puoi ripetere questo blocco tutte le volte che vuoi, memorizzando gli utenti come un array di tabelle.

3. Permetti agli utenti di creare e passare da una conversazione all’altra

Come suggerisce il titolo, questo crea un menu a tendina in alto con un pulsante per scegliere la tua conversazione.

col1, col2 = st.columns([5, 1])
with col1:
   conversation_id = st.selectbox(
       "Select Conversation",
       options=[conv["id"] for conv in conversations],
       index=conversation_ids.index(st.session_state.active_conversation),
   )


with col2:
   st.markdown("<div style='height: 1.9em'></div>", unsafe_allow_html=True)
   if st.button("➕"):
       create_conversation()


selected_conversation = client.get_conversation(conversation_id)

4. Assegna il ruolo corretto ai messaggi precedenti

Risolveremo il problema di formattazione visto sopra assegnando il ruolo di utente o assistente a ciascun messaggio precedente:

if (
   "messages" not in st.session_state
   or st.session_state.get("active_conversation") != conversation_id
):
   st.session_state.active_conversation = conversation_id
   st.session_state.messages = []


   messages = client.list_messages(conversation_id)
   next_token = messages["meta"].get("nextToken")


   for message in messages["messages"][::-1]:
       role = "user" if message["userId"] == user_id else "assistant"
       text = message["payload"]["text"]
       st.session_state.messages.append({"role": role, "content": text})

Questo adegua il nostro codice alla struttura richiesta da Streamlit.

5. Aggiungi la logica di messaggistica

Questa è più o meno la stessa cosa di prima, adattata alla nuova struttura.

# display chat history
for message in st.session_state.messages:
   with st.chat_message(message["role"]):
       st.markdown(message["content"])


if prompt := st.chat_input("*wine*-d it up"):


   st.session_state.messages.append({"role": "user", "content": prompt})
   client.create_message(prompt, conversation_id=conversation_id)


   with st.chat_message("user"):
       st.markdown(prompt)


   with st.chat_message("assistant"):
       stream = client.listen_conversation(conversation_id=conversation_id)
       response = st.write_stream(stream)


   st.session_state.messages.append({"role": "assistant", "content": response})

5. Crea un utente

La logica è pronta, ma dovrai creare un utente per eseguire l’app. Ho scelto di aggiungerlo separatamente per simulare l’esperienza di iscrizione a un servizio. Per fortuna, ho anche scritto uno script:

# create_user.py


import argparse
from pathlib import Path
from client import *
from constants import *

secrets_path = Path(".streamlit") / "secrets.toml"

template = """[[users]]
key="{}"

"""

client = BotpressClient()

def create_user(name, id, add_to_secrets=True):
   res = client.create_user(name, id)
   if not add_to_secrets:
       return res

   secrets_path.touch(exist_ok=True)

   with open(secrets_path, "a") as f:
       f.write(template.format(res["user"]["id"], res["key"]))

   return res


if __name__ == "__main__":
   parser = argparse.ArgumentParser(
       description="Create a Botpress user and optionally store secrets."
   )
   parser.add_argument("--name", required=True, help="Display name of the user.")
   parser.add_argument(
       "--id", required=True, help="User ID. If omitted, one is generated by the API."
   )
   parser.add_argument("--chat_api_id", help="ID for the Botpress Chat API integration. Taken from `.env` file if not provided.")
   parser.add_argument(
       "--no-secrets",
       action="store_true",
       help="Do not append to .streamlit/secrets.toml.",
   )

   args = parser.parse_args()

   print(f"Creating user: {args.name} (ID: {args.id or 'auto-generated'})")
   result = create_user(name=args.name, id=args.id, add_to_secrets=not args.no_secrets)

   print("✅ User created:")
   print(result)

Se hai il tuo Chat API ID, puoi eseguire:

python create_user.py –name YOUR_NAME –id SOME_USER_ID –chat_api_id YOUR_CHAT_API_ID

Questo passaggio serve a creare l’utente e aggiungerlo al tuo file dei segreti.

Passaggio 5: Avvia l’applicazione

Con la tua logica pronta e l’utente creato, è il momento di testare l’applicazione. Installa le dipendenze ed esegui:

streamlit run app.py

E proprio così, vedrai il nostro bot in tutto il suo splendore.

Avvia oggi stesso un chatbot Streamlit

Se stai prototipando con Streamlit, sai che la personalizzazione non dovrebbe compromettere la praticità. I chatbot servono a risolvere problemi, non a crearne.

Botpress offre un builder visuale drag-and-drop, decine di integrazioni ufficiali e API accessibili. Così puoi costruire, iterare e distribuire su molti canali di comunicazione.

Inizia a costruire oggi. È gratis.

Domande frequenti

Perché dovrei scegliere Streamlit rispetto ad altri framework front-end per creare un chatbot?

Sceglieresti Streamlit per creare un chatbot se desideri una soluzione rapida basata su Python che ti permetta di prototipare app interattive velocemente senza bisogno di competenze front-end, poiché gestisce elementi UI come componenti di chat e gestione dello stato con poco codice.

Un chatbot Streamlit è adatto all’uso in produzione o solo per prototipi?

Un chatbot Streamlit è ottimo per prototipi e strumenti interni, ma per app pubbliche in produzione con molto traffico o esigenze di stile avanzate, potresti aver bisogno di livelli aggiuntivi come reverse proxy, rafforzamento della sicurezza e forse di un framework front-end più robusto per gestire la scalabilità.

Quanto si può personalizzare l’aspetto grafico di un chatbot creato con Streamlit?

Streamlit consente di modificare lo stile di base come colori, font e layout, ma è meno flessibile dei framework web tradizionali; per design davvero personalizzati, occorre incorporare HTML/CSS o JavaScript personalizzati, il che è possibile ma aggiunge complessità rispetto ai widget integrati di Streamlit.

Posso integrare un chatbot Streamlit in un sito web esistente o deve funzionare solo come applicazione autonoma?

Un chatbot Streamlit di solito funziona come app web autonoma su un proprio URL, ma puoi anche incorporarlo in un sito esistente tramite iframe, tenendo però conto di stile e sicurezza per offrire agli utenti un’esperienza integrata.

Quanto costa distribuire un chatbot Streamlit per l’uso pubblico?

Distribuire un chatbot Streamlit può essere gratuito se ospitato localmente o su Streamlit Community Cloud per applicazioni di piccole dimensioni, ma per l’uso pubblico su larga scala i costi variano da circa 5 a 50 USD al mese su piattaforme cloud come Heroku, AWS o DigitalOcean, a seconda del traffico e dei requisiti di disponibilità.