Manual de operación de vFlow

1 Descripción general vFlow

vFlow es un módulo de conexión a sistemas de inteligencia artifical para sistemas de comunicaciones unificadas, ya sean sistemas corporativos o contact center Gracias a vFlow, las plataformas de UC dispondrán de una solución para comunicarse con sistemas IA utilizando un mismo mecanismo independientemente de la solución de inteligencia artificial que se utilice

Para proporcionar el servicio de manera completa, vFlow (en concreto el orquestador) se conectará a sistemas de inteligencia artificial (LLM) que permitirán desarrollar los agentes definidos en los orquestadores

Conceptos:

• Plataforma--> Plataforma de comunicaciones unificadas; por ejemplo Omnisuite o VIVAit Call
• Orquestador--> Plataforma agéntica de IA (por ejemplo Flowise)
• vFlowProxy--> Módulo VIVAit que conecta multiples plataformas con múltiples orquestadores
• LLM--> Modelo de lenguaje natural que usará un orquestadores
• Agente--> Cada uno de los flujos creados en vFlow; corresponde a un par plataforma/agentflow de orquestador
• Servicio--> Cada elemento de negocio en la plataforma de CU (por ejemplo VDN)

Los módulos principales de vFlow son:

• vFlowProxy: Recibe las conexiones de los sistemas de comunicaciones unificadas, y conecta con los orquestadores de Inteligencia Artificial de manera segura y adaptada al tipo de servicio; el acceso a vFlow Proxy desde las plataformas se realizará mediante:
• Programa cliente: Se utiliza en el sistema de comunicaciones unificadas (actualmente VIVAit Call y Omnsisuite) para invocar a vFlow
• API REST: Alternativa al programa cliente, vFlowProxy proporciona una API REST que facilita que cualquier plataforma pueda comunicarse mediante un procedimiento estándar y documentado
• Portal de administración vFlow: Permite visualizar las interaciones realizadas y configurar el sistema
• Orquestador de IA: Herramienta de Inteligencia Artificial que permitirá la creación de aplicaciones personalizadas (agentes)

Otros elementos relevantes serán:

• Base de datos vFlow:

• Almacena información sobre sesiones y transacciones realizadas
• Almacena información de configuración sobre vFlow
• Gestiona el RAG de las inteligencias artificiales a usar

2 Puesta en marcha de nodo vFlow

Existe un nodo vFlow en los repositorios habituales proporcionados

Para dar de alta nodo vflow en un cliente hay que:

• Configurar IP (por defecto la maquina va configurada por DHCP)
• Adaptar el firewall, para ello REVISAR el fichero /etc/firewall/vars.sh
• Certificados validos en apache
• REVISAR ficheros /etc/apache2/sites-enabled/flowise.conf y /etc/apache2/sites-enabled/vFlow.conf la variable ServerName (nombre valido de la maquina)

Accesos vFlow (se debe cambiar tras instalación):

• Usuario ssh y de SO por defecto es sat y clave a proporcionar.
• Para el portal de flowise las credenciales son usuario: vfloadmin@vflow.com clave: A proporcionar
• Para el portal de vflow las credenciales son usaurio sat y clave a proporcionar.

Accesos BBDD vFlow

• Para acceder a la base de datos desde el workbenck solo desde localhost (o tunel):
• BBDD Vlfow (admin) vflowadmin // clave a proporcionar
• BBDD Vlfow (no_admin) vflow // clave a proporcionar

Portal orquestador Flowise

ubicado en https://host.cliente.xx:4567

⚠️ ATENCION !! Los cambios en tablas de configuración de BBDD de vFlow (orquestadores, plataformas, agentes) requieren reinicio del servicio vFlowProxy

/etc/init.d/vFlowProxy.service status
/etc/init.d/vFlowProxy.service stop
/etc/init.d/vFlowProxy.service start

El fichero de configuración del demonio vFlowProxy se encuentra en /etc/MDtel/vFlowProxy.conf, si bien este fichero de configuración no se modificará habitualmente (los parámetros generales de configuración de vFlowProxy se encuentran en la BBDD de vFlow)

