Lezione 5: Collegare i pezzi: l'automazione che parte da sola

Obiettivi della lezione

Fino a qui la catena la fai partire tu: apri l'assistente, incolli, copi il risultato, lo porti dove serve. Funziona, e vale già una parte del risparmio. Adesso vediamo come toglierti anche quel copia e incolla, che nei processi frequenti è la metà del tempo rimasto.

Alla fine sei capace di:

• Descrivere qualunque automazione nella forma innesco e azioni;
• Scegliere lo strumento adatto fra quelli visuali, i fogli e il codice;
• Capire che cosa sono API e webhook, quanto basta per leggerne la documentazione;
• Inserire un passo di AI dentro una catena automatica e maneggiarne l'uscita;
• Riconoscere quando serve un agente e perché un agente vuole un cancello umano.

Innesco e azioni, sempre la stessa forma

Qualunque automazione, con qualunque strumento, ha questa forma: quando succede una cosa, fai queste altre cose in fila. Cambia il vestito, la sostanza no.

Gli inneschi si contano sulle dita:

• Arriva qualcosa: una mail, un messaggio, un file in una cartella, una risposta a un modulo.
• Cambia qualcosa: una riga nuova in un foglio, uno stato che passa da aperto a chiuso.
• È ora: ogni lunedì alle otto, ogni primo del mese.
• Qualcuno preme: un pulsante, un comando, una chiamata da un altro programma.

Le azioni sono altrettanto poche: leggere un dato, trasformarlo, scriverlo da qualche parte, mandare un messaggio, decidere fra due strade. Un passo di AI è un'azione di trasformazione come le altre: entra testo, esce testo.

Con che cosa si collega

Tre famiglie, e si sceglie in base a dove stanno già i tuoi dati.

Due avvertenze pratiche. La prima: gli strumenti visuali si pagano a operazione, quindi un processo che gira mille volte al mese cambia di prezzo rispetto a uno che gira cinquanta volte. La seconda: n8n si può installare su un proprio server, che è la strada di chi ha dati che preferisce tenere in casa.

E una terza strada, che in aula stupisce sempre: a volte basta una cartella condivisa con dentro un modello e una convenzione sui nomi dei file. Mi è capitato di arrivare con l'idea di collegare tre servizi e di uscire con una cartella e due regole scritte, che dopo un anno funzionavano ancora. Prima di montare cinque servizi, guarda se il problema si scioglie così.

API e webhook, spiegati corti

Un'API è la porta di servizio di un programma: un indirizzo a cui mandi una richiesta scritta in un formato prestabilito e che ti risponde con dei dati, di solito in JSON. Quando in uno strumento visuale scegli l'azione «aggiungi riga al foglio», dietro c'è una chiamata a un'API, con la differenza che l'hanno già scritta per te.

Un webhook è la stessa cosa al contrario: dai a un servizio un tuo indirizzo, e lui ti chiama quando succede qualcosa. Il modulo del sito che avvisa la tua automazione appena qualcuno lo compila funziona così. Il vantaggio è che nessuno deve stare a controllare ogni cinque minuti se è arrivato qualcosa.

Tre parole che ti servono leggendo qualunque documentazione:

• Chiave (o token): la password del programma che chiama. Si tiene fuori dai file che condividi, nelle impostazioni del servizio.
• Endpoint: l'indirizzo preciso della funzione che vuoi usare.
• Limite di chiamate: quante richieste al minuto ti concedono. Superarlo fa fallire i passi, in silenzio.

Il passo di AI dentro la catena

Dentro un'automazione, il passo di AI è un nodo che riceve del testo e ne restituisce dell'altro. Cambiano tre cose rispetto alla chat, e sono le tre che fanno fallire i primi tentativi.

Nessuno guarda la risposta. Quindi il formato d'uscita della Lezione 3 diventa obbligatorio, e in JSON: il nodo dopo deve poter prendere il campo che gli serve.

