Handoff al tecnico via WhatsApp

Quando l'agente industriale rileva un evento critico e apre un'attività, il tecnico riceve un WhatsApp con tutte le informazioni della macchina. Rispondendo, può chiedere manuali o segnalare la chiusura dell'attività senza re-identificarsi. Questa pagina descrive il flusso end-to-end.

Riassunto esecutivo

Il cambio di paradigma: il tecnico non digita più "Sono Juan del turno pomeridiano, la macchina 042 sta fallendo". Risponde allo stesso WhatsApp con "qual è la procedura?" e l'agente già sa chi è, quale macchina sta fallendo e quale attività è aperta.

Prima dell'handoff il tecnico doveva:

1. Leggere il WhatsApp dell'evento.
2. Aprire un'altra finestra per cercare il manuale.
3. Autenticarsi all'agente conversazionale con la sua identità per vedere documenti riservati.
4. Copiare l'asset_id manualmente nella query.

Con l'handoff: risponde allo stesso WhatsApp e tutto è nel contesto.

A cosa serve

• Rimuove l'attrito di identificazione. Il telefono che riceve il WhatsApp è già legato al personnel registrato. La sessione viene preautenticata con i ruoli del tecnico automaticamente.
• Preserva il contesto tra agenti. L'agente industriale elabora eventi; l'agente WhatsApp conversa. Senza handoff, il secondo non sa cosa abbia scatenato il thread. Con handoff, lo sa.
• Restringe le ricerche all'asset reale. Quando il tecnico chiede "come si pulisce?", l'agente risponde sulla pompa AST-042 che sta fallendo, non su qualsiasi pompa del catalogo.
• Supporta eventi concorrenti. Se un tecnico riceve due attività su asset diversi nella stessa ora, entrambi i contesti rimangono attivi nella conversazione e l'agente li distingue nella risposta.

Come funziona

sequenceDiagram
    participant PLC as Sensore / PLC
    participant MA as Agente di macchina
    participant DB as MongoDB
    participant WA as WhatsApp
    participant T as Tecnico
    participant CA as Agente conversazionale

    PLC->>MA: Evento (overheating, AST-042, critical)
    MA->>MA: assign_task → task MAN-001
    MA->>DB: push_machine_context(conv, asset_id, task_id, personnel_id)
    MA->>WA: send_whatsapp_message (template deterministico)
    WA->>T: "🔴 MAN-001 Asset AST-042 · overheating..."
    T->>WA: "quale manuale si applica?"
    WA->>CA: webhook (conversazione = Juan)
    CA->>DB: legge machine_contexts attivi + ruoli personnel
    CA->>CA: prompt arricchito + sessione preautenticata
    CA->>DB: query manuals con asset_id implicito
    DB-->>CA: sezione del manuale di AST-042
    CA->>T: "Procedura 4.2: spurgare il circuito..."

TTL e multi-contesto

Ogni voce in machine_contexts[] porta triggered_at e expires_at = triggered_at + 6h. Il job interno POST /internal/cleanup-machine-context viene eseguito ogni ora e purga le voci scadute.

Se due eventi arrivano allo stesso tecnico per asset diversi, lo stack ha due voci attive. Il prompt mostra all'agente un blocco per evento, così il tecnico può dire "il secondo" e l'agente sa di quale sta parlando.

Configurazione

L'intero handoff si attiva configurando la notifica dell'agente di macchina in Agente di macchina → Notifiche:

1. Abilitare WhatsApp.
2. Selezionare il numero connesso.
3. Scegliere Destinatario = un tecnico registrato in Personale.

Selezionare un tecnico registrato (non "Numero personalizzato") è ciò che attiva la preautenticazione e la preservazione del contesto. Se scegli un numero custom senza personnel, il WhatsApp parte ma il tecnico inizia anonimo e non potrà interrogare collezioni con access_roles configurati.

Ruoli del tecnico

I ruoli del tecnico vivono in _personnel.roles (array di stringhe). Il sistema li eredita così come sono nella sessione. Se il tecnico ha ruolo technician e una collezione manuals ha access_roles: ["technician"], la query passa.

Se una collezione ha access_roles non presenti nei ruoli del tecnico, la query fallisce con una risposta in linguaggio naturale: "Non ho il permesso per consultare quell'informazione con il tuo profilo." — l'agente non restituisce mai JSON grezzo all'utente.

Limitazioni

• L'handoff richiede che il telefono del tecnico in _personnel.phone corrisponda esattamente a ciò che il PLC ha inviato all'agente. Formati diversi non fanno match.
• Un singolo numero WhatsApp serve un solo agente conversazionale per tenant. Non puoi avere due agenti WhatsApp che puntano allo stesso numero.
• La preautenticazione assume che il telefono sia un fattore di identità sufficiente. Se un tecnico perde il telefono, chiunque con quel numero può interrogare finché il record non viene aggiornato o viene aggiunta autenticazione OTP esplicita.
• I contesti scaduti (più di 6 ore dal push) non vengono mostrati né usati anche se rimangono nell'array finché il job di cleanup non viene eseguito.
• asset_id si propaga solo se l'evento lo porta in metadata.asset_id. Sensori mal mappati non propagano il contesto.

Benefici chiave

• Thread WhatsApp unico, senza doppia identificazione.
• Risposte dell'agente ristrette all'asset reale dalla prima domanda.
• Multi-ticket: il tecnico gestisce più eventi aperti senza mischiarli.
• Chiusura dell'attività conversazionale senza aprire la dashboard.
• Scadenza automatica del contesto affinché le vecchie conversazioni non influenzino le risposte future.

Come verificarlo

Lo script scripts/e2e/machine_agent_demo/run_demo.py nel repo relaai-api esegue il flusso end-to-end contro un tenant reale (senza inviare WhatsApp reali né chiamare Gemini). Valida che il contesto sia persistito, la sessione sia preautenticata con i ruoli corretti e il cleanup purghi le voci scadute.