Conceptos Fundamentales: La Jerarquía Operativa

Para dominar el Centro de Acción y las herramientas de IA en Sfero, es crucial entender cómo interactúan los tres roles principales en el ecosistema. Cada uno tiene un propósito específico y herramientas dedicadas.

1. El Administrador (Estratega)

Es el dueño de la organización en Sfero. Su rol es Estratégico.

Responsabilidad: Monitorear la gestión general de la organización.
Alcance: Todos los espacios de trabajo.
Acciones Clave: Creación de usuarios (Gestores), Creación y gestión de Workspaces, Monitoreo de resultados de Insights.

2. El Gestor (Táctico)

Es el líder operativo de un equipo o área (Workspace). Su rol es Táctico.

Responsabilidad: Diseñar y asegurar la ejecución de la estrategia de evaluación.
Alcance: Sus Espacios de Trabajo (Workspaces) asignados.
Acciones Clave: Creación de Objetos de Evaluación, Evaluadores, Plantillas y Asignaciones. Monitoreo del equipo Evaluador.

3. El Evaluador (Ejecutor)

Es quien está en el campo o en el punto de inspección. Su rol es Ejecutivo.

Responsabilidad: Capturar la realidad con precisión y veracidad.
Alcance: Las asignaciones que recibe en su bandeja de entrada.
Acciones Clave: Capturar información en las plantillas asignadas (Online/Scan to Fill). Sincronizar datos.

Objeto de Evaluación, Tipo de Objeto, Sujeto y Tipo de Sujeto

El Gestor es responsable de configurar los Objetos de Evaluación de cada Workspace. Para hacerlo correctamente, debe distinguir cuatro conceptos:

Concepto	Definición	Ejemplos
Tipo de Objeto	Es la Instancia o Intención CORE de Sfero. Define para qué se evaluará el objeto. No es configurable por el usuario: se selecciona entre las cinco instancias del sistema.	Inspecciones, Intervenciones, Monitoreo, Auditorías, Evaluaciones
Sujeto	Es la entidad concreta que será evaluada dentro de esa intención. Responde a “qué o quién se evalúa”.	Línea de Producción 1, Área de Manejo de Químicos, Comedor y Vestuarios
Tipo de Sujeto	Es la categoría o rol operativo que agrupa al sujeto. Sirve para organizar, filtrar y asignar objetos con mayor claridad.	Línea, Área, Equipo, Instalación, Persona, Norma, Proceso
Objeto de Evaluación	Es el registro final que el Gestor configura combinando Tipo de Objeto + Sujeto + Tipo de Sujeto.	Inspecciones / Línea de Producción 1 / Línea

En términos prácticos, el Gestor crea un Objeto de Evaluación en este orden:

Selecciona el Tipo de Objeto o intención CORE.
Define el Sujeto concreto.
Clasifica ese sujeto con un Tipo de Sujeto.

Esta estructura permite que las plantillas, asignaciones, filtros e inteligencia operativa hablen el mismo idioma.

Asignación vs. Evaluación

Es fundamental distinguir entre la orden y la ejecución:

La Asignación (El Plano)

Es la orden administrativa creada por el Gestor. Contiene las instrucciones: Quién evalúa, Qué evalúa, Cuándo y con Qué plantilla. Mientras está como asignación, es un plan pendiente de ejecución.

La Evaluación (La Realidad)

Es el registro resultante creado por el Evaluador. Una vez el evaluador completa la asignación, esta se convierte en una evaluación con datos, evidencia y resultados que alimentan la inteligencia del sistema.

El MCP Server: Integración con Agentes Autónomos

El MCP Server de Sfero es una capa de integración basada en el Model Context Protocol que permite a agentes de IA externos y sistemas autónomos interactuar con Sfero de forma programática. Mientras que los tres roles descritos arriba operan a través de la interfaz web, el MCP Server abre una puerta para que herramientas como Claude, sistemas CMMS, plataformas de mantenimiento o cualquier agente compatible con MCP participen en el ciclo operativo.

¿Para qué sirve?

El caso de uso central es el cierre del ciclo operativo: Sfero detecta un problema (via triage de IA), y un sistema externo —por ejemplo, un sistema de gestión de órdenes de trabajo— recibe esa alerta, crea la orden de trabajo, ejecuta la corrección, y finalmente le notifica a Sfero que el problema fue resuelto. Todo esto puede suceder de forma automatizada, sin intervención humana manual.

Autenticación: API Keys

El acceso al MCP Server se controla mediante API Keys con prefijo sfero_. Solo el Administrador puede crearlas o revocarlas desde la configuración de la organización. Cada clave:

Se muestra una sola vez al momento de creación — no es recuperable después.
Se almacena como hash SHA-256 en Cloudflare KV (el secreto nunca persiste en base de datos).
Queda asociada a la organización, no a un usuario individual.
Puede ser revocada con efecto inmediato.

Herramientas Disponibles

El MCP Server expone herramientas organizadas por dominio:

Dominio	Herramientas
Workspaces	`list_workspaces`, `get_workspace_catalogs`
Objetos de Evaluación	`list_evaluation_objects`, `create_evaluation_object`, `get_evaluation_object`
Plantillas	`list_templates`, `get_template`
Asignaciones	`list_assignments`, `create_assignment` y otras operaciones de ciclo de vida
Inteligencia	`get_assignment_results` (triage, briefing ejecutivo, análisis predictivo)
Cierre Operativo	`record_operational_feedback` (registra la resolución desde sistemas externos)
Webhooks	`register_webhook`, `list_webhooks`, `revoke_webhook`

Webhooks: Notificaciones en Tiempo Real

En lugar de hacer polling, un agente puede registrar un webhook para recibir una notificación push cuando Sfero genera nuevos insights para una evaluación. El evento insights.generated entrega un payload liviano con el evaluation_id, y el agente puede entonces llamar a get_assignment_results para obtener el análisis completo.

Cada entrega viene firmada con HMAC-SHA256 usando el secreto del webhook, lo que permite al receptor verificar que el mensaje proviene de Sfero. Una organización puede tener hasta 5 webhooks activos simultáneamente. Si un webhook falla 10 veces consecutivas, se desactiva automáticamente.

Flujo Típico de Integración

El Administrador crea una API Key desde la configuración y la entrega al equipo de integración.
El agente externo se conecta al MCP Server usando la clave y llama a list_workspaces para descubrir el entorno.
Registra un webhook para el evento insights.generated.
Cuando un Evaluador completa una evaluación, Sfero procesa la IA y dispara el webhook.
El agente recibe la notificación, consulta get_assignment_results, y actúa (abre una orden de trabajo, envía una alerta, etc.).
Una vez resuelta la situación, el agente llama a record_operational_feedback para cerrar el ciclo en Sfero.