Como criar um Chatbot Streamlit em 10 minutos

1. Dar-lhe instruções

No estúdio, navegaremos para Início na barra lateral esquerda.

Deverá ver a secção Instruções no centro da página. Clique nela para adicionar ou modificar as instruções em texto simples.

Isto dá ao nosso bot diretivas, personalidade e guardrails. Usando linguagem simples, pode orientar o seu bot de forma bastante eficaz para o comportamento desejado. Faça-o parecer mais humano, e 

2. Construir o fluxo

É aqui que residem os aspetos essenciais da personalidade do bot: acesso a informações específicas, passos rígidos, execução de código, etc.

Não subestime o poder da simplicidade. Um único nó autónomo rivaliza com a funcionalidade dos agentes de raciocínio. Eu tenho um ligado à minha Base de Dados de Conhecimento (KB).

3. Adicionar a base de conhecimentos

Se as instruções são sobre vibrações, a KB é sobre factos concretos. No meu caso, os factos em questão são os vinhos no conjunto de dados Wine Reviews, uma lista de vinhos, descrições e preços. Vou tratar isto como um inventário de vinhos de facto para o nosso bot Sommelier-ize.

Clico em Tables (Tabelas ) no painel esquerdo e carrego em New Table (Nova tabela) no canto superior esquerdo da página e dou-lhe um nome descritivo. 

Clique nas elipses verticais (⋮) no canto superior direito e prima Importar.

Arraste o seu .csv para o modal que aparece e siga os passos no ecrã.

Para tornar a tabela acessível ao seu bot, navegue até Bases de Conhecimento na barra lateral esquerda.

Clique no pequeno ícone de tabela verde e selecione a fonte relevante. Clique em Adicionar tabelas.

Certifique-se de que o seu fluxo tem acesso à base de dados de conhecimento e está pronto para começar.

1. Adicione as suas credenciais

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,
       }

Pode adicionar o seu ID da API Chat a um ficheiro .env - ajuda na depuração, mas não é estritamente necessário. Lidaremos com a ID da API e a chave de usuário quando criarmos o aplicativo Streamlit.

Eu mantenho BASE_URI e CABEÇALHOS numa constants.py ficheiro, para a desarrumação.

# constants.py

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

2. Criar os métodos 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")

Como mencionado, quase todos estes mapeiam para um ponto final na API. Estou apenas a envolvê-los numa classe.

3. Criar um ouvinte SSE

Esta é a extensão do hackerismo. Para ouvir as actualizações da conversa e fazer um loop num front-end Streamlit, o cliente precisa de um método para ouvir - e produzir - eventos enviados pelo servidor do nosso 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"]}

Esta função recebe o conversation_id (que será acedido programaticamente dentro da aplicação) e produz os dados de entrada à medida que estes acontecem.

1. Adaptar o código padrão

Em teoria, é possível pôr a aplicação a funcionar com alterações mínimas ao boilerplate no exemplo do 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}
               )

Estamos a ler variáveis secretas aqui. Portanto, crie um arquivo .streamlit/secrets.toml e coloque suas variáveis dentro dele:

CHAT_API_ID = "SEU_API_ID"
USER_KEY = "SUA_CHAVE_DE_UTILIZADOR"

O trabalho pesado está a ser feito dentro:

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}
               )

em que o cliente se agarra aos elementos de conversação para entregar e receber mensagens.

Isto funciona, mas não é o ideal por algumas razões:

• Tem de ter criado uma nova conversa separadamente.
• As mensagens antigas serão formatadas de forma diferente das novas, uma vez que não têm a designação de função (utilizador ou assistente).
• Não é possível alternar as conversas.

2. Criar conversas de forma dinâmica

Começando do zero, crio automaticamente uma nova conversa ou abro a mais 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"]

Note que modifiquei as chaves secretas para poder armazenar vários utilizadores. Você vai querer modificar seu .streamlit/secrets.toml para refletir isso:

[[utilizadores]]
chave = "sua_chave_de_utilizador"

Pode repetir este bloco as vezes que quiser, armazenando os utilizadores como uma matriz de tabelas.

3. Permitir que os utilizadores criem e alternem entre conversas

Tal como o título indica, isto cria um menu pendente na parte superior com um botão que lhe permite escolher a sua conversa.

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. Atribuir a função correta às mensagens anteriores

Resolveremos o problema de formatação acima, atribuindo a função de utilizador ou assistente a cada uma das mensagens anteriores:

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})

Isto faz com que o nosso código esteja em conformidade com a estrutura que o Streamlit espera.

5. Adicionar a lógica de envio de mensagens

É mais ou menos a mesma coisa que antes, adaptada à nova estrutura.

# 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. Criar um utilizador

A lógica está pronta, mas é necessário criar um utilizador para executar a aplicação. Optei por adicionar isto separadamente para simular a experiência de subscrição de um serviço. Felizmente para si, também escrevi um 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)

Desde que tenha o seu ID da API Chat , pode executar:

python criar_utilizador.py -nome SEU_NOME -id ALGUM_ID_DO_UTILIZADOR -id_api_do_chat SEU_ID_API_DO_CHAT

Isto irá tratar da criação do utilizador e adicioná-lo ao seu ficheiro de segredos.

Porque é que eu escolheria o Streamlit em vez de outras estruturas de front-end para criar um chatbot?

Escolheria o Streamlit para construir um chatbot se quisesse uma solução rápida, baseada em Python, que lhe permitisse criar rapidamente protótipos de aplicações interactivas sem necessitar de conhecimentos de front-end, uma vez que lida com elementos de IU como componentes de chat e gestão de estados com o mínimo de código.

Um chatbot Streamlit é adequado para utilização na produção ou apenas para protótipos?

Um chatbot Streamlit é ótimo para protótipos e ferramentas internas, mas para aplicações de produção viradas para o público com tráfego intenso ou estilo avançado, pode precisar de camadas adicionais como proxies inversos, reforço de segurança e possivelmente uma estrutura de front-end mais robusta para lidar com a escala.

Quão personalizável é o aspeto e a sensação de um chatbot criado com o Streamlit?

Embora o Streamlit permita ajustar o estilo básico, como cores, tipos de letra e disposição, é menos flexível do que as estruturas Web tradicionais; para designs verdadeiramente personalizados, teria de incorporar HTML/CSS ou JavaScript personalizados, o que pode ser feito, mas acrescenta complexidade em comparação com a utilização dos widgets incorporados no Streamlit.

Posso integrar um chatbot Streamlit num sítio Web existente ou tem de funcionar de forma autónoma?

Um chatbot Streamlit é normalmente executado como uma aplicação Web autónoma no seu próprio URL, mas pode ser incorporado num Web site existente através de um iframe, embora isto exija um estilo de manuseamento e considerações de segurança para tornar a experiência incorporada perfeita para os utilizadores.

Quanto custa implementar um chatbot Streamlit para utilização pública?

A implementação de um chatbot Streamlit pode ser gratuita se hospedado localmente ou no Streamlit Community Cloud para aplicativos menores, mas para uso público em escala, os custos variam de cerca de US $ 5 a US $ 50 por mês em plataformas de nuvem como Heroku, AWS ou DigitalOcean, dependendo dos requisitos de tráfego e tempo de atividade.