## Visión general

**Maestro** es el motor de IA de la plataforma: alimenta el Cerebro de la cuenta, el copiloto, los
agentes y el onboarding generativo. La integración se gestiona en la consola del operador — sin
necesidad de redesplegar el servicio para cambiar la configuración.

## Requisitos previos

- Acceso a la consola del operador (Super Admin).
- URL interna del servicio Maestro y la clave administrativa entregadas en el despliegue.

## Paso a paso

1. Abre la consola del operador → configuración de Maestro.
2. Completa la **URL de la API** (dirección interna) y, si aplica, la **URL pública** (usada en los
   webhooks de los agentes).
3. Ingresa la **clave administrativa** — queda enmascarada y no vuelve a mostrarse.
4. Elige el **modo de onboarding** para cuentas nuevas: apagado, guiado (wizard) o automático.
5. Define la **plantilla vertical predeterminada** aplicada cuando el registro no informa segmento.
6. Guarda y usa **"Probar conexión"** para validar.

## Configuración y opciones

- **Maestro habilitado**: interruptor general. Apagado, todas las superficies de IA responden con
  un estado claro de "desactivado por el operador" en lugar de errores de conexión.
- **Permitir claves por cuenta (BYOK)**: controla si las cuentas pueden usar sus propias claves de
  IA (ver el artículo "Tokens de IA por cuenta").
- La configuración del panel tiene precedencia sobre variables de entorno; los entornos
  aprovisionados por variables siguen funcionando.

### Pausa por atención humana

Cuando una conversación es asumida o asignada a una persona, el estado de pausa se guarda de forma
duradera y sigue válido después de reiniciar la API, los workers o la caché. Reanudar solo libera al
agente después de una confirmación válida; un estado desconocido se trata como pausado.

Cada agente también define qué conservar de los mensajes recibidos durante la pausa: **descartar**
(predeterminado), guardar solo el **más reciente** o guardar **un conjunto limitado** por cantidad y
edad. Reanudar nunca reproduce esos mensajes por sí solo. La reproducción es una acción separada,
explícita y confirmada por el operador.

Para procesar una cola conservada de forma segura:

1. Elimina el agente humano asignado a la conversación si todavía existe uno.
2. En el panel **Maestro** de la conversación, selecciona **Reanudar** y espera la confirmación. Esta
   acción libera solo mensajes nuevos.
3. La tarjeta **Mensajes recibidos durante la pausa** aparece únicamente después de confirmar la
   reanudación.
4. Selecciona **Procesar mensajes conservados**, revisa el impacto y elige **Confirmar procesamiento**.

Cada intento usa un identificador único y seguro para reintentos: si se pierde la respuesta de red,
volver a intentarlo no procesa dos veces la misma cola. Sin confirmación, con estado desconocido o
mientras haya un agente humano asignado, la plataforma mantiene la cola bloqueada.

## Casos de uso

- Rotar la clave administrativa tras una rotación de credenciales, sin reiniciar servicios.
- Activar el onboarding automático solo después de validar el guiado en cuentas piloto.

## Consejos, límites y buenas prácticas

- Rota la clave administrativa periódicamente y ante cualquier sospecha de exposición.
- Mantén la URL interna accesible solo en la red privada; expón únicamente la URL pública.

## Solución de problemas

El diagnóstico muestra uno de cinco estados:

- **OK**: servicio accesible y autenticado.
- **Falla de autenticación**: la clave administrativa no coincide con la del servicio — actualiza
  uno de los lados.
- **Inaccesible**: la URL no responde (DNS, red, servicio detenido). El detalle indica la causa.
- **Desactivado**: el interruptor general "Maestro habilitado" está apagado.
- **No configurado**: falta la clave administrativa.

Mientras el servicio esté **Inaccesible** o responda con un estado inválido, las respuestas
automáticas, las herramientas con efectos y los Follow-ups configurados para respetar la atención
humana permanecen bloqueados hasta que el estado vuelva a ser conocido.

Si el onboarding generativo está activo y Maestro no está disponible, las cuentas se siguen
aprovisionando con las plantillas verticales — nada se bloquea.

## Ver también

- Tokens de IA por cuenta (BYOK)
- Uso y límites de consumo
- Onboarding con IA