Assistenti di workflow

Gli assistenti di workflow sono una forma avanzata di assistenti AI in AI-School. Invece di una conversazione libera senza struttura fissa, l’utente segue una serie definita di passaggi — guidata dall’AI. Questo permette di automatizzare processi complessi, multi-step, come una lezione completa dall’inizio alla fine.

Che cos’è un assistente di workflow?

Un assistente di workflow è composto da una visuale di workflow di nodi (nodes) collegati da frecce (edges). Ogni nodo esegue un compito specifico, come:

• Inizio / Fine — il punto di inizio e di fine del workflow
• Valuta — analizza il contesto e memorizza informazioni strutturate nella memoria
• Condizione — valuta un’espressione e guida il flusso nella direzione corretta
• LLM — richiama un modello linguistico per un compito specifico (opzionalmente: attende input dall’utente)
• Approvazione — pone una domanda si/no e guida il flusso in base alla risposta
• Sottomissione / Subagent - esegue lo stesso compito in parallelo per più elementi, ad esempio uno studente per ciascuna revisione

Il workflow salva automaticamente il suo stato dopo ogni passaggio. Quando l’utente fornisce input, il workflow riprende esattamente da dove era rimasto.

Creare un assistente di workflow

Vai su Assistenti → Nuovo assistente e scegli il tipo Assistente di workflow. Puoi scegliere tra una tela vuota o una delle preset preconfigurate.

Impostazioni generali

Quando crei o modifici un workflow, imposti le impostazioni generali tramite il pannello delle impostazioni. Queste impostazioni valgono per l’intero workflow:

• Modello: Il modello AI usato da tutte le fasi. Scegli un solo modello per tutto il workflow.
• Strumenti: Quali strumenti sono disponibili nel workflow (ad es. registrazione, ricerca SLO, ricerca su Internet). Gli strumenti attivi sono disponibili per tutti i passaggi LLM, a meno che tu non li disattivi per singolo passaggio.
• Server MCP: Collegamenti esterni disponibili nel workflow.
• Documenti: File a cui i passaggi LLM possono fare riferimento.
• Immagini: Immagini che i passaggi LLM possono utilizzare.

È possibile anche impostare se l’utente può aggiungere file o immagini durante la chat.

File nei moduli di workflow

Un workflow può chiedere all’utente di fornire file, ad esempio una verifica, un modello di correzione o un lavoro studente consegnato. In caso di una domanda di file, l’utente può:

• caricare un nuovo file
• scegliere un file esistente da Gestione file
• per ogni domanda definire a quale parte appartiene il file

I nuovi file vengono elaborati prima. Il workflow può avanzare solo una volta che l’elaborazione è terminata in modo affidabile. Se una domanda di file obbligatoria è ancora in corso o fallita, l’utente deve attendere o selezionare/ricaricare nuovamente il file.

I file aggiunti tramite il modulo di workflow sono disponibili come file dell’assistente per quella chat. Non vengono selezionati automaticamente come normali file di chat.

Impostazioni per step

In ogni passaggio LLM puoi disattivare strumenti, file e immagini abilitati globalmente per quel passaggio specifico. Questo ti offre un controllo preciso su quali strumenti sono disponibili in quale passo. Non puoi aggiungere nulla a livello di passo se non è già stato abilitato a livello globale.

Usare preset

Per la maggior parte degli utenti, un preset è la migliore opzione iniziale. Puoi poi adattarlo alle tue esigenze.

Esempio: l’assistente di Lezione

L’Assistente Lezione è un preset pronto all’uso appositamente progettato per l’istruzione. Guida l’utente dall’inizio alla fine attraverso una lezione completa: dalla scelta dell’argomento e del livello, agli obiettivi di apprendimento e spiegazioni, fino agli esercizi e a una sintesi finale.

Panoramica del workflow

Il Lezione assistente è composto dai seguenti passaggi (nodi), in ordine:

Passo per passo spiegato

1. Inizio

Il workflow inizia non appena l’utente apre la chat e invia il suo primo messaggio.

---

2. Triage: Argomento della lezione (evalueer-node)

Cosa fa? L’AI analizza il messaggio dell’utente e cerca di determinare:

• Argomento — di cosa parla la lezione? (ad es. "legge della leva")
• Livello — base, medio o avanzato?
• Informazioni sufficienti? — c’è abbastanza contesto per definire subito gli obiettivi di apprendimento?

Questo risultato viene salvato nella memoria del workflow.

---

3. Informazioni sufficienti? (condizione-node)

Se c’è abbastanza informazione (informazioni_sufficienti = true), il workflow va direttamente a Definire obiettivi di apprendimento.

Se manca informazione, va a Raccogliere informazioni.

---

4. Raccogliere informazioni (LLM-node, attende input)

Cosa fa? L’AI pone domande mirate all’utente per identificare l’argomento e il livello desiderato. Non appena l’utente risponde, il flusso torna a Triage: Argomento della lezione per una nuova valutazione.

Esempio di dialogo:

🤖 "È bello averti qui! Per poterti aiutare bene, alcune brevi domande: 1. Su quale argomento vuoi una lezione? 2. A che livello sei? (base / medio / avanzato)"

👤 "9o2 3 scienze naturali, leva"

Dopo questa risposta, la triage viene rieseguita e determina: informazioni_sufficienti = true.

---

5. Definire obiettivi di apprendimento (LLM-node)

Cosa fa? L’AI definisce una lista numerata di massimo 4-5 obiettivi di apprendimento concreti e misurabili per l’argomento e livello indicati.

Output di esempio:

Obiettivi di apprendimento per Leva – (base) / medio:

1. Puoi formulare la legge della leva e spiegare la formula F₁ × r₁ = F₂ × r₂.
2. Puoi eseguire calcoli per determinare forze o bracci inconosciuti.
3. Puoi applicare la leva a esempi pratici (sciavetta, carriola, altalena).
4. Puoi spiegare la differenza tra leva di primo, secondo o terzo tipo.

---

6. Approvare obiettivi (goedkeuring-node)

Cosa fa? L’AI chiede all’utente se gli obiettivi di apprendimento sono corretti e se la lezione può iniziare.

• Sì → procedi con la lezione
• No → torna a Definire obiettivi di apprendimento per riformularli

L’utente può visualizzare gli obiettivi tramite il menu a barra espandibile nella chat.

---

7. Triage: Obiettivi di apprendimento (evalueer-node)

Cosa fa? Dopo ogni ciclo di lezione, l’AI verifica se l’utente ha padroneggiato tutti gli obiettivi. Si tratta di una valutazione rigorosa: l’utente deve dimostrare di comprendere ogni obiettivo.

---

8. Tutti gli obiettivi compresi? (condizione-node)

• Sì → procedi a Agente esercizi
• No → procedi all’Agente Lezione per il prossimo obiettivo

---

9. Agente Lezione (LLM-node, attende input)

Cosa fa? L’AI insegna la materia sull’argomento, passo dopo passo, in base agli obiettivi di apprendimento. Dopo ogni parte, l’AI propone una domanda di comprensione. Solo quando l’utente dimostra di capire l’obiettivo, la lezione procede.

Dopo l’input dell’utente, il flusso torna a Triage: Obiettivi di apprendimento per valutare il progresso.

Esempio:

🤖 "Iniziamo con obiettivo di apprendimento 1: la leva. Una leva è una barra rigida che ruota attorno al punto di appoggio. La forza necessaria dipende dalla distanza dal punto di appoggio. La formula è:

F₁ × r₁ = F₂ × r₂

Puoi spiegare cosa significano r₁ e r₂ in questa formula?"

---

10. Agente esercizi (LLM-node, attende input)

Cosa fa? L’AI propone almeno una domanda di esercizio per ogni obiettivo di apprendimento. L’utente risponde alle domande, quindi il flusso procede a Agente feedback.

---

11. Agente feedback (LLM-node, attende input)

Cosa fa? L’AI fornisce feedback dettagliato e personale sugli esercizi svolti. Per ogni obiettivo di apprendimento si discute cosa è andato bene e dove migliorare. Il tono è onesto ma incoraggiante.

---

12. Concludere? (goedkeuring-node)

L’AI chiede se l’utente vuole concludere o se desidera praticare ancora.

• Sì → vai a Sintesi
• No → torna a Agente esercizi per un nuovo giro

---

13. Sintesi (LLM-node)

Cosa fa? L’AI offre una chiara sintesi di tutto il materiale trattato, seguita da feedback finale personale e motivante sulle prestazioni.

---

14. Fine

Il workflow si chiude con un messaggio di incoraggiamento.

"Ottimo lavoro in questa lezione e a presto!"

---

Conversazione completa di esempio

Di seguito una breve conversazione di esempio con l’Assistente di Lezione sulla leva, base/medio:

Chi	Messaggio
👤 Utente	ciao
🤖 Assistente di Lezione	Felice che tu sia qui! Su quale argomento vuoi una lezione e a quale livello?
👤 Utente	leva, livello base/medio
🤖 Assistente di Lezione	Perfetto! Ho definito 4 obiettivi di apprendimento. Vuoi iniziare la lezione con questi obiettivi?
👤 Utente	sì
🤖 Assistente di Lezione	Iniziamo con l’obiettivo di apprendimento 1: la leva. (spiegazione + domanda di comprensione)
👤 Utente	(risposta alla domanda di comprensione)
🤖 Assistente di Lezione	(continua lezione per obiettivo 2, 3, 4 ...)
🤖 Assistente di Lezione	Hai completato tutti gli obiettivi di apprendimento! È tempo degli esercizi...
👤 Utente	(risposte agli esercizi)
🤖 Assistente di Lezione	(feedback personale) Vuoi concludere o fare ancora esercizi?
👤 Utente	concludere
🤖 Assistente di Lezione	(sintesi + chiusura motivante)

Monitorare i progressi

Quando interagisci con un assistente di workflow, puoi monitorare i progressi tramite il pulsante Workflow a destra dell’input della chat. Cliccando si apre un pannello con:

• Tutti i passi del workflow (condizione e note non mostrati)
• lo stato di ogni passo:
  • ⬜ In attesa: Non ancora raggiunto
  • 🔄 In corso: In esecuzione
  • ✅ Pronto: Completato con successo
  • ⏸️ In attesa di input: In attesa di una risposta dell’utente
  • ⏭️ Saltato: Non eseguito (es. per una condizione)
  • ❌ Errore: Si è verificato un errore

Creare una triage node

Una node di valutazione (triage node) estrae informazioni dalla conversazione e le salva nella memoria del workflow. Le condizioni possono leggere quei valori per guidare il flusso nella direzione corretta.

Configurazione

1. Aggiungi una node Valuta alla workflow.
2. Scrivi un prompt di sistema che descriva cosa deve analizzare l’AI e quali conclusioni trarre.
3. Definisci lo schema di output con campi:
   • Nome del campo: La chiave con cui recuperare il valore in seguito (ad es. informazioni_sufficienti, livello, route).
   • Tipo: string (testo), number (numero), boolean (sì/no), o enum (scelta tra valori fissi). Per enum indica i valori consentiti separati da virgole.
4. Imposta un numero massimo di iterazioni per evitare che la node giri indefinidamente.

Valori di memoria

I valori salvati sono accessibili tramite il prefisso state. nelle node di condizione, ad es. state.informazioni_sufficienti o state.livello.

Impostare una node di condizione

Una condizione node valuta espressioni basate sulla memoria del workflow e indirizza il flusso alla successiva node appropriata.

Rami

Una condizione node ha uno o più rami:

• Se (if): la prima condizione che viene valutata.
• Altrimenti se (else-if): eventuali condizioni aggiuntive.
• Altrimenti (else): la rotta predefinita se nessuna condizione è vera.

Scrivere espressioni

Le espressioni si scrivono in CEL (Common Expression Language):

Comportamento desiderato	Espressione
Campo è true	state.informazioni_sufficienti == true
Campo ha un valore fisso	state.livello == "avanzato"
Confronto numerico	state.score > 7
Più condizioni	state.livello == "base" && state.score < 5

Collegamenti

Disegna dalla node di condizione collegamenti separati per ogni ramo verso la node successiva corretta. L’editor mostra per ogni ramo una uscita distinta dalla node.

Usare una subagent node

Una subagent node è pensata per compiti che devono essere eseguiti molte volte nello stesso modo. La node ottiene una lista di elementi dalla memoria del workflow e avvia per ciascun elemento una esecuzione separata con una context isolata.

Applicazioni pratiche:

• correggere un test per ogni studente
• analizzare un documento per ogni file
• creare un sommario per ogni modulo compilato
• registrare un rapporto per ogni parte

Configurazione

1. Assicurati che una precedente node di valutazione abbia salvato una lista di elementi nella memoria del workflow, ad es. studenti_json.
2. Aggiungi una node Subagent.
3. Imposta la fonte degli elementi.
4. Configura eventualmente un field di etichettatura per rendere chiaro il progresso.
5. Imposta il numero massimo di esecuzioni parallele.
6. Indica sotto quale chiave di memoria salvare i risultati.

Il contesto della subagent contiene sempre solo l’elemento attualmente in lavorazione. Perciò fai esplicitamente riferimento all’elemento corrente nel prompt e evita che l’AI gestisca più elementi contemporaneamente.

Registrazione in workflow

Lo strumento Registrazione è particolarmente utile nei workflow. Consente all’AI di memorizzare automaticamente risultati intermedi o finali come documenti ricercabili nel pannello laterale.

Configurazione

1. Abilita la Registrazione tramite le impostazioni generali del workflow.
2. Aggiungi nel prompt di sistema della desiderata fase LLM un’istruzione per registrare contenuti specifici. Attiva lo strumento per quella fase (o lascialo attivo globalmente).

Esempio

In una fase di obiettivi di apprendimento puoi scrivere nel prompt di sistema:

"Definisci gli obiettivi di apprendimento per l’argomento e livello indicati. Registra subito gli obiettivi di apprendimento con lo strumento di Registrazione, con il titolo 'Obiettivi di apprendimento'."

L’utente può visualizzare i documenti registrati tramite il pulsante Registrazione (📄) nella barra degli strumenti della chat.

Ripristinare una conversazione

Se sei a metà di una lezione e vuoi tornare a un punto precedente della conversazione, puoi farlo tramite il pulsante di ripristino (l’icona della cronologia) in un messaggio precedente. Questo elimina tutti i messaggi successivi a quel punto e riprende il workflow da quel preciso momento.

Attenzione

Il ripristino è definitivo — i messaggi eliminati non sono più disponibili.

Modifica del Workflow

Come amministratore, puoi aprire e modificare un workflow esistente nell’editor di workflow. Clicca su un nodo per modificare la configurazione, aggiungi nuovi nodi tramite il menu con clic destro o trascina connessioni verso altri nodi.

Per un workflow completamente nuovo puoi partire da una tela vuota o da un’altra preset.