Come Ho Costruito un Sistema Multi-Agente per Generare Articoli SEO

Otto agenti AI specializzati, una pipeline sequenziale, cinque checkpoint di revisione umana. Il risultato: articoli SEO costruiti su dati reali dei competitor, non su template generici.

Tutti parlano di "generare contenuti con l'AI". Il problema è che la maggior parte degli approcci si riduce a un prompt singolo che produce testo generico - scollegato dai dati SERP, senza analisi della concorrenza, senza verifica della qualità. Il risultato? Contenuti che si assomigliano tutti e che Google ha imparato a riconoscere e penalizzare.

Ho costruito un sistema diverso. Un orchestratore che coordina 8 agenti specializzati: ognuno con un compito preciso, ognuno con il proprio set di tool, tutti collegati in sequenza. Si parte dalla keyword research e si chiude con un quality score automatico. In mezzo, scraping delle SERP, analisi strutturale dei competitor, generazione FAQ, strategia SEO, e produzione dell'articolo. Con revisione umana a ogni snodo critico.

Se hai letto il mio articolo sui workflow pattern per agenti AI nella SEO, questo è il caso pratico. Là descrivevo i pattern; qui mostro cosa succede quando li applichi a un progetto reale.

Perché un singolo prompt non basta per contenuti SEO

Un singolo prompt - anche lungo, anche ben ingegnerizzato - ha limiti strutturali quando l'obiettivo è produrre contenuti ottimizzati per il posizionamento.

• Nessun dato reale: il modello non sa quali sono i top 5 risultati per la tua keyword oggi, quante parole usano, che struttura di heading hanno
• Nessun contesto competitivo: senza analizzare cosa già rankka, stai scrivendo alla cieca
• Nessuna validazione: un prompt produce output e si ferma - non c'è chi controlla keyword density, lunghezza, copertura semantica
• Context window limitata: infilare keyword research, analisi SERP, strategia e generazione in un singolo prompt significa sacrificare profondità ovunque

Per questo ho scomposto ogni fase in un agente dedicato. Ogni fase della creazione di un contenuto SEO diventa un agente dedicato, con il suo prompt specializzato, i suoi tool, e un output strutturato che diventa l'input dell'agente successivo.

Architettura: 8 agenti in pipeline sequenziale

Il sistema segue un pattern sequential puro - ogni agente dipende dall'output del precedente. Ho scelto questo pattern anziché il parallel perché ogni fase arricchisce il contesto che la fase successiva consuma. Non puoi generare una strategia SEO senza aver prima analizzato i competitor.

Gli 8 agenti e i loro ruoli

Il flusso di revisione umana

Il sistema non è completamente autonomo - e per design. Ho inserito 5 checkpoint di revisione umana nei punti dove un errore a monte si propagherebbe a valle.

1. Dopo la keyword research - per validare che i cluster semantici siano rilevanti per l'intento dell'articolo
2. Dopo l'analisi strutturale - per verificare che i competitor analizzati siano effettivamente rilevanti
3. Dopo la generazione FAQ - per scartare domande irrilevanti o duplicate
4. Dopo la generazione dell'articolo - per revisione editoriale prima del quality check
5. Dopo il QA finale - approvazione definitiva o richiesta di revisione

Ogni checkpoint è asincrono: l'utente può approvare con "sì" o rifiutare. Un rifiuto ferma la pipeline e registra il punto esatto di interruzione, così il workflow può essere ripreso dalla fase corretta.

Cinque approvazioni manuali per articolo sono gestibili se produci 2-3 pezzi a settimana. Per volumi più alti, il sistema prevede che i checkpoint possano essere bypassati. Nella pratica, dopo 10-15 articoli sullo stesso dominio verticale, i checkpoint 1 (keyword) e 3 (FAQ) diventano quasi sempre approvazioni automatiche perché il sistema è già calibrato. Quelli che non puoi mai saltare sono il 4 (revisione editoriale) e il 5 (approvazione finale).

Un esempio concreto: dalla keyword all'articolo

Descrizioni astratte ne hai lette abbastanza. Ecco cosa succede realmente quando lancio la pipeline su una keyword. L'esempio è anonimizzato ma i numeri sono reali.