3 Procedimientos de respaldo y restauración

3.1 Respaldo

• Hacer backup de las bases de datosdel orquestador (flowise) y de vFlow

mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_config_$(date +%F_%H%M%S).sql
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_upsert_$(date +%F_%H%M%S).sql
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vFlow > vFlow_$(date +%F_%H%M%S).sql

• Copiar:
  • El directorio /opt/vFlow_flowise/.flowise

cp -vai /opt/vFlow_flowise/.flowise /opt/vFlow_flowise/.flowise_$(date +%F_%H%M%S)

• • El directorio /opt/vFlow_flowise/archivos

cp -vai /opt/vFlow_flowise/archivos /opt/vFlow_flowise/archivos_$(date +%F_%H%M%S)

Todos los ficheros creados pueden ser movidos al destino deseado para almacenar la copia de respaldo

3.2 Restauración

Para restaurar, será necesario

• Importar de nuevo las dos bases de datos de flowise y la base de datos de vFlow:

mysql -u root -p vflow_flowise_config < vflow_flowise_config_ULTIMAFECHA.sql
mysql -u root -p vflow_flowise_upsert < vflow_flowise_upsert_ULTIMAFECHA.sql
mysql -u root -p vFlow < vFlow_ULTIMAFECHA.sql

• Volver a poner las carpetas de /opt/vFlow_flowise/

mv -vi /opt/vFlow_flowise/.flowise_ULTIMAFECHA /opt/vFlow_flowise/.flowise
mv -vi /opt/vFlow_flowise/archivos_ULTIMAFECHA /opt/vFlow_flowise/archivos

Las ubicaciones de los archivos a resturar pueden ser diferentes

4 Gestión en vFlow

vFlow prevé la existencia de tres entornos que permita hacer una gestión segura de agentes y RAG:

• Producción
• Preproducción
• Pruebas

Para cada agente o store de RAG se podrá desplegar un entorno, dos o los tres entornos

✅ Recomendación

En la mayoría de los casos con disponer de entorno de producción y preproducción tanto para agente como para RAG será suficiente

Para realizar una gestión completa en vFlow (suponiendo tres entornos y gestión de agentes y RAG), deberemos tener

Gestión en vFlow

4.1 En orquestador (Flowise)

• 1.- Crear agente: Se crearán hasta tres agentes (pro/pre/pru) en función de los entornos deseados; es importante anotar los ID's de los agentes creados (se ven en la URL)

Creación de agente en orquestador flowise (uno por entorno)

✅ Puntos 2, 3 y 4 solo en caso de tener RAG

• 2.- Crear store : Se crearán hasta tres stores (pro/pre/pru) en función de los entornos deseados; es importante anotar los ID's de los stores creados (se ven en la URL)

Creación de store (uno por entorno)

• 3.- Crear loader : Para cada loader que se desee manejar, se creará en el orquestador y en el document store, para los entornos deseados

