Report AI per WordPress: Come Abbiamo Costruito il Sistema di Analisi in AgencyPilot [2026]

Gestire decine di siti WordPress per conto dei clienti significa produrre report ogni mese: uptime, aggiornamenti, performance, sicurezza. Per anni lo abbiamo fatto a mano — o con template fissi che dicevano sempre le stesse cose. Poi abbiamo integrato Claude API in AgencyPilot e il flusso è cambiato radicalmente.

In questo articolo raccontiamo come funziona il sistema di report AI per WordPress che abbiamo costruito internamente, quali decisioni tecniche abbiamo preso e cosa ha funzionato (e cosa no) in produzione.

TL;DR: Abbiamo collegato i dati aggregati dei siti WordPress (uptime, Core Web Vitals, aggiornamenti plugin, scan sicurezza) all’API di Claude per generare report narrativi personalizzati per ogni cliente. Tempo medio di produzione di un report: da 45 minuti a 3 minuti. Qualità percepita dai clienti: significativamente migliorata.

Il Problema: Report WordPress Manuali Non Scalano

Chi gestisce un’agenzia WordPress lo sa bene: i clienti vogliono sapere cosa sta succedendo sui loro siti, ma non vogliono — e non devono — capire la differenza tra un plugin con vulnerabilità nota e uno semplicemente non aggiornato.

Il nostro vecchio processo per i report mensili WordPress era così:

1. Aprire ManageWP o il nostro pannello per ogni sito
2. Screenshot dei dati principali
3. Riempire un template Google Docs
4. Scrivere a mano un paragrafo di “stato generale”
5. Inviare via email

Per un’agenzia con 15 siti: circa 45 minuti per report, moltiplicato per 15 clienti = quasi 12 ore al mese spese solo in reportistica. Ore non fatturabili, spesso delegate a figure junior che non avevano il contesto tecnico per scrivere con autorevolezza.

La soluzione non era trovare un template migliore. Era automatizzare la narrazione, mantenendo il controllo umano sul dato sottostante.

L’Architettura: Dati WordPress → Claude API → Report PDF

Il sistema che abbiamo costruito in AgencyPilot segue questo flusso:

1. Raccolta dati: Il nostro daemon Python (FastAPI) interroga ogni sito via WordPress REST API e raccoglie metriche giornaliere
2. Aggregazione mensile: A fine mese, PostgreSQL aggrega i dati in un oggetto JSON strutturato per sito
3. Generazione narrazione: Passiamo il JSON a Claude (claude-3-5-sonnet) con un prompt di sistema calibrato per il tono dell’agenzia
4. Output strutturato: Claude restituisce il testo narrativo in sezioni predefinite (JSON mode)
5. Composizione PDF: WeasyPrint assembla dati + narrativa in un PDF brandizzato per il cliente

Per chi vuole approfondire come strutturiamo la comunicazione con le API WordPress, la nostra guida sulla REST API WordPress e gli endpoint personalizzati copre le basi tecniche.

Il Prompt di Sistema: La Parte Più Delicata

La qualità del report AI dipende quasi interamente dal prompt. Abbiamo iterato per settimane prima di trovare un formato che producesse testo usabile senza editing.

Ecco la struttura del payload che inviamo a Claude:

def build_report_payload(site_data: dict, agency_config: dict) -> dict:
    system_prompt = f"""Sei un consulente WordPress senior che scrive report mensili 
per clienti aziendali. Stile: professionale ma diretto. 
Agenzia: {agency_config['name']}.
Tono: {agency_config['report_tone']}.

Regole assolute:
- Mai inventare dati non presenti nel JSON
- Cifre sempre con unità di misura (%, ms, GB)
- Se un dato manca, scrivi "dato non disponibile questo mese"
- Max 3 righe per sezione, salvo sicurezza e performance
- Niente filler ("Siamo lieti di presentarvi...")
"""

    user_message = f"""Genera il report mensile per questo sito WordPress.
Dati periodo: {site_data['period']}

{json.dumps(site_data['metrics'], indent=2)}

Sezioni richieste (rispondi in JSON):
1. executive_summary (2-3 frasi, per il CEO del cliente)
2. uptime_narrative (commento sull'uptime del periodo)
3. performance_narrative (Core Web Vitals, LCP/CLS/FID)
4. security_narrative (plugin vulnerabili, scan risultati)
5. updates_narrative (aggiornamenti eseguiti, eventuali problemi)
6. next_month_priorities (2-3 azioni raccomandate)
"""
    return {"system": system_prompt, "user": user_message}