Input: keyword "consulenza SEO per e-commerce"

L'agente Keyword Research riceve la keyword principale e i dati di volume (720/mese, difficulty 38). Produce 4 cluster semantici: "consulenza SEO e-commerce" (core), "audit SEO e-commerce" (correlato), "SEO per Shopify/WooCommerce" (piattaforme), "ottimizzazione schede prodotto" (operativo). Checkpoint #1: approvo, i cluster coprono l'intento.

L'agente SERP Scraper trova i top 5: due agenzie, un blog tecnico, un articolo di Shopify, una guida di Semrush. Word count medio: 2.840 parole. L'agente Content Structure analizza le pagine: tutti e 5 hanno almeno 6 H2, 3 su 5 hanno tabelle, 4 su 5 hanno FAQ section.

L'agente Strategy produce: lunghezza raccomandata 3.408 parole (2.840 × 1.2). L'agente Content Generator produce l'articolo. L'agente QA dà score 84 (length score 91 × 0.6 + keyword score placeholder 85 × 0.4). Stato: approvato.

Tempo totale: 12 minuti di pipeline + 4 minuti di revisione umana sui 5 checkpoint. Il risultato è un articolo di 3.200 parole con struttura heading derivata dai competitor, FAQ generate dalle domande reali di Google, e meta tag entro i limiti.

Stack tecnologico

Perché OpenAI Agents SDK e non LangChain

Ho scelto l'OpenAI Agents SDK per tre motivi concreti. Primo: il decoratore @function_tool rende la definizione dei tool dichiarativa - ogni agente dichiara cosa può fare, e il framework gestisce il routing. Secondo: il Runner.run() gestisce il ciclo di vita dell'agente in modo pulito, con SQLiteSession per la persistenza automatica delle sessioni. Terzo: la validazione Pydantic è nativa - ogni output di agente è un BaseModel tipizzato, e il passaggio tra agenti è type-safe.

LangChain avrebbe funzionato, ma per un pipeline sequenziale con tool ben definiti, l'overhead di astrazione non era giustificato. Il sistema ha bisogno di prevedibilità, non di flessibilità.

Deep dive: i tre agenti che fanno la differenza

Agente #3: SERP Scraper - il dato reale

Questo agente è il cuore informativo del sistema. Usa il Bright Data SDK per fare scraping dei primi 5 risultati organici di Google per la keyword target. Per ogni risultato estrae: posizione, title tag, URL, meta description, e stima del word count.

Il valore non è nel singolo dato, ma nell'aggregazione. Quando l'agente SEO Strategy riceve questi dati, ha un quadro concreto di cosa Google premia per quella query: articoli lunghi o corti? Con FAQ? Con tabelle? Con struttura profonda (H2 → H3 → H4) o piatta?

Il fallback su Pyppeteer è fondamentale: circa il 15% delle pagine dei competitor ha protezioni anti-scraping che bloccano Bright Data. In quei casi, il browser headless riesce dove l'API fallisce.

Agente #4: Content Structure - la radiografia dei competitor

Le URL dei competitor passano a BeautifulSoup per un'analisi strutturale pura. Non guarda il contenuto - guarda la struttura. Estrae la gerarchia degli heading (quanti H2, quanti H3, come sono distribuiti), la presenza di tabelle, il numero di immagini, il word count esatto.

Il file del modulo include anche funzioni di analisi strutturale (_analyze_structure_patterns, _find_common_patterns, _generate_structural_recommendations) pensate per calcolare medie di word count, distribuzioni degli heading, e pattern comuni. Nell'implementazione attuale non sono ancora integrate nel flusso principale del tool agent, ma rappresentano il layer di analisi che intendo collegare nella prossima iterazione.

Agente #6: SEO Strategy - dove tutto si unisce

A questo punto la pipeline ha tutti i dati che servono. L'agente Strategy li sintetizza e produce il parametro chiave: la lunghezza raccomandata dell'articolo, calcolata come media dei competitor × 1.2. Il 20% in più è il margine che permette di trattare l'argomento più in profondità rispetto a chi già rankka.