Il modello ogni tanto aggiunge frasi di cortesia. «Ecco il JSON richiesto:» davanti all'oggetto manda in errore la lettura. Si previene con l'istruzione esplicita («rispondi solo con l'oggetto JSON, senza testo attorno e senza blocco di codice») e si sopravvive con un controllo che, se la lettura fallisce, ferma la pratica e avvisa.

Ogni chiamata parte da zero. Il contesto che in chat era nella conversazione qui va messo nel messaggio: le istruzioni fisse della Lezione 4 vanno incollate nel nodo.

function elaboraRichieste() {
  const etichetta = GmailApp.getUserLabelByName('da-elaborare');
  const foglio = SpreadsheetApp.getActive().getSheetByName('Richieste');

  etichetta.getThreads(0, 10).forEach(function (thread) {
    const messaggio = thread.getMessages()[0];
    const dati = estraiConAI(messaggio.getPlainBody());
    if (!dati) return;                       // lettura fallita: si lascia li'
    foglio.appendRow([
      new Date(), dati.nome, dati.azienda, dati.contatto,
      dati.richiesta, dati.scadenza, dati.tono
    ]);
    thread.removeLabel(etichetta);
  });
}

Quindici righe, e fanno il grosso del lavoro di copia e incolla di un mese. La funzione estraiConAI è la chiamata al modello con il prompt della Lezione 3: prende il testo, restituisce un oggetto con i campi, oppure niente quando la risposta non si riesce a leggere.

Guarda l'ultima riga del ciclo: l'etichetta si toglie dopo che la riga è stata scritta. Se qualcosa fallisce prima, la mail resta etichettata e al giro successivo ci riprova. È il modo più economico di non perdere pratiche per strada.

Quando si parla di agenti

In una catena come quella qui sopra, il modello risponde e basta: il giro delle azioni l'hai deciso tu, passo per passo. Si parla di agente quando al modello dai degli strumenti (leggere una casella, scrivere in un foglio, cercare sul web) e lasci che sia lui a decidere quale usare e in che ordine, finché l'obiettivo è raggiunto.

Il modo standard di dare strumenti a un assistente si chiama MCP, ed è il protocollo con cui un'applicazione espone le proprie funzioni a un modello. In pratica: colleghi il tuo gestionale e poi puoi chiedere a parole di fare le cose che il gestionale sa fare.

La differenza pratica fra catena e agente si vede in due situazioni.

• Il processo è sempre uguale: conviene la catena. È prevedibile, si collauda, costa poco.
• Il percorso cambia ogni volta a seconda di quello che si trova: qui l'agente ha senso, perché scrivere tutti i rami sarebbe infinito.

Con gli strumenti in mano, però, un errore smette di essere una frase sbagliata e diventa un'azione sbagliata: una mail partita, una riga cancellata. Per questo un agente che può scrivere fuori vuole un cancello: le azioni che modificano qualcosa passano da un visto, almeno finché non hai qualche settimana di storico che ti dice che si comporta bene.

Il cancello, fatto fare a un classificatore

Il visto su ogni azione regge finché le azioni sono dieci al giorno. Gli strumenti di programmazione con l'AI hanno preso un'altra strada: prima che una chiamata parta, un secondo modello guarda che cosa sta per fare e la ferma se tocca qualcosa di serio. Passa il comando che legge un file, si ferma quello che cancella, manda o paga.

Con un classificatore come Jev, quello della Lezione 3, il cancello si monta anche fuori da quegli strumenti. In LangChain è un pezzo di mezzo da aggiungere all'agente, e sono tre righe:

from langchain.agents import create_agent
from langchain_typesafe.experimental.middleware import AutoModeMiddleware

guardrail = AutoModeMiddleware(tools=["bash"])
agent = create_agent("anthropic:claude-opus-5", middleware=[guardrail])

Lo stesso pezzo sa anche scegliere il modello: una domanda sul primo messaggio («è una ricerca semplice o un lavoro di architettura?») manda la richiesta al modello economico oppure a quello capace, e la probabilità con la sua confidenza restano leggibili nello stato dell'agente. Il pacchetto si chiama langchain-typesafe e vuole la sua chiave in TYPESAFE_API_KEY, fuori dal codice come tutte le altre.

Jev però è un servizio chiuso in lista d'attesa, quindi lo stesso cancello lo faccio girare con Bivio, la versione locale che trovi nella Lezione 3. Cambia che il modello sta sul tuo computer, quindi il comando che sta per partire non esce di casa:

from bivio import Bivio

guardia = Bivio()

def si_puo_fare(azione):
    r = guardia.decidi(azione, {
        "scrive": {"tipo": "si_no",
                   "istruzioni": "L'operazione modifica o cancella dati gia' esistenti"},
        "esce_dati": {"tipo": "si_no",
                      "istruzioni": "L'operazione manda dati fuori dall'organizzazione"},
    })
    return not (r["scrive"].valore or r["esce_dati"].valore)

si_puo_fare("SELECT nome FROM clienti WHERE citta = 'Livorno'")   # True
si_puo_fare("DELETE FROM ordini WHERE anno < 2024")               # False

La domanda costa un decimo di secondo e non si paga a token, e questa è la ragione per cui un cancello così si può mettere davanti a ogni chiamata invece che davanti a quelle che ti ricordi. L'esempio completo, con sei comandi da provare, sta in esempi/cancello_agente.py dentro al progetto.

Qui siamo dentro al codice. Se non programmi, tieni l'idea e chiedila a chi vi costruisce le automazioni: un cancello automatico davanti alle azioni costa poco e vale molto il giorno che un agente decide di cancellare la cartella sbagliata.

Laboratorio: la tua prima catena che parte da sola

Obiettivo: un'automazione che gira senza di te su un pezzo del tuo processo, con un punto di controllo.

Consegna

1. Scrivi la frase innesco e azioni del pezzo che vuoi automatizzare. Un pezzo solo: il più meccanico della catena della Lezione 3.
2. Scegli lo strumento guardando dove stanno i dati: dentro la suite che usi già, oppure uno strumento visuale se i servizi sono di fornitori diversi.
3. Monta l'innesco e verificalo da solo: quando arriva la cosa, la catena deve partire. Provalo prima di aggiungere il resto.
4. Aggiungi il nodo di AI con il prompt della Lezione 3, uscita in JSON, istruzione esplicita di rispondere senza testo attorno.
5. Aggiungi il controllo: se la lettura del JSON fallisce o un campo obbligatorio è vuoto, la pratica si ferma e ti arriva un avviso.
6. Aggiungi l'azione finale: la riga nel foglio, il file nella cartella, la bozza salvata.
7. Provala su dieci casi veri e tieni il conto: quanti sono passati puliti, quanti si sono fermati, quanti sono passati con un errore che non ha fermato niente. L'ultima colonna è quella che conta.

Mini-test di autoverifica

Sezione A: risposta multipla

1. La forma di qualunque automazione è:
   a) modello e prompt   b) innesco e azioni   c) entrata e uscita   d) cliente e fornitore
2. Un webhook serve a:
   a) chiamare tu un servizio   b) farti chiamare da un servizio quando succede qualcosa   c) conservare la chiave   d) leggere un foglio
3. Dentro una catena automatica, l'uscita del nodo di AI deve essere:
   a) discorsiva   b) in un formato prevedibile, di solito JSON   c) lunga   d) in tabella con i colori
4. «Ecco il JSON richiesto:» davanti alla risposta:
   a) aiuta la lettura   b) manda in errore il nodo successivo   c) è obbligatorio   d) riduce i costi
5. Una chiave API va tenuta:
   a) nel codice   b) nelle proprietà dello script o nelle variabili d'ambiente   c) in un foglio condiviso   d) nel prompt
6. Un agente si distingue da una catena perché:
   a) usa un modello più grande   b) sceglie da sé quali strumenti usare e in che ordine   c) costa meno   d) non serve collaudarlo

Sezione B: risposta aperta

7. (3 punti) Scrivi la frase innesco e azioni di un pezzo del tuo processo, indicando per ogni azione chi la esegue (servizio, AI, foglio, persona).
8. (3 punti) Nella tua catena, dove metteresti il controllo che ferma la pratica? Che cosa deve verificare e chi deve avvisare?

Riassunto della lezione