Workflows
Un workflow è una mappa visuale di ciò che il tuo agente deve fare passo dopo passo — chi parla per primo, cosa chiedere, quando ramificare, quando trasferire la chiamata e quando passarla a un altro agente. Lo costruisci su un canvas posizionando nodi e collegandoli.
Usa un workflow quando un singolo prompt non basta — quando la chiamata ha fasi chiare («prima qualificare, poi raccogliere i dettagli, poi prenotare o trasferire»), quando ti serve un routing deterministico in base alle risposte del chiamante (non «di solito l'AI ci arriva»), o quando un agente dovrebbe passare una parte del lavoro a uno specialista.
Un prompt è una lunga istruzione. L'agente la legge una volta e la usa per tutta la chiamata. Un workflow è tante piccole istruzioni, una per nodo, con transizioni esplicite tra loro. Il grafo guida la chiamata — l'agente di ogni nodo possiede solo la sua porzione.
Se il tuo agente già funziona bene con un singolo prompt, non ti serve un workflow. Passa ai workflow quando inizi ad accumulare regole «se X allora Y» nel prompt e non sono più affidabili.
L'editor
L'editor di workflow vive nella sua scheda dedicata nella pagina dell'agente. Vedi un canvas con un nodo Start e un nodo End di default. Aggiungi nodi dalla toolbar, li trascini sul canvas e li colleghi con archi.
Il pannello a destra cambia in base a ciò che selezioni:
- Clic su un nodo — apre il suo pannello di impostazioni (prompt, campi, variabili di estrazione, ecc.).
- Clic su un arco — apre le impostazioni del suo trigger (AI decides / Condition / Always).
- Il pannello Variables (pulsante nella toolbar) elenca ogni variabile del workflow con salto in un clic al nodo che la imposta o la legge.
Esegui una Test Call nel browser direttamente dall'editor — una lucciola luminosa segue la posizione in tempo reale per farti vedere esattamente quale nodo è attivo in ogni momento.
I workflow hanno tre stati:
- Draft — modificabile, non ancora live. Usa Test Call per provarlo.
- Active — live per chiamate reali. L'agente usa questo workflow dalla prossima chiamata.
- Template — template riutilizzabile, mai legato direttamente a un agente. Puoi istanziarlo su più agenti.
Nodi
Ogni nodo è un passo nella conversazione. Tipi di nodi diversi fanno cose diverse — alcuni parlano, altri ascoltano, altri instradano, altri eseguono strumenti.
Agent
Il nodo Agent è il cuore di una fase del workflow. Quando il grafo arriva a un nodo Agent, quell'agente prende la parola e guida la conversazione finché qualcosa non scatena una transizione.
Configuri la personalità e il compito del nodo Agent direttamente sul canvas (la tab Prompt si apre cliccando sul nodo) — questo è il prompt per quella porzione di conversazione, non per l'intera chiamata. Puoi anche allegare basi di conoscenza e strumenti per nodo.
Greeting — la riga di apertura. Se questo è il nodo di ingresso (la prima tappa dopo Start), questa è la prima cosa che il chiamante sente.
Quando un grafo governa una chiamata, il prompt principale dell'agente (quello nella tab Model) viene sostituito dal prompt del nodo attivo. È voluto — il grafo possiede la personalità e il compito per fase, non un singolo prompt fisso in competizione.
Subagent
Un subagent è un aiutante che gira inline — prende la conversazione per un compito specifico, poi restituisce il risultato a chi l'ha invocato.
I subagent funzionano bene quando un pezzo di lavoro è riutilizzabile o sembra distinto: «verifica l'identità del chiamante», «raccogli l'indirizzo di spedizione», «qualifica un lead con il metodo SPIN». L'agente padre chiama il subagent, il subagent fa il suo, riporta un risultato, il padre riprende da dove aveva lasciato.
I nodi Subagent hanno le stesse tab di un nodo Agent (Prompt, Knowledge, Tools, Actions) — l'editor crea automaticamente un agente backing nascosto per te. Non vedi questo agente nascosto nella tua lista principale e non conta verso il limite di agenti del tuo piano.
Return variable — il campo dove memorizzare il risultato del subagent (es. identity_verified, lead_score).
Message (Say)
Il nodo Say dice una riga fissa — niente turno AI, niente improvvisazione. Usalo per transizioni («Un attimo, la trasferisco…»), avvisi legali obbligatori o conferme predefinite dove le parole contano.
Text — cosa dire. Supporta token {{variable}} per iniettare valori catturati, es. "Grazie {{first_name}}, ti ho prenotato per le {{appointment_time}}."
Un nodo Say consuma il turno — l'agente non aggiungerà niente sopra.
Gather Input
Un nodo Gather Input pone una domanda e cattura la risposta del chiamante in una variabile.
Prompt — la domanda da fare. Supporta {{tokens}}.
Variable — il nome del campo dove memorizzare la risposta.
Usalo ogni volta che ti serve un valore concreto prima di proseguire — email, numero di conto, numero di persone, categoria del problema. Il prossimo turno del chiamante diventa il valore; puoi ramificare su di esso con un arco Condition subito dopo.
Update State
Un nodo Update State scrive uno o più valori nelle variabili del workflow senza parlare né chiedere. Usalo per pre-impostare default, marcare flag di avanzamento o comporre valori da passi precedenti.
Variable / Value — una coppia chiave-valore. More variables (optional) — coppie chiave-valore aggiuntive.
Sia le chiavi che i valori supportano {{tokens}}, quindi puoi comporre nuovi valori a partire da esistenti.
Condition
Il nodo Condition è un nodo di solo routing — non parla, non chiede, manda semplicemente la chiamata sul ramo in uscita che fa match.
La condizione stessa vive su ogni arco in uscita, non sul nodo — vedi archi Condition sotto.
Usa un nodo Condition quando vuoi un punto chiaro di «fan-out» nel tuo grafo: molti rami che dipendono dal valore di una variabile. Rispetto a mettere condizioni sugli archi dei nodi Agent, un nodo Condition dedicato rende la logica di routing visivamente ovvia.
Tool
Il nodo Tool esegue uno degli strumenti collegati dell'agente come passo del grafo — senza che l'AI dica la sua sulla chiamata. Usalo quando vuoi un fatto, non una conversazione: «cerca questo cliente», «controlla lo stock», «GET del meteo attuale».
Puoi:
- Scegliere uno degli strumenti esistenti dell'agente (lookup calendario, ricerca in una knowledge base, azione specifica di un'integrazione), o
- Configurare una chiamata HTTP inline direttamente nel nodo (URL, metodo, header, parametri, body).
La risposta dello strumento diventa disponibile a tutti i nodi a valle. Se la risposta è un oggetto JSON, ogni campo di primo livello diventa la propria variabile — una risposta come {"is_known": true, "tier": "gold"} scrive sia is_known sia tier perché tu possa ramificare su di essi.
Ogni campo testo nel nodo Tool — URL, valori header, body — supporta {{tokens}}. Infila una variabile in un path URL, in un header o in un body senza scrivere codice.
Se una chiamata strumento fallisce (errore HTTP, timeout, rete), il nodo logga il fallimento e il grafo prosegue — senza i dati. Pianifica le tue condizioni a valle per gestire il caso «nessun valore».
Integration
Il nodo Integration è una variante focalizzata di Tool, per servizi esterni collegati — Google Calendar, Outlook, HubSpot. Scegli il provider e l'azione specifica (es. check_availability, create_event), passi i parametri, e il nodo chiama l'integrazione in modo deterministico.
Se l'integrazione non è collegata su questo agente, il nodo passa senza fare nulla — il tuo grafo continua. Controlla le condizioni a valle per il caso «non è girata».
Phone Transfer
Il nodo Phone Transfer trasferisce la chiamata (warm transfer) a un numero telefonico esterno. Dopo un trasferimento riuscito, la chiamata ha lasciato il tuo workflow — il tuo agente non è più in linea.
Number — destinazione in formato internazionale con il + iniziale (es. +15551234567). Supporta {{tokens}} così la destinazione può venire da un passo precedente (es. la risposta a «con quale ufficio vuole essere messo in contatto?»).
Se il trasferimento non va a buon fine (numero invalido, nessuna risposta, connessione telefonica non configurata), il grafo torna indietro e l'agente attuale resta in linea. La conversazione prosegue normalmente — l'agente può scusarsi e provare un altro percorso.
End Call
Il nodo End Call chiude — l'agente dice la frase di chiusura configurata e poi riaggancia. Usalo come terminus pulito per rami «tutto fatto» o per il ramo «non possiamo aiutare, ci dispiace» da una Condition difficile.
Non richiede configurazione oltre a un arco in entrata.
Riusare un workflow (Sub-workflow)
Il nodo Sub-workflow è riservato per incorporare un altro workflow come sotto-grafo. Questo nodo è nell'editor ma non è ancora completamente cablato — il grafo lo attraversa senza fare nulla. Non affidarti a esso per chiamate in produzione. Lo attiveremo quando rilasceremo i sotto-grafi riutilizzabili.
Archi (Connessioni)
Colleghi un nodo al successivo con un arco. Il trigger dell'arco decide quando la transizione scatta.
Ci sono tre trigger:
| Trigger | Chi decide | Quando scatta |
|---|---|---|
| AI decides | L'AI | Quando la conversazione lo rende il prossimo passo naturale. L'AI riceve uno «strumento di transizione» che può chiamare. |
| Condition | Il runtime | Quando una variabile fa match con una regola che hai scritto. Valutato prima che l'AI risponda. |
| Always | Il runtime | Incondizionatamente — appena il nodo sorgente finisce. Nessun input del chiamante, nessuna AI. |
AI decides (basato sull'intenzione)
Usa AI decides quando solo l'AI può decidere quando cambiare — «se il chiamante chiede dei prezzi, trasferisci all'agente vendite», «se sembra un reclamo, esegui il subagent scuse».
Scrivi una breve descrizione di intent sull'arco (es. «Il chiamante chiede dei prezzi o vuole fare upgrade»). L'AI lo vede come uno strumento etichettato con quell'intent e decide se chiamarlo in base alla conversazione. Se sono presenti più archi AI-decides, l'AI ne sceglie al massimo uno per turno.
Condition (branching deterministico)
Usa Condition quando vuoi che il grafo — non l'AI — decida in base a un fatto noto: «se lead_score > 7, manda al closer; altrimenti, termina educatamente».
Le Condition sono valutate prima che l'AI risponda, quindi vincono sempre sull'AI in quel turno. L'AI non può scavalcare una condizione che fa match.
Puoi costruire una condizione con questi operatori:
| Operatore | Significato | Esempio |
|---|---|---|
| equals | match esatto (case-insensitive per il testo) | intent equals "billing" |
| not equals | non fa match | status not equals "active" |
| contains | match di sottostringa (case-insensitive) | feedback contains "broken" |
| greater than | numerico > | lead_score greater than 7 |
| less than | numerico < | wait_minutes less than 5 |
Puoi anche combinare clausole con All (tutte devono fare match — AND) o Any (almeno una deve fare match — OR), e annidarle. Una regola come «il chiamante è conosciuto e il suo tier è gold o premium» diventa:
All:
- is_known equals true
- Any:
- tier equals gold
- tier equals premium
Se referenzi una variabile non ancora impostata (es. l'AI non l'ha mai raccolta), le condizioni su di essa falliscono sempre — nessun errore, semplicemente non fa match. Quindi loyalty_tier equals "gold" torna falso se loyalty_tier non è mai stato impostato. Progetta i tuoi rami per gestire questo — di solito con un ramo else (vedi sotto).
Ramo else — quando nessuna condizione fa match
Se hai più archi Condition in uscita da un nodo e nessuno fa match, la chiamata cade sull'arco non-Condition di priorità più bassa (Always o un arco AI-decides). Se non c'è alcun fallback, l'AI riprende il controllo e può proseguire liberamente.
Pattern comune: più Condition per i percorsi noti, più un arco Always verso un catch-all (dire qualcosa, poi End Call o trasferire).
Always (auto-advance)
Usa Always quando il passo successivo è incondizionato — nessuna decisione, nessun input chiamante. Due usi naturali:
- Concatenare passi: SAY → UPDATE_STATE → SAY → TOOL → Condition. Ogni passo finisce e l'arco Always avanza immediatamente.
- Auto-avanzare dopo che l'agente finisce di parlare: un nodo Agent con un arco Always in uscita significa «appena l'AI smette di parlare, avanza» — senza bisogno che il chiamante risponda. Utile per flussi a monologo come un agente presentatore che consegna e passa alla prossima sezione.
Condition e Always (i deterministici) vincono sempre su AI decides. Se una Condition fa match, gli strumenti di transizione dell'AI sono ignorati in quel turno. Questo ti permette di scrivere regole che l'AI non può scavalcare.
Variabili
Le variabili sono la memoria del workflow. La maggior parte delle cose in un workflow sono o impostare una variabile o leggerne una.
Dichiarare variabili
Il pannello Variables (pulsante nella toolbar) mostra ogni variabile del workflow con i passi che la impostano o leggono. Clicca una variabile per saltare a un setter; è il modo più veloce per trovare dove qualcosa va storto.
Puoi dichiarare una variabile con un valore di default nel pannello — utile per flag come escalated=false che devono esistere fin dall'inizio così che le tue condizioni non manchino silenziosamente per «assenza».
Come si impostano le variabili
| Fonte | Esempio |
|---|---|
| Default (dichiarati nel pannello Variables) | escalated = false impostato prima dell'inizio della chiamata |
| Gather Input | La risposta parlata del chiamante viene catturata nella variabile del nodo |
| Update State | Scrivi un valore (letterale o composto con {{tokens}}) direttamente |
| Risultato Tool / Integration | L'intera risposta è memorizzata sotto il nome del nodo; se la risposta è un oggetto JSON, ogni campo di primo livello diventa anche la propria variabile |
| Return di Subagent | Ciò che il subagent finalizza viene memorizzato nella variabile di ritorno del nodo subagent |
Leggere variabili — {{tokens}}
Ovunque tu possa scrivere testo in un nodo — prompt di Agent, testo di Say, prompt di Gather, URL/body/header di Tool, numero di Phone Transfer, valore di Update State, valori di condizione — puoi infilare {{variable}} e verrà sostituito a runtime.
I path puntati funzionano anche per dati annidati — es. se una risposta di Tool era {"customer": {"name": "Anna", "tier": "gold"}}, puoi leggere {{customer.name}} o {{customer.tier}}.
Se un token referenzia una variabile che non esiste, il testo letterale {{name}} viene lasciato così com'è (non sbiancato). È intenzionale — rende i template rotti facili da individuare in una test call, invece di ingoiarli silenziosamente.
Pattern comuni
Qualifica → Ramifica → Instrada
Start
└─ Agent (greeting + qualify)
└─ Gather Input (intent)
└─ Condition: intent == "sales" → Agent (sales)
└─ Condition: intent == "support" → Subagent (triage)
└─ Always (catch-all) → Say "Let me connect you" → Phone Transfer
Cerca → Personalizza
Start
└─ Tool (CRM lookup, writes is_known, name, tier)
└─ Condition: is_known == true → Agent (warm greeting with {{name}})
└─ Always (else) → Agent (cold greeting)
Helper riutilizzabile (Subagent side-trip)
Agent (main conversation)
└─ AI decides: "Caller mentions an address" → Subagent (address collector)
└─ on finish: result = full_address
└─ Agent continues with {{full_address}}
Cosa è bloccato durante una chiamata pilotata da workflow
Alcuni default cambiano quando un grafo governa la chiamata:
- La lingua è bloccata su quella usata dal primo agente del workflow. L'AI non può cambiare lingua a metà chiamata. Questo previene che il modello derivi verso la lingua sbagliata in un turno rumoroso.
- Il prompt principale dell'agente è sostituito dal prompt del nodo attivo. È la regola «il grafo possiede la persona» — vedi warning sotto Agent.
- Il primo messaggio viene dal greeting del nodo di ingresso, non dal campo «Begin Message» dell'agente.
Sicurezza anti-loop — Step Budget
Ogni workflow ha un numero massimo di transizioni per chiamata (di default 25). Ogni volta che il grafo passa a un nuovo nodo, il contatore cala di uno. Quando arriva a zero, il workflow smette di saltare tra i nodi per prevenire loop fuori controllo. Puoi scegliere un nodo di fallback per questo caso (tipicamente un Phone Transfer o un End Call) — la chiamata viene deviata lì una volta esaurito il budget.
Raramente devi pensarci — è una rete di sicurezza per grafi che accidentalmente loopano. Se lo raggiungi in uso normale, probabilmente hai un ciclo da qualche parte.
Testare
Il pulsante Test Call dell'editor apre una chiamata browser con il draft attuale del workflow. Mentre gira, una lucciola luminosa si muove tra i nodi del canvas per farti vedere esattamente dov'è la chiamata. L'editor è bloccato durante una test call per impedire che le modifiche desincronizzino lo stato live.
Usa Test Call per verificare:
- Le tue condizioni matchano i valori che ti aspetti (guarda se la lucciola salta un ramo che pensavi sarebbe scattato).
- I tuoi token sono sostituiti correttamente (ascolta un
{{name}}rimasto appeso se un valore non era stato impostato). - I fallimenti degli strumenti degradano con grazia (la tua rotta fallback scatta davvero).
Fallimenti da conoscere
| Situazione | Cosa succede |
|---|---|
| Chiamata Tool / Integration fallisce | Il grafo continua senza i dati. Le tue condizioni a valle dovrebbero gestire la variabile assente. |
| Phone Transfer fallisce (numero invalido, nessuna risposta, connessione telefonica assente) | Il grafo torna indietro, l'agente attuale resta in linea, e la conversazione prosegue normalmente. |
| Subagent non parte | La deviazione viene annullata, l'agente padre resta in linea, e viene pronunciata una breve riga di fallimento. |
{{missing_variable}} nel testo | Lasciato letterale in output — facile da individuare in test call. |
| Nodo Sub-workflow | Attualmente lo attraversa senza fare nulla. Non affidarti a esso per ora. |
| Step budget esaurito | Devia al nodo di fallback se ne è impostato uno, altrimenti l'AI riprende il controllo. |
Quando NON usare un Workflow
I workflow sono potenti ma non sono la risposta giusta per ogni agente. Rimani con un singolo prompt quando:
- La conversazione è aperta («rispondere alle domande del chiamante sui nostri prodotti»).
- Non hai logica di branching chiara — la maggior parte delle decisioni sono giudizi che l'AI gestisce bene.
- Scriveresti solo un nodo Agent e un End Call — è solo un prompt con passi extra.
Passa a un workflow quando:
- Puoi abbozzare la chiamata come un diagramma di flusso con tre o più fasi distinte.
- Ti serve almeno un branching deterministico su una variabile (una Condition).
- Vuoi riusare un pezzo di conversazione tra più agenti (un subagent).
- Stai già accumulando regole «se il chiamante dice X allora fa Y» in un prompt e non sono affidabili.