Detto questo, la formula è grezza e lo so. Il word count è un proxy, non una metrica di qualità. Un competitor che rankka con 3.000 parole di contenuto denso e strutturato non è lo stesso di uno che rankka con 3.000 parole di filler. La media li tratta allo stesso modo, e il × 1.2 non distingue tra i due casi. Per keyword poco competitive, la formula funziona bene. Per keyword dove la qualità del contenuto conta più della quantità, il checkpoint umano #4 (revisione editoriale) è quello che compensa davvero.

Il data model prevede anche campi per keyword density target e struttura heading raccomandata (SEOAnalysis in Pydantic), ma nell'implementazione attuale il tool dell'agente produce solo la lunghezza target. È il punto dove il sistema ha più margine di crescita: collegare l'analisi strutturale dei competitor alla strategia renderebbe l'output del Content Generator molto più mirato.

Questa strategia diventa il brief per l'agente Content Generator. L'articolo generato deve rientrare nella lunghezza raccomandata. Il prompt dell'agente #7 istruisce anche su meta title sotto i 60 caratteri e meta description sotto i 160, anche se non c'è validazione automatica su questi limiti.

Il sistema di quality assurance

L'agente #8 è il gatekeeper. Riceve l'articolo generato e la strategia, e produce uno score composito su scala 0-100.

Onestamente, lo scoring è il punto più debole del sistema. Il length score funziona bene perché è un calcolo oggettivo. Il keyword score è un placeholder hardcoded a 85: l'analisi reale della densità e distribuzione keyword non è ancora implementata. È il prossimo pezzo da costruire.

Lo score determina lo stato:

• Approvato (80+): l'articolo è pronto per la pubblicazione
• Fix minori (65-79): piccoli aggiustamenti necessari
• Fix maggiori (<65): riscrittura necessaria - il contenuto non rispetta la strategia

In pratica, dopo decine di test, gli articoli che passano tutti e 5 i checkpoint umani arrivano quasi sempre sopra l'80. I problemi vengono intercettati molto prima del QA finale.

L'elefante nella stanza: il prompt dell'agente generatore

Ho descritto 8 agenti, tool, validazione Pydantic, checkpoint umani. Ma il fattore più determinante sulla qualità dell'output finale è uno solo: il system prompt dell'agente #7, il Content Generator. Ed è il pezzo di cui si parla meno, perché è il più difficile da ingegnerizzare.

Il modello (GPT-4.1 Mini, Claude, o qualsiasi altro) è un fattore. Ma qualsiasi LLM produce testo editorialmente piatto se il prompt non è specifico su tono, registro, struttura argomentativa, e anti-pattern da evitare. "Scrivi un articolo SEO su X" produce slop. "Scrivi un articolo in prima persona con tono pratico, evitando le formule [lista esplicita], con hook nel primo paragrafo e una sezione di limiti onesti" produce qualcosa di diverso.

Nell'implementazione attuale, il prompt dell'agente #7 riceve la strategia (lunghezza target), le FAQ generate, e la keyword principale. Istruisce il modello su meta title < 60 caratteri e meta description < 160. Ma non specifica tono di voce, non ha esempi di output desiderato, e non ha una lista di anti-pattern editoriali. Il risultato: articoli strutturalmente corretti ma editorialmente generici. Servono sempre 30-40 minuti di editing umano post-pipeline.

Il prossimo investimento serio su questo sistema non è nel QA o nella parallelizzazione. È nel prompt engineering dell'agente #7. Few-shot examples da articoli approvati, brand voice guidelines codificate nel prompt, e una lista di "frasi vietate" che eliminino lo slop alla radice. Senza quello, tutto il resto è infrastruttura che serve un generatore mediocre.

Pydantic come contratto tra agenti

Ogni agente comunica con il successivo tramite modelli Pydantic tipizzati. Non stringhe, non JSON libero: BaseModel con campi obbligatori e tipi specifici.

Nella pratica, questo cambia il modo in cui lavori con la pipeline:

1. Se un agente produce output malformato, il sistema fallisce subito - non propaga errori silenziosi downstream
2. Il passaggio tra agenti è documentato dal codice stesso - leggendo i modelli Pydantic capisci esattamente cosa entra e cosa esce da ogni fase
3. Il debugging è triviale: quando qualcosa non funziona, sai esattamente quale agente ha prodotto output non valido e quale campo era sbagliato

