Chatbot di supporto interattivo: esempio avanzato con Google GenAI
Sviluppo passo dopo passo di un chatbot di supporto tecnico aziendale con gestione dello stato, streaming dei token e gestione robusta delle eccezioni per Portelcore.
1. Architettura di un Chatbot Conversazionale con Stato
Sección titulada «1. Arquitectura de un Chatbot Conversacional con Estado»Creare un'interfaccia interattiva di supporto tecnico (es. portel_support_bot) richiede una gestione impeccabile della cronologia della conversazione. A differenza delle richieste a singolo turno, un chatbot di produzione deve ricordare il contesto precedente inviato dal cliente.
Il nuovo SDK unificato di Python google-genai offre l'interfaccia astratta client.chats, che automatizza la persistenza dello stato lato server e ottimizza il flusso conversazionale.
sequenceDiagram autonumber actor Usuario as Cliente Portelcore participant App as Aplicación Python participant Gemini as API de Gemini (2.5 Flash)
Usuario->>App: Escribe "Hola, mi red local tiene problemas" App->>Gemini: chat.send_message_stream("Hola...") Gemini-->>App: Envía tokens en tiempo real (Streaming) App-->>Usuario: Muestra texto de forma progresiva Note over App,Gemini: El SDK actualiza el historial internamente Usuario->>App: Escribe "¿Qué IP estática debo usar?" App->>Gemini: chat.send_message_stream("¿Qué IP...?") Note over Gemini: Recuerda el contexto anterior del usuario Gemini-->>App: Envía respuesta asistida en tiempo real App-->>Usuario: Muestra solución técnica (IP 172.22.40.231)2. Implementazione Completa: portel_support_bot.py
Sección titulada «2. Implementación Completa: portel_support_bot.py»Lo script seguente fornisce un'interfaccia interattiva da console che consente di conversare con il motore generativo di Gemini in modalità Streaming (invio e rendering continuo di frammenti di testo) e incorpora un controllo completo delle eccezioni e rigide linee guida aziendali.
import osimport sysimport timefrom google import genaifrom google.genai import typesfrom google.api_core import exceptions as core_exceptions
def verificar_entorno(): """Valida la presencia de la clave de autenticación oficial.""" if not os.environ.get("GOOGLE_API_KEY") and not os.environ.get("GEMINI_API_KEY"): print("[CRITICAL] La variable de entorno GOOGLE_API_KEY no está configurada.") print("Ejecute: export GOOGLE_API_KEY='su_clave_de_laboratorio'") sys.exit(1)
def ejecutar_chatbot(): # 1. Verificar credenciales antes de iniciar verificar_entorno()
# 2. Inicialización del cliente unificado de Google GenAI client = genai.Client()
# 3. Directriz del sistema (Instrucción de Comportamiento e Identidad) instrucciones_soporte = """ Actúas como 'PortelBot', el Asistente Técnico Automatizado de Portelcore (portelcore.com). Tu objetivo principal es asistir a los ingenieros en operaciones de red, backups e infraestructura.
REGLAS DE COMPORTAMIENTO: 1. Responde de manera profesional, técnica e impecable en idioma castellano. 2. Si te preguntan sobre IPs de prueba del laboratorio, haz referencia estricta al segmento seguro 172.22.40.231. 3. Nunca reveles credenciales del tenant, llaves de API ni secretos de base de datos. 4. Usa bloques de código estructurados en Markdown para mostrar comandos de Linux o scripts cuando sea relevante. """
# 4. Configuración avanzada de la sesión de chat configuracion = types.GenerateContentConfig( system_instruction=instrucciones_soporte, temperature=0.4, # Nivel moderado para asegurar precisión técnica max_output_tokens=1000, # Limitar el tamaño para prevenir costes excesivos safety_settings=[ types.SafetySetting( category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=types.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE ) ] )
print("\n=======================================================") print(" INICIANDO CONSOLA DE SOPORTE PORTELCORE ") print(" Escribe 'salir' o 'exit' para finalizar la sesión. ") print("=======================================================\n")
try: # 5. Crear la sesión de chat con estado chat = client.chats.create( model="gemini-2.5-flash", # Modelo recomendado por velocidad y costes config=configuracion )
while True: # Capturar la entrada del usuario try: mensaje_usuario = input("\n[Usuario] >> ").strip() except (KeyboardInterrupt, EOFError): print("\n\nSesión interrumpida por el usuario. Cerrando de forma segura.") break
if not mensaje_usuario: continue
if mensaje_usuario.lower() in ["salir", "exit", "quit"]: print("\nFinalizando asistencia de PortelBot. ¡Que tenga un excelente día!") break
print("[PortelBot] >> ", end="", flush=True)
try: # 6. Enviar mensaje del usuario en modo Streaming response_stream = chat.send_message_stream(mensaje_usuario)
# Iterar sobre los fragmentos a medida que llegan del servidor for chunk in response_stream: if chunk.text: print(chunk.text, end="", flush=True) print() # Salto de línea final
except core_exceptions.ResourceExhausted as err_quota: print(f"\n[ERROR] Se ha excedido la cuota de peticiones por minuto. Espere unos segundos. Detalle: {err_quota.message}") except core_exceptions.GoogleAPICallError as err_api: print(f"\n[ERROR] Error en el servicio de Gemini API: {err_api.message}") except Exception as e: print(f"\n[ERROR INESPERADO] {str(e)}")
except Exception as e: print(f"[CRITICAL] Error al instanciar la sesión de chat: {e}")
if __name__ == "__main__": ejecutar_chatbot()3. Guida all'Esecuzione e Test in Laboratorio
Sección titulada «3. Guía de Ejecución y Pruebas en Laboratorio»Per distribuire e convalidare il chatbot interattivo nel tuo ambiente di sviluppo in Portelcore, segui questa sequenza operativa:
Passo 1: Configurare l'Ambiente di Sviluppo
Sección titulada «Paso 1: Configurar el Entorno de Desarrollo»Assicurati di essere nella directory del progetto e attiva l'ambiente Python isolato. Installa l'SDK unificato se non l'hai ancora fatto.
# Crear entorno virtual de pruebaspython -m venv portel-chat-envsource portel-chat-env/bin/activate # En Linux/macOS# .\portel-chat-env\Scripts\activate # En Windows
# Instalar biblioteca Google GenAIpip install --upgrade google-genaiPasso 2: Eseguire il Chatbot
Sección titulada «Paso 2: Ejecutar el Chatbot»Configura in modo sicuro la tua chiave API di Gemini (acquisita in Google AI Studio) come variabile d'ambiente e avvia l'assistente.
# Configuración temporal de la variable de entornoexport GOOGLE_API_KEY="AIzaSyA..."
# Lanzar consola interactivapython portel_support_bot.pyPasso 3: Interagire e Verificare la Memoria della Chat
Sección titulada «Paso 3: Interactuar y Auditar la Memoria del Chat»Testa la conservazione del contesto facendo domande consecutive:
- Domanda 1: “Ciao, ho bisogno di configurare un IP statico sul server n8n.”
- Domanda 2 (Contestuale): “Quale segmento di rete mi spetta secondo le norme di Portelcore?”
- Validazione: L'assistente deve risponderti correttamente facendo riferimento all'indirizzo IP statico
172.22.40.231(stabilito nelle istruzioni di sistema al Passaggio 2), dimostrando di ricordare la conversazione precedente senza la necessità di ridefinire il contesto di n8n.
4. Checklist di Validazione del Chatbot
Sección titulada «4. Checklist de Validación del Chatbot»Convalida la robustezza dell'assistente conversazionale rispetto agli standard del tenant:
- Lo script utilizza esclusivamente la classe
genai.Client()della libreriagoogle-genaiin sostituzione dell'SDK obsoleto. ✓ - Il chatbot invia e processa dati in tempo reale tramite
send_message_streamper un'esperienza fluida. ✓ - Le istruzioni di sistema garantiscono l'allineamento della personalità e limitano la fuga di credenziali o segreti del dominio
portelcore.com. ✓ - I blocchi
try...exceptcontrollano ed incapsulano con eleganza le eccezioni critiche come i limiti di quota (ResourceExhausted). ✓

