DUNAMIS AI STUDIO

Manual Oficial y Documentación Técnica

🏢 Volver a la Oficina

📖 Manual de Usuario y Guía Técnica

Aprende a diseñar, modelar, construir y operar Células Autonómas de Agentes de IA para cualquier empresa o departamento. Sistema 100% PHP + MySQL + JavaScript Vanilla, sin dependencias de Node.js ni Python.

01 Introducción y Filosofía del Sistema

Oficina Dunamis es una plataforma de ingeniería y despliegue de Células Autónomas de Agentes IA diseñada bajo el modelo Marca Blanca. Permite a consultores, agencias y directores de operaciones entregar a sus clientes oficinas virtuales funcionales con agentes coordinados.

💡 Principio Clave: No es un chatbot generalista. Es una célula de trabajo donde cada agente tiene un puesto específico, un rol inquebrantable, memoria persistente en base de datos y contratos estrictos de entrada (inputs) y salida (outputs).

Capacidades Principales

  • Cobertura Total de la Cadena Empresarial: No solo ventas; modela Producción, Logística, Finanzas, Recursos Humanos, Servicio Técnico y Operaciones Integrales.
  • Cálculo Dinámico de Agentes: Un Arquitecto de IA evalúa los cuellos de botella y determina la cantidad exacta de agentes (2 a 5) con justificación técnica.
  • Independencia de Stack: Funciona en cualquier servidor LAMP/WAMP estándar (XAMPP, cPanel, Hostinger) con PHP 8+ y MySQL.
  • Resiliencia Continua: Conexión dinámica con OpenRouter con failover automático ante cuotas agotadas (HTTP 402/429) y recuperación inteligente.

02 Requisitos Previos y Puesta en Marcha Local

La plataforma está instalada y lista para correr en tu servidor local XAMPP.

Ruta de Instalación

C:\xampp\htdocs\oficinadunamis\

Pasos para Iniciar

  1. Abre el panel de control de XAMPP.
  2. Inicia los servicios Apache y MySQL (ambos en verde).
  3. Abre tu navegador e ingresa a:
    http://localhost/oficinadunamis/
  4. Base de Datos Automática: El archivo api/db.php crea automáticamente la base de datos oficinadunamis y todas sus tablas si aún no existen. No necesitas importar scripts SQL a mano.

2.1 Instalación en Hosting Web (cPanel / Plesk / Cloud) mediante install.php

  1. Subir los Archivos: Sube la carpeta completa de la plataforma al directorio public_html (o a un subdominio) de tu hosting web mediante Administrador de Archivos de cPanel o cliente FTP (FileZilla).
  2. Crear Base de Datos y Usuario en tu Hosting:
    • En cPanel, ve a Bases de Datos MySQL.
    • Crea una nueva base de datos (ej: mihosting_oficina).
    • Crea un usuario de base de datos con contraseña y asígnalo a la base de datos marcando "Todos los Privilegios" (All Privileges).
  3. Ejecutar el Asistente de Instalación: Abre en tu navegador web:
    https://tudominio.com/install.php
  4. Configuración Guiada: Ingresa los datos de conexión MySQL, crea tu usuario Administrador Principal (Super Admin) y coloca la identidad de tu Marca Blanca y URL del Logo.
  5. El instalador creará las 8 tablas de la plataforma, registrará tu usuario, escribirá api/config.php y creará el candado de seguridad .installed.
  6. Favicon Automático: El logo que configures en la marca blanca se aplicará automáticamente como el favicon en la pestaña del navegador de tus clientes.

03 Configuración Inicial: API Key y Marca Blanca

3.1 Cargar tu API Key de OpenRouter

  1. En la barra superior, haz clic en el botón "🔑 OpenRouter Key".
  2. Pega tu clave en formato sk-or-v1-... (puedes obtenerla en openrouter.ai/keys).
  3. Haz clic en "Guardar Clave". La clave se guarda cifrada localmente en tu navegador (localStorage) para tus sesiones de trabajo.

3.2 Configurar tu Marca Blanca (Pestaña "⚙️ Marca Blanca")

Personaliza la plataforma con la identidad corporativa de tu agencia o empresa:

  • Nombre de la Agencia: Reemplaza el título superior (Ej: Dunamis AI Studio, Nexus Operations).
  • Eslogan o Subtítulo: Define tu propuesta de valor ante el cliente.
  • Color Primario y de Acento: Personaliza los tonos neón de la interfaz.

Haz clic en "Guardar Configuración de Marca" y los cambios se aplicarán en tiempo real y quedarán guardados en MySQL.