I modelli principali - Keyword, SerpResult, ContentStructure, FAQ, SEOAnalysis, ArticleOutput - formano una catena di dipendenze che rispecchia il flusso della pipeline. La ProjectSession li contiene tutti, registrando lo stato completo del workflow.

Persistenza del workflow e ripresa da interruzioni

Ogni esecuzione della pipeline crea una sessione SQLite. Ogni output di agente viene serializzato e salvato progressivamente. Se il workflow viene interrotto - per un rifiuto a un checkpoint, un errore di rete, o semplicemente perché l'utente deve fermarsi - lo stato è preservato.

Questo significa che un workflow su una keyword competitiva, che può richiedere 10-15 minuti di scraping e analisi, non perde lavoro. La ProjectSession registra timestamp, stato di ogni agente, e punto esatto di interruzione.

L'output finale è un file JSON con la struttura completa: ArticleOutput (articolo + meta tag + score) + ProjectSession (tutti i dati intermedi). Tutto tracciabile, tutto riproducibile.

Risultati e lezioni apprese

Cosa funziona bene

• La pipeline produce articoli che rispettano la struttura dei competitor in modo consistente - non ogni tanto, ma sistematicamente
• I 5 checkpoint umani catturano problemi che il QA automatico non rileva: tone of voice sbagliato, sezioni irrilevanti, keyword stuffing sottile
• La persistenza via SQLite ha salvato il workflow decine di volte - soprattutto quando Bright Data ha timeout sulle SERP più competitive
• Pydantic ha eliminato una classe intera di bug: nessun errore silenzioso da JSON malformato tra agenti

Cosa migliorerebbe

• GPT-4.1 Mini è buono per task strutturati ma non eccelle nella qualità editoriale italiana - un modello con training più forte sull'italiano (come Claude) migliorerebbe l'output dell'agente #7
• Il pattern sequential aggiunge latenza: 8 step in serie significano 10-15 minuti per articolo. Gli step 2 e 3 (Google Suggest e SERP) potrebbero essere parallelizzati senza perdere coerenza
• Lo scoring del QA è ancora primitivo: il keyword score è un placeholder fisso, le funzioni di analisi strutturale esistono nel codice ma non sono collegate al pipeline. Il QA in pratica valuta solo la lunghezza
• Il sistema non ha memory cross-sessione: ogni articolo parte da zero, senza apprendere dai pattern degli articoli precedenti approvati

Il vero vantaggio: struttura, non velocità

Un copywriter esperto scrive più in fretta. Ma il sistema garantisce consistenza su ogni articolo: analisi dei competitor reali, struttura derivata dai dati, lunghezza calibrata sui competitor, e revisione umana a ogni snodo critico. Non "a volte". Sempre.

Quello che il sistema fa davvero è codificare in step ripetibili e controllabili le decisioni che un SEO prende a intuito. I checkpoint umani servono a questo: portare l'esperienza dentro un processo che altrimenti vola in automatico.

Prossimi passi

Alcune evoluzioni sono già in fase di prototipazione.

1. Parallelizzazione parziale: gli agenti Google Suggest e SERP Scraper possono lavorare in parallelo, riducendo il tempo totale del 20-25%
2. QA semantico: integrare un embedding model per misurare la copertura delle entità rilevanti nell'articolo, non solo la densità delle keyword
3. Memory cross-sessione: salvare gli articoli approvati e usarli come few-shot examples per l'agente Content Generator, migliorando la qualità editoriale nel tempo

Se vuoi approfondire i pattern di orchestrazione che stanno dietro a questo sistema, leggi il mio articolo su workflow pattern per agenti AI nella SEO. E se ti interessa l'architettura multi-agente a livello più generale, il

paper sugli Agent Teams in Claude Code copre il tema in modo approfondito.

Se invece ti interessa come l'AI si applica alla ricerca su cataloghi prodotto, il paper su RAG per cataloghi prodotto analizza un problema diverso (retrieval, non generazione) con lo stesso approccio critico.