L’uso del JSON mode di Claude è stato determinante: senza di esso, il testo tornava in formati inconsistenti che rompevano il template PDF. Con JSON mode, la composizione finale è completamente automatizzata.

Dati Reali: Cosa Raccogliamo e Come

Il valore del report AI dipende dalla qualità dei dati di input. Ecco cosa raccoglie AgencyPilot per ogni sito monitorato:

La raccolta avviene via FastAPI con worker asincroni (asyncio + httpx) che gestiscono fino a 50 siti in parallelo senza saturare la rete dei clienti. Per i dettagli sull’architettura multi-sito, la nostra guida alla gestione WordPress per agenzie copre l’intera infrastruttura.

Il Problema dei “Dati Assenti” e Come lo Gestiamo

In produzione, i dati non sono mai perfetti. Il sito era down durante la raccolta. L’API WPScan ha avuto un timeout. Il plugin di backup non ha risposto.

Il modello AI senza istruzioni specifiche tende a inventare o omettere le sezioni mancanti — entrambe le cose inaccettabili in un documento che va al cliente. La nostra soluzione:

def sanitize_metrics(raw_data: dict) -> dict:
    """
    Sostituisce i valori None con placeholder espliciti
    prima di passare i dati a Claude.
    """
    placeholders = {
        "uptime_percent": "dato non disponibile (errore raccolta)",
        "lcp_score": "dato non disponibile (PageSpeed API timeout)",
        "security_scan": "scansione non completata questo mese",
        "last_backup": "stato backup non verificato",
    }
    
    sanitized = {}
    for key, value in raw_data.items():
        if value is None or value == "":
            sanitized[key] = placeholders.get(key, "dato non disponibile")
        else:
            sanitized[key] = value
    
    return sanitized

Claude tratta i placeholder come dati validi e li cita esplicitamente nel report, che è esattamente il comportamento che vogliamo: trasparenza verso il cliente, nessuna invenzione.

Personalizzazione per Cliente: Il Sistema di Profili

Non tutti i clienti vogliono lo stesso livello di dettaglio tecnico. Un comune della PA italiana ha esigenze diverse da una startup e-commerce.

In AgencyPilot, ogni cliente ha un profilo di report con questi parametri:

• report_tone: technical | executive | simple
• sections_enabled: array delle sezioni da includere
• language: it | en
• detail_level: high | medium | low
• include_recommendations: boolean

Il profilo viene iniettato nel system prompt di Claude, che adatta il registro linguistico automaticamente. Un cliente con tone: executive riceve frasi come “Il sito ha mantenuto disponibilità superiore al 99,9% nel mese” invece di “Uptime: 99.97%, 2 incidenti da 3 min ciascuno”.

Questa flessibilità è risultata cruciale per i clienti della PA, dove abbiamo sviluppato esperienza specifica — tema che approfondiamo nell’articolo dedicato a WordPress per la Pubblica Amministrazione.

Risultati in Produzione: Numeri Reali

Dopo 6 mesi di utilizzo interno e poi progressivo rollout ai clienti AgencyPilot, questi sono i numeri:

• Tempo medio per report: da 45 minuti a 3 minuti (incluso review umano)
• Tasso di approvazione senza editing: ~73% dei report generati non richiedono modifiche
• Feedback clienti: NPS del servizio report aumentato da 6.2 a 8.1 su 10
• Costo Claude API per report: ~0.08€ per sito/mese (modello sonnet-3-5, ~4.000 token input/output)
• Siti gestiti con lo stesso team: da 40 a 90+ siti senza aumentare il personale dedicato