04 Diseñar una Oficina Virtual Paso a Paso

El constructor permite modelar en minutos una oficina virtual para cualquier negocio:

  1. Nombre del Negocio y Rubro: Ingresa la razón social o nombre comercial (ej: Calzados del Sur) y su actividad (ej: Fabricación de calzado deportivo).
  2. Departamento Corporativo: Elige cuál de las 7 áreas de la empresa deseas automatizar.
  3. Modelo de Operaciones: El selector se actualizará con los modelos industriales propios del departamento seleccionado.
  4. Sistemas y Canales: Indica qué herramientas ya utiliza el cliente (ERP, SAP, WhatsApp, Excel, etc.).
  5. Cuellos de Botella: Describe los dolores operativos reales (ej: demoras en aprobar órdenes de compra, mermas en calidad, falta de trazabilidad en despachos).
  6. Modelo de Inferencia: Selecciona el modelo con el que operará el Arquitecto o búscalo con el filtro dinámico.
  7. Haz clic en "⚡ Diagnosticar y Diseñar Oficina".
Resultado: El Arquitecto de IA evaluará la carga de trabajo y generará la propuesta con la cantidad de agentes ideal, sus puestos, contratos de datos e interconexiones departamentales.

05 Los 7 Departamentos Corporativos y Modelos Operativos

La plataforma soporta todas las áreas de la cadena de valor empresarial:

Departamento Modelos de Operación Soportados Sistemas Típicos
🏭 Producción y Calidad Make to Order (MTO), Make to Stock (MTS), Just-in-Time (JIT), Manufactura Discreta, Maquila. ERP (SAP/Odoo), MES, Sensores IoT, Planos CAD.
📦 Logística y Almacén WMS Centralizado, Cross-Docking, Dropshipping, Ruteo Última Milla, Compras JIT. WMS, GPS de Flota, Lectoras de Códigos, Excel.
💰 Finanzas y Facturación Facturación Recurrente, Cobranza por Hitos, Conciliación Diaria, Auditoría de Gastos. Sistema Contable, Plataforma Bancaria, AFIP/SRI, ERP.
👥 Recursos Humanos Reclutamiento y Filtrado, Turnos Rotativos y Fichaje, Onboarding, Mesa de Ayuda Interna. Portales de Empleo, Biométrico, Correo, WhatsApp.
🛍️ Comercial y Ventas Venta Consultiva B2B, Retail Minorista B2C, E-Commerce D2C, Licitaciones Públicas. CRM (HubSpot/Salesforce), WhatsApp, Catálogos PDF.
🔧 Soporte y Mantenimiento Mantenimiento Predictivo/Preventivo (TPM/GMAO), Mesa N1/N2, Garantías y Taller. Zendesk, Freshdesk, GMAO, WhatsApp Técnico.
🌐 Operaciones Integrales Cadena de Valor End-to-End: de Insumos a Fabricación, Entrega y Cobranza. ERP Integral, Business Intelligence, Correo, Slack.

06 Catálogo Oficial de OpenRouter (470+ Modelos)

A diferencia de sistemas rígidos con 3 modelos fijos, Oficina Dunamis sincroniza en tiempo real el catálogo completo de OpenRouter:

  • Modelos Gratuitos (Free): Modelos listados con cuota cero para pruebas y operaciones económicas (ej: inclusionai/ling-3.2-flash:free, baidu/ernie-5.5-flash-preview:free).
  • Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus.
  • Google: Gemini 2.0 Flash, Gemini 1.5 Pro, Gemini 4.
  • OpenAI: GPT-4o, GPT-4o Mini, o1, o3-mini.
  • DeepSeek: DeepSeek V3, DeepSeek R1.
  • Meta: Llama 3.3 70B Instruct, Llama 3.1 405B.

Utiliza el campo 🔍 Filtrar entre modelos para encontrar cualquier modelo en milisegundos.

6.1 Enrutamiento Dinámico Inteligente por Complejidad

