Diseño de flujos
El estándar completo vive en el skill diseno-de-flujos (.claude/skills/diseno-de-flujos/,
copiado a .cursor/skills/ y .agents/skills/), y lo aplican Claude, Cursor y, en versión corta, el
asistente de flujos del editor (su prompt y el catálogo shared/src/flows/node-catalog.ts). Esta página
es el resumen para personas.
Antes de construir: elegir la arquitectura
Presenta 2 o 3 opciones con nodos, llamadas a la IA por mensaje y estabilidad, y que decida quien pide el bot. Con varios servicios, el patrón recomendado es:
- un menú con una lista fija de servicios;
- un
switchsobreseleccion_idque manda a un nodo IA por servicio, con un prompt corto que solo conoce su servicio (el enrutamiento por menú no gasta IA); - los servicios simples, como dar un enlace o avisar, como nodos fijos, sin IA.
Las herramientas de la IA no pueden llamar APIs, cambiar variables ni enrutar: cada API es un nodo
api_call y cada aviso a terceros un send_message.
Lo que rompe un bot en producción
| Trampa | Qué pasa | Cómo se evita |
|---|---|---|
| Botón de más de 20 caracteres o fila de más de 24 (un emoji cuenta 2+) | WhatsApp rechaza el mensaje entero | Textos fijos. El validador lo marca como error; las opciones que arma la IA van por send_reply_buttons / send_list |
extract_data con un campo que vuelve vacío | Conserva el valor del turno anterior | Centinela ("N/D") o vaciar antes |
| API caída con los valores por defecto | 3 intentos × 15 s por llamada | api_timeout_ms ~10000 y retry_attempts 1, más un tope por turno |
| IA que repite una consulta fallida | Minutos de espera | Tope determinista por turno (contador + switch) |
| Aviso sin cuenta de email, o en TEST sin lease | Sale por error, sin log | Asistente Email del bot; tarjeta Canales de prueba → Asignar |
| Aviso por WhatsApp a quien no escribió en 24 h | Meta lo rechaza | Correo, o una plantilla aprobada |
| API de terceros que filtra por IP | Postman funciona, el servidor no | curl desde el servidor y pedir la autorización de la IP |
Entregar y diagnosticar
- Probar el flujo contra el motor real con un modelo falso (arnés en
referencias/prueba-de-flujo.mddel skill) antes de sembrarlo. - Sembrarlo por SQL con respaldo y vuelta atrás (
referencias/sembrar-flujo.md), sin contraseñas. - Si "se queda" o "no avisa":
referencias/diagnostico.sql, que leebot_turnsybot_node_runs(cómo terminó cada turno y qué rama tomó cada nodo), y la línea[bot-turn]de los logs. Ver también Bots y LangGraph.