Chatbot de suport interactiu: exemple avançat amb Google GenAI
Desenvolupament pas a pas d'un chatbot de suport tècnic corporatiu amb estat, streaming de tokens i gestió robusta d'excepcions per a Portelcore.
1. Arquitectura d'un chatbot conversacional amb estat
Sección titulada «1. Arquitectura de un Chatbot Conversacional con Estado»Crear una interfície interactiva de suport tècnic (p. ex., portel_support_bot) requereix una gestió impecable de l'historial de la conversa. A diferència de les sol·licituds d'un sol torn, un chatbot de producció ha de recordar el context previ enviat pel client.
El nou SDK unificat de Python google-genai ofereix la interfície abstracta client.chats, que automatitza la persistència de l'estat al costat del servidor i optimitza el flux conversacional.
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. Implementació completa: portel_support_bot.py
Sección titulada «2. Implementación Completa: portel_support_bot.py»L'escript següent proporciona una interfície interactiva en consola que permet conversar amb el motor generatiu de Gemini en mode Streaming (enviament i renderitzat continu de fragments de text) i incorpora un control integral d'excepcions i directrius corporatives estrictes.
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. Guia d'execució i proves en laboratori
Sección titulada «3. Guía de Ejecución y Pruebas en Laboratorio»Per desplegar i validar el chatbot interactiu en el teu entorn de desenvolupament a Portelcore, segueix aquesta seqüència operativa:
Pas 1: Configurar l'entorn de desenvolupament
Sección titulada «Paso 1: Configurar el Entorno de Desarrollo»Assegura't que ets al directori del projecte i activa l'entorn de Python aïllat. Instal·la l'SDK unificat si encara no ho has fet.
# 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-genaiPas 2: Executar el chatbot
Sección titulada «Paso 2: Ejecutar el Chatbot»Configura de forma segura la teva clau de l'API de Gemini (adquirida a Google AI Studio) com a variable d'entorn i llança l'assistent.
# Configuración temporal de la variable de entornoexport GOOGLE_API_KEY="AIzaSyA..."
# Lanzar consola interactivapython portel_support_bot.pyPas 3: Interactuar i auditar la memòria del xat
Sección titulada «Paso 3: Interactuar y Auditar la Memoria del Chat»Prova la retenció del context fent preguntes consecutives:
- Pregunta 1: “Hola, necessito configurar una IP estàtica al servidor de n8n.”
- Pregunta 2 (contextual): “Quin segment de xarxa em correspon segons les normes de Portelcore?”
- Validació: L'assistent ha de respondre't correctament fent referència a l'adreça IP estàtica
172.22.40.231(establerta en les instruccions del sistema al Pas 2), demostrant que recorda la conversa prèvia sense necessitat de tornar a definir el context de n8n.
4. Llista de control de validació del chatbot
Sección titulada «4. Checklist de Validación del Chatbot»Valida la robustesa de l'assistent conversacional contra els estàndards del tenant:
- L'script utilitza exclusivament la classe
genai.Client()de la bibliotecagoogle-genaien substitució de l'SDK obsolet. ✓ - El chatbot envia i processa dades en temps real mitjançant
send_message_streamper a una experiència fluida. ✓ - Les instruccions del sistema garanteixen l'alineament de la personalitat i restringeixen la fuga de credencials o secrets del domini
portelcore.com. ✓ - Els blocs
try...exceptcontrolen i encapsulen amb elegància excepcions crítiques com els límits de quota (ResourceExhausted). ✓