El sistema incluye una Matriz de Complejidad Operativa que optimiza el modelo de IA automáticamente según el trabajo a realizar:

  • Fase 1 (Arquitecto / Diagnóstico Estratégico · Alta Complejidad): Al ingresar tu clave de OpenRouter, el sistema selecciona automáticamente Claude 3.5 Sonnet (o el modelo Frontier disponible) para garantizar razonamiento causal y esquemas JSON perfectos.
  • Adaptación por Escenario: Al cambiar entre los 7 departamentos corporativos (Producción, Logística, Finanzas, etc.), el sistema calibra el modelo sugerido acorde al nivel de exigencia técnica del área.
  • Asignación por Agente en la Célula: El Arquitecto etiqueta a cada agente propuesto con su grado de complejidad (Alta, Media o Baja) y le asigna el modelo óptimo (ej: Puesto de Triage en Gemini 2.0 Flash para máxima velocidad, Puesto Especialista en Claude 3.5 Sonnet para cálculo crítico, y Auditor en GPT-4o Mini para cumplimiento de reglas).
  • Conmutación en Vivo en la Escena: Durante la simulación operativa, el sistema conmuta visualmente el modelo activo según el puesto que está procesando la tarea y lo audita en el feed en tiempo real.

07 Conmutación Automática (Failover) y Circuit Breaker

Para evitar que la oficina se congele cuando una API agota saldo o tokens, el sistema implementa una arquitectura de Resiliencia Continua en api/circuit_breaker.php:

⚠️ Detección Inmediata: Si el modelo actual devuelve código HTTP 402 (Payment Required) o 429 (Rate Limit / Quota Exceeded), el motor no lanza error al usuario.

Mecanismo de Cascada

  1. El modelo agotado se registra en api/estado_salud_modelos.json con un temporizador de enfriamiento (*cooldown* de 3 a 5 minutos).
  2. La petición se conmuta instantáneamente al siguiente modelo de respaldo prioritario:
    Claude 3.5 Sonnet ➔ Gemini 2.0 Flash ➔ GPT-4o Mini ➔ DeepSeek V3 ➔ Llama 3.3 70B ➔ GPT-4o
  3. La interfaz muestra un aviso visual en color ámbar informando qué modelo falló y cuál asumió el control.
  4. Recuperación Automática: Al expirar el tiempo de enfriamiento, el sistema vuelve a intentar con el modelo original. Si vuelve a responder con éxito, lo rehabilita como modelo prioritario de manera transparente.

08 Fabricar Agentes, Prompts y Fichas JSON

Una vez aprobado el Blueprint, al presionar "⚡ Fabricar Célula con Memoria Persistente" el backend compila:

  • prompt.md de Producción: Prompt de sistema estricto con identidad, rol, directrices inquebrantables, política de memoria y formato de salida.
  • ficha.json Técnica: Ficha técnica estandarizada en formato JSON con la especificación completa del puesto.
  • Contratos de Inputs & Outputs: Qué datos exactos recibe el agente y qué estructura exacta debe generar.
  • Inicialización de Memoria: Registra las reglas de negocio base en la base de datos MySQL.

8.1 Arquitectura Multimodal de Inputs y Outputs (Voz, Chat, Archivos y Carpetas)

Los agentes no están limitados a texto simple. Operan con una arquitectura omnimodal de 4 vías de entrada y salida:

  • 💬 1. Chat Conversacional Omnicanal: Interacción directa por WhatsApp (QR / Baileys / Webhook), Webchat incrustable en la web del cliente o la bandeja colaborativa de Coworking. El agente interpreta el contexto, consulta su memoria y responde de forma natural.
  • 🎙️ 2. Voz y Mensajes de Audio: Ingesta de notas de voz enviadas por WhatsApp (.ogg, .mp3, .m4a, .wav) o grabadas desde la interfaz. El pipeline procesa el audio con modelos de transcripción (Whisper / Gemini Audio), lo traduce a texto estructurado para el agente, y puede sintetizar audio de respuesta (TTS).
  • 📁 3. Carpetas y Directorios de Ingesta (Hot-Folders): Monitorización de carpetas locales del servidor (ej: /documentos_inbox/) o sincronizadas en la nube (Google Drive, Dropbox, Nextcloud). Cada vez que se deposita un nuevo archivo, el agente asignado lo toma y lo procesa automáticamente.
  • 📑 4. Todo Tipo de Archivos y Documentos:
    • PDFs y Documentos Legales: Extracción de cláusulas, cotizaciones, pólizas y manuales operativos.
    • Hojas de Cálculo (Excel .xlsx y CSV): Listas de precios, inventarios de stock, bases de datos de clientes y extractos bancarios leídos celda por celda.
    • Documentos Word (.docx): Propuestas comerciales, borradores, pliegos y especificaciones de proyectos.
    • Imágenes (.jpg, .png, .webp): Comprobantes de pago bancario, fotos de productos, planos y catálogos procesados mediante visión artificial multimodal.
  • 🔄 5. Contratos Estructurados Inter-Agentes (JSON Pipeline): La salida (Output) de un agente alimenta con precisión matemática la entrada (Input) del siguiente puesto en la célula de trabajo.

