> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Costruire un workflow

Costruire un workflow è un lavoro iterativo: aggiungi un passaggio, lo provi,
guardi cosa è uscito, aggiungi il successivo. Chi prova solo alla fine passa il
doppio del tempo a capire dove si è rotto.

![La tela di un workflow in bozza: a sinistra il Trigger con Inizia da qui, poi un blocco Agente, una Condizione con due uscite e due blocchi finali. In alto il titolo, lo stato Bozza, Condividi e Pubblica; in basso Esecuzioni passate, Analytics, Impostazioni, Crea con l'AI e Aggiungi](/_fern-img/d1bb2acfcd3cf516140e27aaf58730e47e1115066c8fa5edb4cbf813d4984509.webp)

## Prima di aprire la tela

Scrivi in una riga cosa deve fare il flusso.

> *Quando arriva una richiesta di assistenza, capisci di che tipo è, apri il
> ticket nella coda giusta e conferma al cliente.*

Se non ci riesci in una riga, quasi sempre sono due workflow.

## Un passaggio alla volta

#### Apri Nuovo e scegli Workflow

In **Automazioni** premi **Nuovo**, in alto a destra, e scegli **Workflow**.

![Il menu del pulsante Nuovo con la voce Workflow evidenziata; sotto, Importa workflow (.json) e Schedulata](/_fern-img/90e9c854f8c2fae963f08deb4ae36a626a968417f370d96ed6503548a888b921.webp)

#### Dai un nome e premi Crea workflow

Scrivi il **Nome del workflow** e, se vuoi, una **Descrizione (opzionale)**.
**Crea workflow** apre la tela con un Trigger **Manuale** già al suo posto.

![La finestra Crea nuovo workflow con il nome e la descrizione compilati e il pulsante Crea workflow evidenziato](/_fern-img/e688e320118af193aea43d9cd3407238c4cf5d148684a445d4f2e2815295f75a.webp)

#### Configura il trigger

Clicca il blocco **Trigger**: in cima al pannello scegli come parte il flusso.
È la scelta che stabilisce quali dati hai in ingresso, e tutto il resto
dipende da questa.

![Il pannello del blocco Trigger aperto: in cima le schede Manuale, Integrazione e Webhook, sotto i modi in cui parte un trigger Manuale](/_fern-img/ee4c031e943505dba257ce3dd766e521d309f72a3bef46a57c804241041e71d1.webp)

→ [Come si avvia un workflow](/avvio-workflow)

#### Premi Aggiungi e scegli il blocco

**Aggiungi**, in basso a destra, apre il pannello **Aggiungi nodi** con tre
categorie: **Agenti**, **Nodi**, **Integrazioni**. La ricerca in cima cerca
nella categoria aperta. Clicca il blocco che ti serve: compare sulla tela, e
lo sposti trascinandolo per l'intestazione.

![Aggiungi apre il pannello a destra; nella categoria Nodi bastano quattro lettere nella ricerca per ridurre l'elenco, il clic su Condizione mette il blocco sulla tela e un trascinamento lo porta accanto all'agente](/_fern-files/userbot-035249.docs.buildwithfern.com/fe08a0b82e94e872d0536f71c108e2ccf6352e09f5ae34a3bbef859d36a79d66/docs/assets/animazioni/workflow-aggiungere-blocco.gif)

→ [I blocchi disponibili](/blocchi)

#### Provalo da solo, subito

Passa sopra il blocco e premi **Esegui solo questo nodo**, il triangolo
nell'intestazione: gira solo quel blocco, senza far partire il flusso
intero. Nel pannello **Output** vedi esattamente cosa ha prodotto.

![Un blocco Agente con il pulsante Esegui solo questo nodo evidenziato nell'intestazione, accanto alla freccia del menu di esecuzione e ai tre puntini](/_fern-img/9d376dfc27531d831793a88ea766929fe287208cd9b66db00af1c887ded77dca.webp)

Se il blocco ha bisogno di dati che a monte non ci sono ancora, compila i
**Valore di test**: sono i valori con cui gira la prova.

#### Collega il blocco al precedente

Trascina dal punto di uscita di un blocco, sul suo bordo destro, fino
all'ingresso del successivo. Una Condizione ha un'uscita per ogni ramo.

![Dall'uscita Ordine o fattura della Condizione parte una linea che il puntatore porta fino all'ingresso di Rispondi al cliente: lasciato il mouse, il collegamento resta](/_fern-files/userbot-035249.docs.buildwithfern.com/3300f2e286e9214dc56753c1d6adb24840af4ffae9f75ddba44a83cec5b1ef5f/docs/assets/animazioni/workflow-collegare-blocchi.gif)

#### Dai al blocco un titolo che dica cosa fa

Clicca il titolo nell'intestazione del blocco e scrivilo: *Classifica la
richiesta* è più utile di *Agente 1* per chi rileggerà la tela fra sei mesi.

![Un blocco Agente con il titolo cliccato nell'intestazione viola: è diventato un campo, evidenziato, in cui scrivere il nome che dice cosa fa il blocco](/_fern-img/70c38c7b7a9105446a2a1535820f79befe67d106187a7534ea82eb4140b836b0.webp)

#### Prova l'intera catena

Quando il flusso è completo, eseguilo dall'inizio con dati realistici: la
freccia accanto al triangolo apre **Esegui solo questo nodo** ed **Esegui
workflow da qui**. Gira la bozza com'è sulla tela, con i valori di test che
hai compilato.

![Il menu di esecuzione aperto su un blocco Agente, con le due voci Esegui solo questo nodo ed Esegui workflow da qui](/_fern-img/5946e52a2d89ef9aaf01627aa1262692103488ed06f7cd4800b3f02338dcc3ac.webp)

**Non ancora attivo:** **Esegui workflow da qui** dovrebbe ripartire dal
blocco scelto. Oggi fa ripartire l'intero flusso dal Trigger, compresi i
blocchi a monte. Se a monte c'è qualcosa che invia o scrive, tienine conto.

Il builder salva da solo, poco dopo ogni modifica: non c'è un pulsante **Salva**
né un indicatore da controllare. Se passi a un altro workflow dal menu del
titolo mentre una modifica non è ancora salvata, ti chiede **Salvare le
modifiche?** e con **Salva e vai** salva prima di cambiare.

## Farsi aiutare dall'AI

**Crea con l'AI**, il pulsante con le scintille in basso a destra, apre una chat
accanto alla tela. Descrivi il flusso che vuoi o la modifica da fare (*«aggiungi
una condizione dopo il nodo selezionato»*, *«spiegami cosa fa questo flusso»*) e
l'AI ti propone le **Modifiche proposte**, blocco per blocco. **Applica** le
porta nella bozza, **Ignora** le scarta.

Quando un passaggio fallisce durante una prova, nella cronologia compare **Chiedi
all'AI**: apre la stessa chat con l'errore già descritto, e **Prova a
correggere** chiede una proposta di correzione. Le proposte vanno rilette come
qualunque modifica: l'AI vede la tela, non il sistema che stai chiamando.

## Come si passano i dati fra blocchi

Ogni campo di configurazione accetta due cose: un **valore fisso**, che scrivi tu
e resta uguale a ogni esecuzione, oppure un **riferimento** a un dato prodotto
prima, scritto fra doppie parentesi graffe. Puoi anche mescolarli nella stessa
riga: `Ticket {{hTTPRequest.output.body.id}} aperto`.

![Il pannello di un blocco Agente: nel campo Prompt una riga di istruzioni scritta a mano e, sotto, il riferimento al messaggio di partenza in verde. Anche il campo Allegati contiene un riferimento, e accanto a ogni campo c'è il pulsante Test](/_fern-img/a93dfaf5dce4dc6185d9593e0002011b6e1eef920004e31bf495501e1e7f1c9a.webp)

Il modo pratico per costruire un riferimento è **Inserisci contesto**: apre
l'albero dei dati disponibili (l'**Input Run** e i blocchi a monte) e cliccando
su un valore lo inserisce nel campo già scritto per bene.

Se un blocco a monte non ha mai girato, l'albero è vuoto: eseguilo una volta e i
suoi dati compaiono. Se richiami un dato che al momento dell'esecuzione non
esiste, il passaggio fallisce: meglio così che proseguire con un campo vuoto.

→ [La sintassi dei riferimenti](/riferimenti-dati)

## Il riferimento a un blocco non è il suo titolo

Questa è la cosa che fa perdere più tempo. Ogni blocco ha due nomi distinti.

* Il **titolo** è quello che leggi sulla tela. Lo cambi quando vuoi, serve alle
  persone.
* Il **riferimento** è l'identificatore con cui lo richiami nelle espressioni. È
  assegnato alla creazione, deriva dal **tipo** del blocco e non cambia più.

Un blocco HTTP request è `hTTPRequest`, una condizione è `condition`, un agente è
`agent`. Se ne aggiungi un secondo dello stesso tipo, prende un suffisso
numerico: `agent2`, `agent3`. Rinominare il blocco in *Classifica la richiesta*
non tocca niente di tutto questo: il riferimento resta `agent`.

La regola pratica: non scrivere i riferimenti a memoria e non dedurli dal titolo.
Usa sempre **Inserisci contesto**, che è l'unico modo per essere certo di quale
identificatore ha davvero quel blocco.

## Organizzare la tela

Una tela ordinata si rilegge in fretta, anche da chi non l'ha costruita.

* **Aggiungere un blocco dove serve.** Oltre al pulsante **Aggiungi**, puoi
  cliccare con il tasto destro sulla tela, oppure trascinare una connessione da
  un'uscita e lasciarla nel vuoto: il blocco che scegli compare lì, già
  collegato.
* **Note.** Il blocco **Nota**, nella sezione **Base**, è un commento sulla tela:
  non si collega e non gira mai. Serve a spiegare a chi viene dopo perché un
  ramo esiste. Si riduce a icona con **Riduci nota** e si riapre con **Espandi
  nota**.
* **Il menu del blocco.** I tre puntini di un blocco offrono **Disattiva nodo**
  (il blocco resta sulla tela ma non gira), **Sostituisci nodo**, **Duplica**,
  **Cancella output** ed **Elimina**. Per svuotare l'output usa questa voce: il
  pulsante **Cancella** nella parte bassa del blocco oggi elimina il blocco
  intero.
* **Le connessioni.** Una connessione selezionata mostra una piccola croce,
  **Elimina connessione**. Dopo una prova, le connessioni percorse diventano
  verdi.
* **La barra in basso.** **Mini mappa** mostra una vista d'insieme per spostarti
  sulle tele grandi. **Altre azioni** contiene **Guida**, **Schermo intero** e
  **Riordino automatico**, che ridispone i blocchi.
* **I pannelli laterali.** **Esecuzioni passate**, **Analytics** e
  **Impostazioni** si possono agganciare a sinistra, in basso o a destra; il
  browser ricorda la scelta.

Il titolo del workflow, in alto, apre l'elenco degli altri workflow: è il modo
più rapido per passare da un flusso all'altro. Accanto, **Opzioni workflow**
raccoglie **Rinomina**, **Fissa nella barra laterale**, **Attiva** o
**Disattiva**, **Duplica**, **Importa workflow (.json)**, **Esporta workflow
(.json)** ed **Elimina**.

## Provare senza fare danni

I blocchi che agiscono verso l'esterno (inviare email, chiamare un'API che
scrive, eseguire un'azione su un'app collegata) fanno sul serio anche durante le
prove.

> **Warning**
>
> Prima di eseguire un flusso completo che scrive da qualche parte, controlla
> destinatari e identificativi. Un workflow di prova che manda una email a un
> cliente vero è un errore che si nota.

Mentre costruisci, sostituisci i destinatari reali con i tuoi e rimettili solo
prima di pubblicare. Oppure tieni scollegato l'ultimo blocco finché il resto non
funziona: provi tutta la catena e non spedisci niente.

## Quando il flusso è pronto

Tutto quello che hai costruito finora vive in una **bozza**: non gira per
nessuno. Quando pubblichi una versione il workflow diventa attivo, e da lì chi
lo avvia esegue quella versione.

→ [Pubblicare e monitorare](/pubblicare-workflow)

## Errori frequenti

#### Il flusso finisce ma non fa niente

Guarda prima quali blocchi hai usato. **Codice** si prova con **Test**
nell'editor, ma durante un'esecuzione lascia passare i dati senza eseguire
il codice.

Se il flusso passa da una **Condizione**, controlla il ramo: quando nessun
ramo è vero il flusso si ferma lì, senza errori. Apri l'esecuzione e
verifica quali rami ha imboccato.
→ [I blocchi disponibili](/blocchi)

#### Il blocco successivo non trova i dati

Quasi sempre il riferimento punta a un identificatore che non esiste, perché
è stato scritto a mano o dedotto dal titolo del blocco invece che dal suo
tipo. Il messaggio di errore del passaggio fallito riporta il percorso che
non ha trovato. Riapri **Inserisci contesto** e riseleziona il valore.

L'altra causa è un campo che quel blocco produce solo in certi casi: il
percorso è giusto, ma quella volta il dato non c'era.

#### Funziona in prova e fallisce quando gira davvero

In prova i dati li scegli tu. Nella realtà arrivano campi vuoti, formati
diversi, elenchi più lunghi. Un percorso che non esiste fa fallire il
passaggio, quindi vale la pena provare anche il caso in cui il dato manca.
E ricorda che in servizio gira la versione pubblicata, non la bozza.

#### La tela è diventata illeggibile

Usa **Riordino automatico**, nel menu **Altre azioni** in basso. Se dopo il
riordino il flusso resta confuso, è il flusso a essere troppo grande: estrai
una parte in un altro workflow e richiamala con **Chiama workflow**.