# Workflow e lavori

Un **workflow** è una catena di passaggi che i tuoi agenti eseguono per te:
leggere ogni mattina i nuovi messaggi di un contesto e pubblicare un
riassunto, leggere i documenti che arrivano ed estrarne i dati, rispondere a
un webhook di un altro sistema. Lo costruisci una volta in SweetHive e poi va
da solo.

I workflow girano **sui tuoi computer**, non nel cloud: sul tuo
[SweetHive Agents Node](agents-node) o sull'[Agents Server](agents-server)
della tua azienda. I modelli AI, i documenti e i dati che elaborano restano
su quelle macchine.

Tutto quello che gira per te è elencato in **My agents, Lavori**: i tuoi
workflow e le richieste che arrivano dalle app di SweetHive (per esempio
SweetTimetable che legge i tuoi scontrini, o SweetReach che crea un video).

## Creare un workflow

1. Apri **My agents** e scegli la scheda **Workflow**.
2. Clicca **Nuovo workflow**. Si apre l'editor con un canvas:
   - a sinistra, la lista dei **passaggi** che puoi aggiungere;
   - al centro, il **canvas** con i tuoi passaggi e i collegamenti tra loro;
   - a destra, le **impostazioni** del passaggio selezionato.
3. Clicca un passaggio nella lista per aggiungerlo dopo quello selezionato.
   Per collegare due passaggi, trascina dal pallino a destra di un passaggio
   fino a un altro passaggio.
4. Scegli l'**agente** con cui gira il workflow (barra in alto). I passaggi
   che leggono o pubblicano nei tuoi hive usano quell'agente, così il
   workflow non vede mai più di quanto può vedere l'agente.
5. **Salva**. Ogni modifica ai passaggi salva una nuova versione; le
   esecuzioni già partite tengono la versione con cui sono iniziate.
6. Premi **Esegui** per provarlo: ogni passaggio sul canvas mostra il suo
   stato in tempo reale (in attesa, in corso, fatto, non riuscito) e, una
   volta finito, il suo risultato.

## Quando parte un workflow

Seleziona il primo passaggio (l'avvio) per scegliere come parte il workflow:

- **Manuale** - quando premi Esegui, nell'editor o nella lista dei Workflow.
- **Pianificato** - a orari fissi: ogni ora, ogni giorno alle 8:00, dal lunedì
  al venerdì alle 9:00, o qualsiasi pianificazione che scrivi tu (cron) nel
  tuo fuso orario.
- **Evento della hive** - quando c'è un nuovo messaggio, file, task, evento o
  email in un hive (anche solo in un contesto, se vuoi).
- **Webhook** - quando un altro sistema chiama l'URL del workflow. Il segreto
  viene mostrato una sola volta: copialo quando lo crei.
- **Evento di un'app** - quando un'app collegata emette un evento (per
  esempio un nuovo lead in SweetCRM).

Puoi mettere in pausa un workflow in qualsiasi momento con il suo
interruttore **Attivo**.

## I passaggi

| Gruppo | Passaggi |
|---|---|
| SweetHive | **Leggi contesto** (messaggi, file, task di un contesto), **Pubblica nel contesto** |
| AI sul tuo computer | **Genera testo**, **Estrai dati** (da testo a dati strutturati), **Leggi documento** (da PDF, scansioni e foto a testo e dati), **Crea video** |
| Integrazioni | **Richiesta HTTP** (solo https; le reti private sono bloccate) |
| Dati | **Imposta valori**, **Trasforma lista**, **Filtra lista** |
| Flusso | **Se** (due rami), **Smista** (un ramo per ogni caso), **Attendi** |

Un passaggio può usare i risultati di quelli precedenti. In qualsiasi campo
di testo, inserisci una variabile con i pulsanti sotto le impostazioni, per
esempio `{{ $steps.summary.output.text }}` (il testo generato dal passaggio
chiamato *summary*) o `{{ $trigger }}` (ciò che ha avviato il workflow). Non
c'è codice da scrivere.

## Dove girano i passaggi

Ogni passaggio gira su uno dei tuoi computer:

- di norma resta sullo **stesso computer del passaggio precedente** (il
  modello è già caricato, i file sono già lì);
- si sposta su **un altro computer** quando gli serve qualcosa che il primo
  non ha: un modello che vede le immagini, un contesto più ampio, un render
  worker. Puoi anche lasciare che un passaggio giri su **qualsiasi computer
  disponibile** (*Dove gira* nelle sue impostazioni).

Se in quel momento nessuno dei tuoi computer può eseguire un passaggio, il
lavoro aspetta e ti dice perché (per esempio *In attesa di uno dei tuoi
computer: apri SweetHive Agents Node e parte da solo*). Parte da solo appena
un computer adatto è online.

## Seguire i tuoi lavori

**My agents, Lavori** elenca cosa sta girando e cosa è già girato, dal più
recente. Ogni lavoro mostra chi l'ha avviato (un workflow o un'app), quanti
passaggi sono fatti, quale computer lo sta eseguendo e, quando qualcosa va
storto, il motivo in parole semplici: il modello non è installato, il
documento è troppo lungo per il modello, il link al file è scaduto, il
computer ha smesso di rispondere.

- **Annulla** ferma un lavoro in attesa o in corso.
- **Riprova** esegue di nuovo un lavoro non riuscito o annullato.
- Apri un lavoro per vedere ogni passaggio, il computer e il modello usati,
  quanto ci ha messo e il suo risultato.

Quando il problema è sul computer (un modello mancante, un contesto troppo
piccolo, il computer spento), il lavoro non consuma i suoi tentativi: passa a
un altro computer o aspetta. Quando il problema è nei dati in ingresso (un
documento illeggibile, una risposta che il modello non è riuscito a
formattare), viene ritentato una volta e poi segnalato.

Lo SweetHive Agents Node mostra la stessa lista nella sua sezione **Lavori**:
cosa sta facendo adesso e cosa ha fatto di recente.

## Privacy

- Un workflow gira **come uno dei tuoi agenti**: vede solo gli hive e i
  contesti che quell'agente può vedere, e può pubblicare solo se
  quell'agente può pubblicare.
- I passaggi AI girano **sui tuoi computer** con modelli locali.
- I file passati tra un passaggio e l'altro sono conservati per 7 giorni e
  poi eliminati. I link ai documenti inviati dalle app non vengono mai
  mostrati nelle liste dei lavori.