09 La Oficina Virtual Isométrica en Vivo

En la pestaña "🖥️ Oficina en Vivo" se despliega el visualizador SVG isométrico:

  • Escritorios Virtuales: Dibuja en 2.5D la cantidad exacta de escritorios según los agentes fabricados.
  • Avatares Robotizados: Cada agente tiene su propio avatar con monitor activo y placa identificatoria.
  • Simulación de Flujo: Al hacer clic en "▶ Simular Flujo Operativo en Vivo", los puestos se iluminan en secuencia, despliegan globos de diálogo con sus pensamientos y pasan los datos a la siguiente estación.
  • Feed de Auditoría: El panel lateral registra cada evento con marca de tiempo.
  • Celebración de Ciclo: Al finalizar la tubería se lanza el confeti animado y el banner de éxito.

10 Sistema de Memoria Persistente en 3 Capas

Almacenado en la tabla memoria_agentes de MySQL, cada agente retiene tres tipos de conocimiento:

  1. Memoria de Corto Plazo: Datos volátiles de la tarea u orden actual en ejecución.
  2. Memoria de Largo Plazo: Catálogos de productos, listas de precios, políticas de tolerancia y directrices fijas del negocio.
  3. Memoria Episódica: Registro histórico de casos resueltos, antecedentes de clientes y auditorías pasadas.

Puedes auditar la memoria de cualquier agente haciendo clic en el botón "🧠 Ver Memoria" en el panel de nodos o en el Dashboard.

11 Malla de Interconexión Interdepartamental

Las oficinas no operan aisladas. A través de api/interconexion_deptos.php y la tabla bus_interdepartamental:

  • Cuando el departamento de Ventas cierra un pedido, emite un evento estructurado.
  • El Bus Interdepartamental lo recibe y despierta automáticamente la oficina de Producción para fabricar y la de Logística para despachar.
  • Queda trazabilidad completa del ciclo de negocio entre las diferentes oficinas virtuales del cliente.

12 Dashboard de Control y Métricas

En la pestaña "📊 Dashboard" dispones de:

  • Listado de Oficinas Creadas: Historial completo de clientes, departamentos y estados.
  • Botón "🖥️ Abrir Oficina": Carga instantáneamente cualquier oficina histórica en la escena isométrica en vivo.
  • Tubería Global de Datos: Inspección rápida de los inputs y outputs de toda la organización.

13 Guía de Migración a Hosting Web (cPanel / Hostinger)

Publica tu plataforma en cualquier servidor compartido sin necesidad de terminal SSH ni configuraciones complejas:

  1. Comprime la carpeta C:\xampp\htdocs\oficinadunamis\ en un archivo .zip.
  2. Súbelo a public_html/ (o un subdominio como agentes.tuempresa.com) en tu cPanel o panel de Hostinger y descomprímelo.
  3. Crea una Base de Datos MySQL y un usuario con todos los privilegios.
  4. Edita el archivo api/config.php con tus credenciales:
    define('DB_HOST', 'localhost'); define('DB_NAME', 'tu_nombre_de_bd'); define('DB_USER', 'tu_usuario_de_bd'); define('DB_PASS', 'tu_contraseña_de_bd');
  5. ¡Listo! Al ingresar a tu dominio, la base de datos se inicializará automáticamente.

14 Preguntas Frecuentes y Solución de Problemas

¿Por qué no veo los 470 modelos al abrir la página?

Si tu navegador tenía la página en caché, presiona Ctrl + F5 (o Ctrl + Shift + R) para recargar los scripts limpios. Verifica también que tu conexión a internet esté activa para consultar el catálogo de OpenRouter.

¿Qué sucede si se acaba el crédito en mi cuenta de OpenRouter?

El sistema activará el circuito de conmutación. Si tienes modelos gratuitos (free) configurados o saldo en otros proveedores, continuará sin detenerse e indicará el cambio en pantalla.

¿Puedo modificar los prompts generados por la IA?

Sí. Puedes hacer clic en cualquier agente en la escena interactiva, presionar "Ver Prompt", copiarlo y adaptarlo según las particularidades de tu cliente.

15 Coworking Digital: Agentes IA + Operador Humano y Conexiones Sin API

A diferencia de los chatbots aislados que requieren complejas verificaciones de Meta o Google Cloud Console, Oficina Dunamis incorpora un modelo de Coworking Digital (Human-in-the-Loop) que conecta redes sociales y agendas mediante métodos ultrarrápidos y sin fricción técnica.

