In questa guida non ci limiteremo alla teoria. È il momento di applicare la filosofia del dogfooding: useremo come caso studio il sito stesso che stai leggendo in questo momento. La sezione /guide/ di The Automation Society non è nata da un processo di copia-incolla manuale su un CMS, ma è il risultato di un'architettura di automazione avanzata che unisce pianificazione didattica, intelligenza artificiale generativa e sistemi di controllo qualità (Human-in-the-loop).

In questo capitolo avanzato analizzeremo l'infrastruttura tecnica di questo sistema, spiegando come strutturare i dati, come forzare i modelli linguistici (LLM) a rispettare formati rigidi e come distribuire il contenuto in modo sicuro.

---

L'Architettura del Sistema: I 4 Pilastri

Per evitare il classico problema dei contenuti generati dall'AI (ovvero testi generici, ripetitivi e privi di formattazione coerente), abbiamo progettato un sistema modulare diviso in quattro fasi distinte:

  1. La Sorgente di Verità (Notion): Un database relazionale dove risiede la roadmap didattica, con metadati precisi (Capitolo, Difficoltà, Target SEO, Stato).
  2. L'Orchestratore (n8n): Il motore che gestisce i flussi di lavoro, recupera i dati, effettua le chiamate API e coordina i passaggi.
  3. L'AI Engine (OpenAI API con Structured Outputs): Il modulo che genera il contenuto. Non usiamo prompt generici, ma schemi JSON rigidi per garantire che l'output sia perfettamente compatibile con il nostro codice.
  4. Il Canale di Deploy (GitHub & Vercel): Una volta approvato, il contenuto viene trasformato in un file Markdown/HTML e pushato nel nostro repository, attivando una build automatica.

Vediamo nel dettaglio come funzionano i passaggi più critici di questa pipeline.

---

1. La Gestione dello Stato e Context Injection

Un errore comune è chiedere all'AI di "scrivere un articolo sul no-code". Il risultato sarà inevitabilmente superficiale. Nel nostro sistema, l'orchestratore non invia solo il titolo del paragrafo, ma inietta nel prompt un contesto estremamente ricco recuperato dinamicamente dal database:

  • Livello di difficoltà (calcolato sul numero del capitolo): Se il capitolo è < 3, il sistema istruisce il modello a spiegare ogni singolo acronimo. Se è > 6 (come questo), assume che il lettore conosca già concetti come API, webhook e payload.
  • Linee guida di stile (Style Guide): Un blocco di testo statico iniettato in ogni chiamata che definisce il tono di voce (didattico, pragmatico, senza fuffa marketing).
  • Evitare duplicati: L'orchestratore interroga il database per recuperare i titoli dei capitoli precedenti e successivi, dicendo all'AI: "Non trattare questi argomenti, focalizzati esclusivamente su X".

---

2. Generazione con Structured Outputs (JSON Schema)

Per integrare l'AI in una pipeline software, non possiamo accettare testo libero (Markdown generico). Abbiamo bisogno che l'API ci restituisca un oggetto JSON perfetto, contenente esattamente i campi richiesti dal nostro front-end (titolo, excerpt, tag, meta description, corpo HTML).

Per fare questo, sfruttiamo la funzionalità di Structured Outputs di OpenAI, definendo uno schema JSON rigoroso durante la chiamata API. Se il modello tenta di restituire un formato diverso, l'API stessa rifiuta la risposta e lo costringe a correggersi.

Ecco la struttura concettuale dello schema che inviamo all'API:

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "excerpt": { "type": "string" },
    "meta_title": { "type": "string" },
    "meta_description": { "type": "string" },
    "html": { "type": "string" },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["title", "excerpt", "meta_title", "meta_description", "html", "tags"]
}

---

3. Il Guardrail: Human-in-the-Loop (HITL)

La completa automazione della scrittura è un mito pericoloso. La qualità richiede l'intervento umano. Nel nostro flusso, il contenuto generato dall'AI non va mai direttamente online.

Quando l'AI termina la generazione, l'orchestratore:

  1. Salva la bozza all'interno di una pagina di review (su Notion o Airtable).
  2. Invia una notifica su Slack al team editoriale con un link diretto per la revisione.
  3. Attende che lo stato della pagina passi da "In Review" ad "Approvato".

Solo quando un editor umano cambia lo stato in "Approvato", un secondo webhook si attiva per avviare la fase di pubblicazione.

---

Esercizio Pratico: Configurare una chiamata API con Output Strutturato

In questo esercizio simuleremo la parte centrale del nostro sistema: una chiamata HTTP all'API di OpenAI per generare la struttura di una lezione, forzando l'output a rispettare un JSON Schema preciso.

Prerequisiti

  • Una chiave API di OpenAI.
  • Un client HTTP (come Postman, Hoppscotch) o un nodo "HTTP Request" su n8n/Make.

La Richiesta API (Payload)

Imposta una richiesta POST verso l'endpoint https://api.openai.com/v1/chat/completions con i seguenti Header:

  • Content-Type: application/json
  • Authorization: Bearer TUA_API_KEY

Utilizza il seguente corpo della richiesta (Payload JSON). Nota l'utilizzo del parametro response_format impostato su json_schema:

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "Sei un autore tecnico. Scrivi una breve lezione sul concetto di Webhook. Rispondi esclusivamente in formato JSON seguendo lo schema richiesto."
    },
    {
      "role": "user",
      "content": "Genera la lezione sui Webhook."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "lesson_generation",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "titolo": {
            "type": "string"
          },
          "concetto_chiave": {
            "type": "string"
          },
          "esempio_pratico": {
            "type": "string"
          }
        },
        "required": ["titolo", "concetto_chiave", "esempio_pratico"],
        "additionalProperties": false
      }
    }
  }
}

Cosa succede ora?

Inviando questa richiesta, l'LLM non risponderà con del testo libero introduttivo (es. "Ecco la lezione richiesta: ..."). Riceverai un JSON puro, validato sintatticamente, pronto per essere mappato nei passaggi successivi della tua automazione o inserito direttamente nel tuo database di produzione.

Questo approccio strutturato è ciò che trasforma un semplice chatbot in un componente software affidabile per la tua azienda.