Il 27% dei report che richiedono editing quasi sempre riguarda siti con incidenti significativi nel periodo — casi in cui vogliamo aggiungere contesto umano che il modello non può avere (es. “il downtime del 14 marzo era legato alla migrazione server pianificata”).

Errori da Non Ripetere

Build in public significa condividere anche gli errori. Ecco le tre decisioni sbagliate che ci hanno costato tempo:

1. Passare l’HTML del sito come contesto

Nella prima versione, passavamo a Claude anche uno snapshot HTML della homepage per “dargli contesto visivo”. Risultato: token sprecati, latenza triplicata, qualità del report invariata. I dati strutturati JSON sono sufficienti.

2. Generare tutto in un’unica chiamata API

Per risparmiare chiamate API, inizialmente generavamo tutti i report del mese in un’unica richiesta batch. Claude tendeva a “contaminare” i report tra siti diversi con dettagli incrociati. La soluzione giusta: una chiamata API per sito, parallelizzata con asyncio ma con contesti separati.

3. Non validare l’output JSON di Claude

Claude rispetta il JSON mode ~97% delle volte. Quel 3% in produzione su 90 siti significa quasi 3 report al mese con JSON malformato che rompevano il pipeline. Ora ogni output passa attraverso Pydantic prima di procedere:

class ReportOutput(BaseModel):
    executive_summary: str = Field(min_length=50, max_length=400)
    uptime_narrative: str = Field(min_length=30, max_length=300)
    performance_narrative: str = Field(min_length=30, max_length=300)
    security_narrative: str = Field(min_length=30, max_length=300)
    updates_narrative: str = Field(min_length=30, max_length=300)
    next_month_priorities: list[str] = Field(min_length=2, max_length=3)

def parse_report(raw_json: str) -> ReportOutput:
    try:
        data = json.loads(raw_json)
        return ReportOutput(**data)
    except (json.JSONDecodeError, ValidationError) as e:
        logger.error(f"Report validation failed: {e}")
        raise ReportGenerationError("Output Claude non valido, retry...")

Cosa Viene Dopo: Report Predittivi

Il passo successivo che stiamo sviluppando è passare da report descrittivi a report predittivi: invece di documentare cosa è successo, anticipare cosa potrebbe succedere.

I dati storici di 6-12 mesi per ogni sito ci permettono di addestrare pattern semplici (non serve ML complesso) che identificano:

• Plugin che storicamente causano problemi dopo aggiornamenti WordPress major
• Siti che mostrano degrado performance progressivo prima di un down
• Pattern di attività anomala che precedono tentativi di intrusione

Questi segnali diventano avvisi proattivi nel report, trasformando il documento da “recap del passato” a “piano per il futuro”. Per approfondire come gestiamo la sicurezza proattiva, l’articolo sulla sicurezza WordPress per agenzie è il punto di partenza.

FAQ: Report AI per WordPress

Quanto costa integrare Claude API per i report WordPress?

Con il modello claude-3-5-sonnet, il costo per report è circa 0.07-0.10€ per sito al mese. Per un’agenzia con 50 siti: meno di 5€/mese di API, contro ore di lavoro manuale.

I clienti sanno che i report sono generati da AI?

Sì, lo comunichiamo nella nota a piè di pagina del PDF. La reazione è stata quasi sempre positiva: i clienti apprezzano la coerenza e la rapidità, non il fatto che sia scritto da un umano.

Come si gestiscono i report per siti in lingue diverse dall’italiano?

Il parametro language nel profilo cliente cambia la lingua dell’output Claude. Gestiamo attualmente IT e EN; aggiungere nuove lingue richiede solo di aggiornare il system prompt.

È possibile usare questo sistema con WordPress.com o solo WordPress self-hosted?

AgencyPilot è progettato per WordPress self-hosted. WordPress.com ha accesso API limitato che non permette la raccolta dati necessaria per i report completi.

Il sistema funziona anche per WooCommerce?

Sì, abbiamo un set di metriche aggiuntivo per i siti WooCommerce (ordini, revenue, conversion rate) che viene incluso nel JSON di input per Claude quando rilevato.