15.1 Dinámica de Trabajo Copiloto vs. 100% Autónomo

  • Modo Copiloto (Supervisado): El agente recibe el mensaje del cliente por WhatsApp o Instagram, consulta su memoria persistente en MySQL y redacta una propuesta de respuesta perfecta. El operador humano ve el borrador en la bandeja, puede editarlo y presiona [Aprobar y Enviar] en 1 clic.
  • Modo 100% Autónomo: El agente responde y atiende 24/7 sin pedir permiso, notificando al operador solo cuando detecta un cierre de venta o un caso crítico.

15.2 Agendamiento en Google Calendar Directo (Zero-API)

Para evitar configurar OAuth2 y pantallas de consentimiento en Google Cloud, el sistema genera Enlaces Universales Dinámicos a través de api/generar_agendamiento.php:

https://calendar.google.com/calendar/render?action=TEMPLATE&text=Reunion+Estrategica&dates=20261120T170000Z/20261120T174500Z...

El cliente recibe el link en su WhatsApp, toca la pantalla de su teléfono y la cita queda guardada inmediatamente en su app nativa de calendario con recordatorios y enlace de videollamada.

15.3 Instancia Local en Node.js (Código QR con Baileys)

Tu plataforma ya incluye su propio microservicio en Node.js listo para correr en tu máquina sin instalar software externo:

  1. Hacé doble clic en el archivo INICIAR_WHATSAPP_QR.bat ubicado en la raíz de tu proyecto (C:\xampp\htdocs\oficinadunamis\).
  2. En la oficina virtual, abrí la pestaña 🤝 Coworking y presioná «📱 Conectar WhatsApp QR».
  3. El código QR se proyectará en vivo en tu pantalla. Escanealo desde tu teléfono (Dispositivos Vinculados).
  4. ¡Listo! Tu número quedará conectado. Cuando un cliente te escriba a tu WhatsApp personal o de empresa, el agente preparará la respuesta en tu bandeja de Coworking y al aprobarla se enviará automáticamente al chat del cliente.

15.4 Conexión de WhatsApp por Conectores Externos (Evolution API / n8n / Make)

Si prefieres desplegar Evolution API o n8n en un servidor en la nube para operar 24/7 sin tu PC encendida, solo apunta el Webhook de eventos a tu endpoint:

http://localhost/oficinadunamis/api/webhook_coworking.php

16 Sistema Multiusuario y Control de Acceso por Roles (RBAC)

Oficina Dunamis cuenta con una arquitectura de seguridad y permisos basada en roles (Role-Based Access Control - RBAC) nativa en PHP y MySQL (sin dependencias de librerías externas), ideal para agencias y empresas que operan con equipos humanos.

16.1 Los 4 Roles del Sistema

Rol Alcance y Permisos Pestañas Visibles
👑 Super Admin (Agencia) Acceso irrestricto. Diseña oficinas, configura la Marca Blanca, administra claves de OpenRouter y gestiona usuarios. Todas (Constructor, Oficina en Vivo, Coworking, Dashboard, Marca Blanca, Usuarios).
👔 Gerente (Cliente / Dpto) Supervisa la oficina y el flujo operativo. Puede simular la tubería, revisar métricas y auditar chats. No puede cambiar marcas ni ver la clave OpenRouter. Oficina en Vivo, Coworking, Dashboard.
🎧 Operador de Coworking Enfocado 100% en atención al cliente (Human-in-the-Loop). Revisa borradores de IA, edita y hace clic en [Aprobar y Enviar]. No ve configuración técnica. Exclusivo: Coworking & Redes.
👁️ Auditor (Solo Lectura) Acceso de inspección y trazabilidad. Puede ver la oficina isométrica y el historial de operaciones sin botones de modificación. Oficina en Vivo, Dashboard.

16.2 Usuarios y Credenciales Iniciales

Para facilitar pruebas inmediatas, la base de datos incluye 3 usuarios activos con acceso rápido de 1 clic en la pantalla de inicio:

  • Super Admin: admin@dunamis.ai · Contraseña: admin123
  • Gerente Operativo: gerente@cliente.com · Contraseña: gerente123
  • Operador Coworking: operador@dunamis.ai · Contraseña: operador123

16.3 Gestión y Creación de Nuevos Usuarios

Como Super Admin, en la barra superior dispones del botón «👥 Usuarios»:

  1. Permite dar de alta a nuevos colaboradores con su nombre, correo y contraseña encriptada (con bcrypt).
  2. Permite asignarles su rol específico y vincularlos a una oficina.
  3. Permite activar o suspender el acceso de cualquier usuario en tiempo real.
🏢 Ir a la Oficina Virtual