• Subir fichero (p.ej "ld1.txt" a /var/www.html/storages/production (o a /staging o a test si procede)

Subir fichero inicial (uno por entorno)

• Crear loader

• Tipo: API loader
• Method: get
• URL : <cde>http://127.0.0.1/storages/production/nombrefich.txt (o /staging /test) (formatos posibles txt, pdf, doc, docx)
• Splitter: Recursive character text splitter
• Comprobar con "preview chunks"
• Pulsar "process"

Creador loader en orquestador flowise

Loader creado en orquestador flowise

• 4.- Sincronizar chunks en store (para cada entorno)

• En Store, more actions / Upsert All Chunks

Upsert chunks store flowise

• Embeddings: Por ejemplo OpenAI embeddings (requiere "Credential")
• Vector Store: Qdrant

• Credential: cflow_qdrant
• URL: http://localhost:6333
• Qdrant Collection Name: vflow

• Record Manager: MySQL

• Connect credential: mysql_upsert
• Host: localhost
• Database: vflow_flowise_upsert
• Cleaun: Full

• Aplicar

• Save config
• Upsert

Sincronizado de store en flowise

La siguiente imagen muestra como quedará en el orquestador (flowise) un document store de vflow con entornos de producción, reproducción y pruebas

Document store en flowise con los tres entornos (tres document stores)

4.2 En flow

• 1.- Crear un agente: Vincularlo a los tres agentes de orquestador (pro/pre/pru) anotados anteriormente

Crear agente en vflow

✅ Puntos 2 y 3 solo en caso de tener RAG

• 2.- Crear un store: Vinculado a los stores de orquestador anotados anteriormente (pro/pre/pru)

Creacion de Store en vflow

• 3.- Crear un loader

• Loader vinculado a agente de vflow
• El sistema comprobará que el fichero ya existe en el orquestador

Pulsar "crear"

Crear loader en vflow

Store, loader y detalle de loader

5 Diagnósticos

Fichero de log, en nodo vFlowProxy, para cualquier canal

tail -f /var/log/vFlowProxy/vFlowProxy.log

Monitorizar estado del proceso vflowProxy, en nodo vFlowProxy

nc localhost 1131

 {
  "proceso": {
    "nombre": "vFlowProxy",
    "version": "00.00.01",
    "inicio_ts": 1771315153,
    "inicio_cad": "20260217 085913",
    "log_alarmas_val": 8,
    "log_alarma_ultimo_ts": 1771970401,
    "log_alarma_ultimo_ts_cad": "20260224 230001"
  },
  "diagnostico": {
    "gmp": {
      "msj_val": 1022,
      "msj_max": 1024,
      "buf_val": 1024,
      "buf_max": 1024,
      "tarea_val": 7,
      "tarea_max": 15
    },
    "tiempo": {
      "uptime": 716665,
      "uptime_dias": 8,
      "uptime_horas": 7,
      "uptime_minutos": 4,
      "uptime_segundos": 25
    },
    "wws": {
      "conexiones_val": 0,
      "conexiones_max_periodo": 0,
      "hilos_val": 4,
      "hilos_max": 4,
      "wsi_cad": "sesiones=0/200"
    }
  },
  "alarmas_nivel_max": 0,
  "alarmas": []
 }

Es relevante la monitorización de sesiones "wsi_cad": "sesiones=0/200" (usadas/máximas)

En nodo Omnisuite, para canal voz

asterisk -rv | grep <callysquare_name>

en nodo Omnisuite, para canal voz

tail -f /var/log/xcally/<agi-combined.yyyy-mm-dd.log>

en nodo Omnisuite, para cualquier canal

tail -f /var/log/xcally/<routing-combined.yyyy-mm-dd.log>

6 Pruebas desde vFlow

En /home/sat/vFlowProxy hay scripts de prueba (se configuran en el vars.sh); para usar los scripts de prueba tendremos que tener también ".ini" en vFlow

Es útil comenzar con

/home/sat/vFlowProxy/vFlowGetInfo.sh

que sin parámetros adicionales confirma el correcto estado de vFlowProxy

{
  "errorNum": 0,
  "errorStr": "OK",
  "app": "vFlowProxy",
  "version": "00.00.01",
  "sessions_opened": 0,
  "sessions_limit": 200,
  "sessions_sleep_timeout_s": 3600,
  "alarms": 8
}

7 Integración de vFlow desde Omnisuite

7.1 Descripción general

En Omnisuite, la integración con vFlow, se realiza con el programa vFlowOmnisuite, que podrá ser invocado como ejecutable (más rápido, para debian), o como Python (más universal)

/opt/omnisuite/bin/vFlowOmnisuite (OPCIÓN PREFERENTE)
/opt/omnisuite/bin/vFlowOmnisuite.py (LEGACY)

Asociado al programa existen los siguientes ficheros de configuración (.ini):

Un ".ini" de plataforma Omnisuite en vFlow --> Solo contiene uuid de la plataforma; se entrega un ".ini" a modo de ejemplo en /etc/MDtel/vflow/platform.ini

EJEMPLO ".INI" DE PLATAFORMA

[uuids]
platform=1d111530-e22d-11f0-b0f2-5254008bef96

Un ".ini" por agente en vFlow --> Solo contiene uuid del agente según su identificación en vFlow (NO en un orquestador, por ejemplo flowise); se entrega un ".ini" asociado a un agente "loop" existente en Flowise /etc/MDtel/vflow/agent_loop_01.ini

EJEMPLO ".INI" DE AGENTE

[uuids]
agent=1a3a1020-ea1d-11f0-b4a5-5254008bef96

Un ".ini" por servicio --> Configuración de cada servicio en Omnisuite; se entrega un ".ini" a modo de ejemplo en /etc/MDtel/vflow/service.ini En cada fichero de servicio configuraremos

• Donde está Vflow
• Agente
• Plataforma
• timeout_s --> Importante, es afectado por el LLM
• channel_text_type --> IMPORTANTE si el servicio es de texto que esté bien (vacio solo si el servicio es de texto, NO COMENTARLO)
• environment --> production, staging, test

EJEMPLO ".INI" DE SERVICIO

  [arch_uuids]
  agent=/etc/MDtel/vflow/agent_loop_01.ini
  platform=/etc/MDtel/vflow/platform.ini

  [vflow]
  host_port=172.25.129.242:7900
  timeout_s=20
  # channel_type=[voice|chat|email]
  channel_type=chat
  # environment=[production|staging|test]
  environment=production
  language=es

  [omnisuite]
  # channel_text_type=[chat|mail|sms|whatsup]
  channel_text_type=chat
  service_id=vflow_service_id
  service_name=vflow_service_name

La imagen siguiente muestra el esquema de relación entre orquestador/plataforma/agente/servicio en la plataforma y en vFlow

Relación orquestador-plataforma-agente-servicio

7.2 Invocación

7.2.1 Generales

7.2.1.1 Ver configuración

/opt/omnisuite/bin/vFlowOmnisuite <config_arch> configPrint

Ejemplo de respuesta

Configuration:
  agent_arch_uuid=/etc/MDtel/vflow/agent_fse_rapido.ini
  agent_uuid=3487af28-1d14-11f1-803c-525400ef204c
  platform_arch_uuid=/etc/MDtel/vflow/platform_labomsui.ini
  platform_uuid=9a54ea74-f050-11f0-bdf1-5254008bef96

  vflow_host_port=labvflow.mdnova.local
  vflow_timeout_s=50
  vflow_environment=production
  vflow_channel_type=voice
  vflow_language=es

  omnisuite_channel_text_type=chat
  omnisuite_service_id=287
  omnisuite_service_name=desarrollo
{
  "errorNum": 0,
  "errorCad": "OK"
}

7.2.1.2 Ver versión

/opt/omnisuite/bin/vFlowOmnisuite version

Ejemplo de respuesta

00.00.02

7.2.2 Para canales de texto

Para canales de texto en Omnisuite existe un único Comando de invocación "omnisuiteText"

/opt/omnisuite/bin/vFlowOmnisuite <config_arch> omnisuiteText <omnisuite_id> <omnisuite_websiteId> <omnisuite_createdAt> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email> <question>

Parámetros ( Los OPCIONALES son "" si no se envía valor):

Parámetro	Obligatoriedad	Descripción
`<config_arch>`	OBLIGATORIO	".ini" del servicio
`<omnisuite_id>`	OBLIGATORIO	Identificativo de la interacción en Omnisuite
`<omnisuite_websiteId>`	OBLIGATORIO	Identificativo del servicio en Omnisuite (ej. website id en chat)
`<omnisuite_createdAt>`	OBLIGATORIO	Creación de la interacción
`<vflow_client_id>`	OPCIONAL	Id de cliente en Omnisuite
`<vflow_client_phone_number>`	OPCIONAL	Telf de cliente en Omnisuite
`<vflow_client_email>`	OPCIONAL	Email de cliente en Omnisuite
`<question>`	OBLIGATORIO	Texto a enviar al orquestado (p. ej. Flowise)

Ejemplo de respuesta JSON

{
 "errorNum": 0,
 "errorStr": "OK",
 "session": "e926548d-fdcf-11f0-a793-525400ef204c",
 "language": "es",
 "response": "HOLA"
}

7.2.3 Para canales de voz

Para canales de voz, existen comandos para "abrir sesión", "enviar texto" y "cerrar sesión"

7.2.3.1 Abrir sesión

/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionOpen <omnisuite_UniqueId> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email>

Parámetros (Los OPCIONALES son "" si no se envía valor):

Parámetro	Requisito	Descripción
<config_arch>	OBLIGATORIO	".ini" del servicio
<omnisuite_UniqueId>	OBLIGATORIO	Unique_ID de asterisk de la llamada en Omnisuite
<vflow_client_id>	OPCIONAL	Id de cliente en Omnisuite
<vflow_client_phone_number>	OPCIONAL	Telf de cliente en Omnisuite
<vflow_client_email>	OPCIONAL	Email de cliente en Omnisuite

Ejemplo de respuesta JSON

 {
    "errorNum": 0,
    "errorStr": "OK",
    "session": "ec73df29-f08a-11f0-a8ec-525400ef204c",
    "platform_id": "146"
 }

El value correspondiente al key "session" deberá ser guardado en una variable para siguientes invocaciones

7.2.3.2 Enviar texto

/opt/omnisuite/bin/vFlowOmnisuite <config_arch> textRequest <vflow_session_uuid> <question>

Parámetros:

Parámetro	Requisito	Descripción
<config_arch>	OBLIGATORIO	".ini" del servicio
<vflow_session_uuid>	OBLIGATORIO	Variable "session" almacenada en el "sessionOpen"
<question>	OBLIGATORIO	Texto a enviar al orquestado (p. ej. Flowise) (normal, abandoned, other)

Ejemplo de respuesta JSON

 {
    "errorNum": 0,
    "errorStr": "OK",
    "session": "c6f6fad7-f6c1-11f0-a793-525400ef204c",
    "language": "ES",
    "response": "Cristóbal Colón."
 }

7.2.3.3 Cerrar sesión

/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionClose <vflow_session_uuid> <vflow_cause>

Parámetros (Los OPCIONALES son "" si no se envía valor):

Parámetro	Estado	Descripción
<config_arch>	OBLIGATORIO	".ini" del servicio
<vflow_session_uuid>	OBLIGATORIO	Variable "session" almacenada en el "sessionOpen"
<vflow_cause>	OPCIONAL	(normal, abandoned, expired, other)

Ejemplo de respuesta JSON

 {
    "errorNum": 104,
    "errorStr": "Wrong session"
 }

7.3 Ejemplos para omnisuite

7.3.1 Ejemplo de chat

/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_chat.ini" "omnisuiteText" "{{interaction.id}}" "{{account.id}}" "{{interaction.createdAt}}" "" "" "" "{{message.body}}" | jq -r '.response'

7.3.2 Ejemplo de voz

Ejemplo de flujo de Cally Square

/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_voice.ini" "sessionOpen" "{UNIQUEID}" "" "" "" |  jq -r '.session' 

salida del comando almacenado en variable "vflow_sessionopen_response" para su posterior uso en cally square

Abrir sesión en vFlow

/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "textRequest" "{vflow_sessionopen_response}" "{OPENAI_WHISPER_TRANSCRIPT}" | jq -r '.response'

la voz se ha transcrito con OpenAI, por eso se usa como parámetro {OPENAI_WHISPER_TRANSCRIPT})

Enviar texto en vFlow

 
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "sessionClose" "{{vflow_sessionopen_response}}" "normal"

Cerrar sesión en vFlow