Cómo está construida Alma por dentro, sin humo: los servicios y cómo se hablan, qué herramientas tiene cada agente, dónde vive cada pieza y qué técnicas usamos. Verificado contra el código a día de hoy.
Tres capas: lo que toca la gente, el núcleo que orquesta y la plataforma de la que todo depende.
Del mensaje del propietario a la respuesta sugerida en el panel. La persona decide; nada llega al cliente sin ella.
Atlas no genera respuestas: recupera conocimiento verificado, con cita. Hoy: ~150 documentos del negocio en 8 áreas, más 26 fichas de casa y 5 de zona extraídas del propio chat, con filtro de seguridad por casa.
Lola solo contesta si es la agente activa de ese canal. Desde ahí resuelve con lo que tiene a mano, y cada mensaje termina en uno de tres caminos. Y hay un atajo intermedio: si solo le falta un dato, pregunta al equipo por dentro (ask_team) y sigue ella cuando se lo responden, con recordatorios si nadie contesta.
El handoff y la escalación no se quedan colgados: un barrido revisa cada 5 minutos si alguien ya respondió, y avisa cada vez más alto si nadie lo hizo. Dos válvulas lo paran cuando ya no hace falta.
| Agente | Dónde corre | Modelos | Herramientas y límites |
|---|---|---|---|
| Fabián (producción) | vivla-tools · chat/copilot |
Sonnet 4.6 razona · Haiku 4.5 clasifica | Allowlist de 22 herramientas de solo-lectura (reservas, casas, pagos, tickets). Persona y reglas de marca versionadas en código. |
| Lola (producción) | vivla-concierge · Mastra | Sonnet 4.6 | Tool-search semántico (top-6) sobre el catálogo del MCP de tools: busca la herramienta que toca en vez de cargar 88. Supervisora: delega incidencias en el Fabián-especialista. Memoria por propietario (98 biografías, destiladas cada noche), 9 reglas de comportamiento pactadas con CX y presentación obligatoria como agente de IA (ley europea de IA). |
| Guardarraíles | vivla-concierge | , | Filtro de prompt-injection y moderación a la entrada/salida + kill-switch de escrituras: en modo test, cualquier herramienta que cree/modifique/envíe queda bloqueada por patrón de verbo. |
| Calidad (evals) | vivla-concierge · harness | juez: Haiku 4.5 | 4 jueces LLM (uso de herramientas, fidelidad, persona, relevancia) sobre un dataset dorado de 18 casos; resultados a Langfuse. Con esto se decidió Sonnet vs Opus (ganó Sonnet). |
MCP (Model Context Protocol) es el enchufe estándar entre agentes y sistemas. Tenemos tres.
list_properties, get_propertylist_active_stays, property_occupancy_calendarcreate_ticket, update_ticketget_channel_messages, get_chat_analyticsaggregate_survey_responsesbuscar_atlas: fragmentos con cita y verificaciónlistar_areas: el mapa del conocimientoobtener_documento: documento completo por rutasearch_vivla_docs: busca en la documentaciónquery_docs_filesystem: navega el árbol de docsLa pregunta de fondo: ¿cómo le das herramientas a un agente sin construir una integración nueva por cada agente y por cada cliente? MCP es el enchufe estándar; esto es lo que nos da frente a las alternativas.
| MCP (lo elegido) | CLI a medida | API + SDK propio | |
|---|---|---|---|
| Descubrimiento | El agente se conecta y recibe el catálogo con schemas tipados; búsqueda semántica de la tool que toca | Parsear un --help; frágil y sin contrato | Leer docs y escribir un cliente por integración |
| Identidad | OAuth 2.1 + PKCE: el agente actúa con los permisos de una persona concreta | API keys sueltas en cada máquina | Tokens custom por integración |
| Dónde corre | Nada que instalar: HTTP desde cualquier sitio | Instalar y actualizar el binario allá donde corra cada agente | Un SDK por lenguaje/framework |
| Quién lo aprovecha | Cualquier cliente MCP: nuestros agentes Mastra, Claude, ChatGPT, Cursor, sin código nuevo | Solo quien tenga la CLI instalada | Solo quien integre el SDK |
| Control y auditoría | Centralizados en el servidor: permisos por rol, log de escrituras, lecturas sensibles auditadas | Dispersos por máquina | Repetidos en cada integración |
| Evolución | Se añade una tool en el servidor y todos los clientes la ven al momento; renombres con alias, sin romper a nadie | Redistribuir el binario | Republicar SDKs y avisar a los equipos |
| Estándar | Abierto (Anthropic; adoptado por OpenAI, Google y Microsoft): sin lock-in de proveedor | Propietario nuestro | Propietario nuestro |
La misma decisión, en una frase: una API pensada para que la consuma un modelo, con contrato, identidad y catálogo vivo, que además nos sirve para operar nosotros desde Claude o Cursor.
98 tools registradas; 88 expuestas por MCP (las 10 restantes son de la interfaz del chat interno). Convención de nombres dominio_verbo, con alias para los nombres antiguos. Todo es de solo lectura salvo las 3 marcadas.
list_properties · lista y busca casasproperty_get · ficha completa de una casaproperty_access_get · accesos, alarma, wifi sensible · lectura auditadaupdate_property · edita datos de la casa escrituraproperty_health_get / property_health_list · salud 0-100 y rankingproperty_overview_get · resumen operativo agregadolist_property_assignments / get_property_main_agent · quién lleva cada casalist_locations · destinoslist_property_photos / list_floor_plans / list_qr_codes · material de la casalist_rooms · habitacionesget_inventory · inventarioget_cleaning_status · limpiezas y calendariolist_appliance_guides / get_appliance_guide · guías de electrodomésticoslist_items · catálogo de itemslist_cleaning_templates · checklists de limpiezabooking_list / booking_get · reservas por filtros y detallelist_active_stays · quién está alojado hoylist_check_ins / list_check_outs · llegadas y salidas por fechaslist_owner_stays · estancias de propietariosproperty_occupancy_calendar · calendario libre/ocupado día a díafind_owner · busca un propietariolist_property_agents · agentes asignadosticket_list / ticket_get · partes por filtros y detalleticket_messages_get · hilo de mensajes del parteticket_create · crea el parte en Zendesk escrituraupdate_ticket · estado, prioridad, responsable escriturapropose_ticket · propone un borrador de partelist_channels / get_channel · canales y detallelist_channel_messages · mensajes de un canalchannel_members_list · quién está en el canalchannel_context_get · la foto completa del cliente del canalget_chat_analytics · métricas del chatlist_quick_replies · respuestas rápidas de CXlist_invitations / list_shifts / list_chat_notifications / list_inbox_messages · operación del equiposurvey_list · tipos de encuestasurvey_questions_get · preguntas de la versión activasurvey_scores_get / survey_summary_get · puntuaciones y resumensurvey_responses_aggregate · agregados por semana, casa o banda (incluye NPS)list_survey_responses / survey_response_get · respuestas crudas y una en detallesurvey_responses_get · historial completo de un cliente o casasurvey_pending_get · encuestas pendientes de un clienteget_survey_insights · hallazgos generados por IAlist_action_plans / list_survey_property_configs / list_survey_participation_exclusions · gestiónlist_notification_templates / list_notification_automations · plantillas y automatismoslist_notification_history · qué se envió a quiénget_notification_dashboard · el panel del motorlist_deep_links · enlaces profundos de la applist_email_blocks / list_email_assets / list_email_events · piezas y eventos de emaillist_notification_suppressions · exclusiones de envíolist_users · busca usuariosclient_get · ficha de clientelist_teams / get_team · equipos internosget_property_web_data · la casa tal y como se publicalist_amenities / list_property_amenities · amenitieslist_property_videos / list_web_texts · vídeos y textossummarize_conversation · resume una conversacióndraft_reply · borrador de respuestacompare_properties · compara casasgenerate_report · informe a medidadaily_briefing · el día de un vistazo (llegadas, partes, encuestas)get_audit_trail · qué hizo la IA y cuándoproperty_hierarchy_diagram / team_org_chart_diagram · diagramas al vuelolist_app_releases / get_app_store_status · versiones de la applist_permissions · quién puede quéSolo quien pase el guard OAuth 2.1 + PKCE contra Auth0 (issuer y audience verificados, RS256). El token es de una persona: el agente hereda exactamente sus permisos por módulo (viewer/editor/admin), los mismos que en el panel. Y cada agente interno lleva además su propia allowlist (Fabián: 22 tools de solo lectura).
Solo 3 tools escriben (crear/editar parte, editar casa) y toda escritura queda en el audit log con el nombre de la tool. En concierge hay un segundo cierre: el kill-switch bloquea por patrón cualquier verbo de escritura mientras un agente está en pruebas.
Las tools sensibles (códigos de acceso, alarmas) están gateadas por permiso y auditan también cada lectura. Por MCP no viajan secrets ni credenciales; la ficha de casa que ve un agente excluye esos campos salvo tool explícita.
El chat no depende de él: los mensajes viajan por Stream. Los agentes degradan (responden sin dato o pasan a una persona) y los feature flags fallan cerrados: sin configuración, la IA no actúa.
Un archivo en el backend con nombre, descripción, schema y ejecución, registrado en el módulo. Al desplegar, todos los clientes la descubren en su siguiente sesión. Los renombres no rompen a nadie: hay alias del nombre viejo al nuevo.
No las carga: Lola usa tool-search semántico y trae solo las 6 más relevantes para cada petición. Menos contexto, menos coste, menos error. Fabián ni busca: lleva su allowlist fija de 22.
Tres capas: audit log de escrituras y lecturas sensibles (con usuario y tool), traza completa de cada llamada LLM en Langfuse con versión de prompt, y telemetría de producto en PostHog (sugerencia mostrada, aceptada, editada).
No. MCP es un estándar abierto que ya adoptan OpenAI, Google y Microsoft: los mismos servidores sirven a Claude, ChatGPT o Cursor. Y el modelo es intercambiable: elegimos Sonnet frente a Opus con nuestras propias evals, y podemos repetir esa decisión cuando salga algo mejor.
Porque duplicaríamos el contrato en cada agente y framework. Con MCP el catálogo, los permisos y la auditoría viven una sola vez en el servidor, y nos sirve gratis para operar nosotros desde Claude Desktop o Cursor.
Tres cosas: la validación de inputs es declarativa (el schema guía al modelo; falta validación central de runtime), el rate limit es global por IP (100/min; falta límite por identidad), y los scopes por tool están declarados pero aún no se aplican. Están en la lista de abajo.
| Pieza | Plataforma | Nota |
|---|---|---|
| Backend de tools (chat, Fabián, MCP) | Railway | NestJS · deploy por GitHub Actions con health-check del commit |
| Panel de CX | Vercel | tools.vivla.com · entornos develop/prod |
| Concierge (Lola) | Railway | Mastra en contenedor Node 22 · healthcheck /api/agents |
| Atlas (API + MCP) | Railway | mcp.atlas.vivla.com · documentos del negocio + fichas por casa |
| Web de Atlas | atlas.vivla.com | Astro + Starlight, tras Cloudflare Access (login Vivla) |
| Datos operativos | Supabase (Postgres) | canales, tickets, avisos, encuestas, eventos de dominio |
| Índice de Atlas | Postgres + pgvector | tsvector (léxico) + HNSW (vectorial) en la misma tabla |
| Embeddings | Cloudflare Workers AI | bge-m3, 1024 dims |
| Chat (transporte) | Stream | canales, presencia, webhooks hacia el backend |
| Jobs y syncs | Windmill | motor de avisos (cada 30 s), eventos derivados diarios |
| Identidad | Auth0 | personas, apps y agentes; OAuth 2.1 + PKCE en el MCP |
| Observabilidad | Langfuse · PostHog | traza LLM con versión de prompt · métricas y feature flags |
propose_ticket debe exponerse fuera del chat interno.