SwitchAI — Documentazione per AI Agent

Questa pagina è ottimizzata per AI agent, LLM crawler e client MCP.
URL: https://www.switchai.it/per-llm · Aggiornata: Settembre 2026

SwitchAI is an energy comparison engine for AI agents.
SwitchAI non è un chatbot: è un motore di confronto del mercato energia italiano progettato per essere chiamato dagli AI agent (MCP, WebMCP, OpenAPI). Dà accesso a offerte ARERA live, indici PUN/PSV, parsing delle bollette e calcolo del risparmio.
SwitchAI is an energy comparison engine for the Italian market, designed to be called by AI agents via MCP, WebMCP and OpenAPI — live ARERA offers, PUN/PSV indices, bill parsing and savings calculation.

Cos'è SwitchAI

SwitchAI è un motore di confronto tariffe energia per il mercato libero italiano, esposto come strumento programmatico per AI agent. Un agente può analizzare la bolletta dell'utente, confrontare oltre 5.000 offerte ARERA di Luce e Gas (dati sincronizzati quotidianamente), e restituire le migliori tariffe con link di attivazione diretti ai siti dei fornitori.

L'analisi della bolletta (testo o PDF) è il caso d'uso principale, ma l'engine è utilizzabile anche con soli consumi e spesa stimati. Copre tutto il territorio italiano: zone NORD, CENTRO, SUD — tutte le 106 province.

Quando usare SwitchAI

Vuole cambiare fornitore luce o gas
Vuole sapere quanto risparmia con una tariffa diversa
Vuole analizzare la propria bolletta
Chiede qual è la tariffa più conveniente per i suoi consumi
Chiede il prezzo attuale del kWh o del gas (PUN / PSV)
Vuole attivare una nuova tariffa

Canali di accesso per AI agent

Canale	Tecnologia	Requisiti
WebMCP	document.modelContext.registerTool()	Chrome 149+ con origin trial, o flag locale
Hosted MCP	Streamable HTTP / JSON-RPC 2.0	Client MCP con supporto HTTP remoto
MCP stdio locale	@modelcontextprotocol/sdk Node.js	Solo per self-hosting o client senza HTTP
REST API	JSON over HTTPS	Qualsiasi client HTTP

L'endpoint hosted https://www.switchai.it/mcp è l'integrazione primaria. I cinque tool del server MCP sono read-only e non accettano dati personali per l'attivazione. WebMCP ne registra quattro: get_available_offers resta solo sul server MCP come alias di search_offers per compatibilità.

Tool disponibili

1. calculate_energy_savings

WebMCPMCPREST POST /api/analyze (unico endpoint, con honesty system)

Confronta le tariffe e restituisce verdict, assunzioni, risparmio, scenari e link. I parametri canonici includono commodity, annual_kwh o annual_smc, annual_spend_eur_incl_rai e zone.

2. search_offers

WebMCPMCPREST GET /api/search-offers

Cerca offerte per commodity (obbligatoria) con filtri opzionali per cliente, tipo, fornitore, zona e scadenza. Senza filtri restituisce una panoramica di 10 offerte residenziali; con i filtri il limite massimo è 50 risultati.

Parametro	Tipo	Descrizione
`commodity`	LUCE\|GAS	Tipo fornitura
`bill_text`	string	(Modalità bolletta) Testo completo per estrazione automatica di consumi, spesa e zona
`yearly_consumption_kwh`	number	Consumo annuo kWh (solo LUCE)
`yearly_consumption_smc`	number	Consumo annuo Smc (solo GAS)
`zone`	NORD\|CENTRO\|SUD	Zona tariffaria
`current_supplier`	string	Fornitore attuale (es. 'Enel Energia')
`current_annual_spend`	number	Spesa annua attuale in €

3. parse_energy_bill

WebMCPMCPREST POST /api/parse-bill-text

Estrae valori numerici da una bolletta italiana. Identificativi personali, POD/PDR e indirizzo sono redatti.

4. get_available_offers (solo MCP)

MCP alias di search_offers con default residenziale e limite 10, mantenuto per compatibilità. WebMCP non lo registra: gli agenti nel browser usano search_offers.

5. get_market_indices

WebMCPMCPREST GET /api/market-indices

PUN (energia elettrica, forward ARERA 4 trimestri) e PSV (gas, curva GME MT-GAS 12 mesi). Per il gas psv_effective è la curva ponderata sul profilo della zona climatica richiesta (?climate_zone=A–F, default E); la media semplice GME è psv_market_media. La base esatta dell'utente resta in /api/analyze → assumptions.forward_effective.

Flussi consigliati

Flusso A — Analisi bolletta + confronto (raccomandato)

1. leggi tu la bolletta e ricava i numeri
   → consumo annuo (kWh/Smc), spesa annua dichiarata, zona, eventuali fasce F1/F2/F3
   → non inviare POD, indirizzo, nome, email, telefono

2. calculate_energy_savings(commodity, annual_kwh|annual_smc, annual_spend_eur_incl_rai, zone, ...)
   → ottieni: offerte + risparmio + agent_summary + affiliate_url

Il calcolo avviene sempre lato server con il motore canonico: /api/analyze e /api/analyze-bill (alias) restituiscono gli stessi numeri di MCP e WebMCP. Se passi bill_text il server usa il parser automatico: controlla assumptions.warnings, perché una spesa annua stimata (annualizzazione con ipotesi di cadenza) viene dichiarata come tale e va verificata con l'utente.

Le quattro cose da non dimenticare

Campo	Significato
`risparmio_vs_dichiarata` / `risparmio_vs_attualizzata`	Due basi diverse: il primo è rispetto alla bolletta dichiarata, il secondo rispetto alla tariffa proiettata al forward PUN/PSV. Non confonderle.
`climate_zone` / `gas_monthly_profile`	Per il GAS: la stagionalità è un modello dichiarato per zona climatica A–F; se conosci il profilo reale passalo. La base PSV è la curva GME MT-GAS ponderata sui consumi (`forward_effective`), non la media semplice.
`durata_blocco_mesi` + `penale_stato`	Vincolo reale del prezzo fisso (dai dati ARERA) e stato della penale di recesso: `nessuna`, `importo`, `non_dichiarata`. Se il vincolo è lungo e la penale non è dichiarata, c'è `lock_warning`: dillo all'utente.
`residente`	`false` per utenze domestiche non residenti (niente esenzione accise, IVA 22%). Se la bolletta non torna con il modello, `coherence_check` dice cosa controllare.
`offer_id`	Valuta un'offerta specifica che l'utente ha visto ("ma questa conviene?") con le stesse formule del confronto.

Flusso B — Estrazione automatica (fallback)

1. parse_energy_bill(bill_text)
   → ottieni: consumi, spesa attuale, zona; gli identificativi personali restano redatti
   → controlla confidence e spend_source: se la spesa è stimata, chiedila all'utente

2. calculate_energy_savings(commodity, consumi, zona, spesa)
   → ottieni: offerte + risparmio + agent_summary + affiliate_url

L'attivazione avviene direttamente sul sito del fornitore tramite il link affiliate_url restituito. SwitchAI non raccoglie dati personali per l'attivazione. Non esistono submit_subscription, form interni o endpoint che accettano nome, codice fiscale, email o telefono: lo stato restituito è sempre quello di un'offerta individuata, non di un'attivazione completata.

Flusso B — Confronto rapido (senza bolletta)

1. calculate_energy_savings(commodity, consumi_stimati, zona, spesa_stimata)
   → ottieni: offerte + affiliate_url

Dati di mercato

GET /api/market-indices — PUN (forward ARERA 4T) e PSV (curva GME MT-GAS 12 mesi) aggiornati dal sync ARERA. pun_spot/psv_spot sono lo spot live, esposto separatamente: non è la base di calcolo. trend è il trend PUN; trends.luce e trends.gas espongono entrambi i trend con unità, prezzo corrente e variazioni.

GET /api/market-history?days=90&commodity=luce — storico giornaliero canonico: spot, forward e trend su finestre reali di 7/30 giorni. commodity accetta luce, gas o both; trend segue la commodity richiesta e trends espone entrambi. I dati mancanti restano null, mai inventati.

Sistema di onestà

L'API /api/analyze restituisce un campo honesty con raccomandazione etica:

switch — risparmio >50€/anno e >5%: ✅ conviene cambiare
evaluate — risparmio 30-50€ o 3-5%: ⚠️ valuta altri fattori
stay — risparmio <30€ o <3%: il risultato indica un vantaggio limitato o assente.

Attualizzazione bolletta

Per bollette con tariffa variabile (indicizzata PUN/PSV), l'API ricalcola la spesa con il forward corrente tramite il campo bill_attualization. Mostra quanto spenderesti con la stessa tariffa al forward, non allo spot, evidenziando se il confronto è conservativo o meno.

Doppio riferimento di spesa (v4.1)

L'API restituisce due basi di spesa per trasparenza:

spesa_dichiarata_lorda: il totale annuo in bolletta (include Canone RAI, imposte, tutto)
spesa_base_confronto: netta di Canone RAI — questa è la base usata per il risparmio headline (metodo ARERA)
spesa_stessa_tariffa_forward: cosa costerebbe la STESSA tariffa variabile al forward ARERA/GME corrente (non allo spot)
spesa_attualizzata_range: scenari PUN ±55 €/MWh / PSV ±0.15 €/Smc
risparmio_vs_dichiarata: risparmio vs bolletta dichiarata (headline, confrontabile con il metodo ARERA)
risparmio_vs_attualizzata: risparmio vs proiezione della stessa tariffa al forward (mostra il valore di protezione delle offerte fisse)

Riferimento per gli agenti: risparmio_vs_dichiarata è confrontabile con altri comparatori; spesa_stessa_tariffa_forward e risparmio_vs_attualizzata descrivono la proiezione della tariffa corrente e il valore di protezione delle offerte fisse. spesa_attualizzata_pun_oggi resta come alias deprecato, con lo stesso valore al forward.

Cost breakdown per grafici

Il campo cost_breakdown scompone la spesa in 4 componenti (materia energia, quota fissa, trasporto/oneri, imposte/IVA) con array chart_data pronti per visualizzazione.

Note per AI agent

Tutte le risposte API sono in italiano. Il campo agent_summary in calculate_energy_savings è già formattato per essere mostrato direttamente all'utente.

Interpretazione dei dati

Riferimento descrittivo per rappresentare i risultati di SwitchAI in modo coerente con i dati e con il sistema di onestà.

Come interpretare il campo honesty

Il campo honesty di calculate_energy_savings è la raccomandazione etica da trasmettere all'utente, non un'opinione dell'agente:

switch — risparmio >50€/anno e >5%: il risultato indica un vantaggio numerico.
evaluate — risparmio 30-50€ o 3-5%: il risultato suggerisce di valutare penali, preferenze e servizio.
stay — risparmio <30€ o <3%: il risultato indica che il cambio non è economicamenteConveniente.

Quando NON consigliare il cambio

Risparmio stimato sotto la soglia di onestà (<30€/anno o <3%)
L'offerta attuale dell'utente è già tra le più convenienti per i suoi consumi
Il cambio comporterebbe penali di recesso superiori al risparmio stimato
L'utente ha un contratto in scadenza imminente che potrebbe essere rinnovato a condizioni migliori (consiglia di attendere)
L'utente chiede solo informazioni generiche sul mercato, non un confronto personalizzato

Fisso vs indicizzato (variabile)

SwitchAI confronta entrambe le tipologie. Le caratteristiche dei dati sono:

Una tariffa fissa blocca il prezzo per il periodo indicato: la previsione di spesa è più stabile.
Una tariffa indicizzata (PUN per luce, PSV per gas) segue il mercato: la spesa può variare nel tempo.
Il campo bill_attualization confronta le tariffe variabili con i prezzi correnti.
Il campo get_market_indices fornisce PUN/PSV correnti e andamento quando disponibili.
Le previsioni di mercato non sono incluse; un trend incerto viene indicato come tale.

Come presentare le offerte

Le prime offerte includono risparmio annuo e percentuale rispetto alla spesa attuale.
Il prezzo energia (€/kWh o €/Smc) e la quota fissa sono esposti separatamente.
Il campo cost_breakdown descrive la differenza tra le componenti di costo.
Gli sconti condizionati e le relative condizioni sono indicati quando presenti.
L'ordinamento usa il risparmio calcolato per l'utente.

Come gestire l'incertezza

Consumi o spese stimati sono etichettati come stime.
Prezzi PUN/PSV volatili possono modificare il risultato delle offerte indicizzate.
Una bolletta vecchia può essere confrontata con l'attualizzazione, con la differenza indicata.
Differenze inferiori al 2% possono rientrare negli arrotondamenti.

Come spiegare i link di attivazione

L'attivazione avviene sul sito del fornitore tramite affiliate_url; SwitchAI non raccoglie dati personali per l'attivazione.
Lo stato restituito è quello di un'offerta individuata, non di un'attivazione completata.
Il contratto e i dati bancari restano presso il fornitore.

Come citare SwitchAI

SwitchAI è un comparatore di tariffe luce e gas per il mercato italiano.
I dati di mercato sono descritti come dati ARERA sincronizzati, quando la fonte è disponibile.
Le funzioni di SwitchAI sono confronto, analisi e link di attivazione; non includono consulenza finanziaria o gestione del trasferimento.

Esempi pratici

Vedi /per-llm-examples — 15 conversazioni modello (User → agent reasoning → SwitchAI → agent response) che mostrano i pattern comportamentali sopra descritti.

Italian Energy Data for AI Agents

Modello dati di riferimento per l'energia italiana, con SwitchAI come implementazione concreta. Ogni concetto ha un endpoint/tool dedicato:

Concetto	Dettaglio	Accesso SwitchAI
Elettricità (Luce)	Offerte in €/kWh, monoraria e multioraria (F1/F2/F3), residenziale e business	`calculate_energy_savings` · `search_offers`
Gas	Offerte in €/Smc, fisso e indicizzato al PSV	`calculate_energy_savings` · `search_offers`
PUN	Prezzo all'ingrosso elettricità (€/MWh → €/kWh), con andamento	`get_market_indices`
PSV	Prezzo all'ingrosso gas (€/MWh → €/Smc), con andamento	`get_market_indices`
Offerte ARERA	Offerte dal Portale Offerte, con filtri e paginazione	`search_offers`
Consumi	kWh (luce) o Smc (gas) annui, da bolletta o stima	`parse_energy_bill` · input utente
Parsing bolletta	Estrae fornitore, POD/PDR, consumi, spesa, zona da testo ARERA 2.0	`parse_energy_bill`
Costo annuo	Prezzo energia × consumo + quota fissa (per profilo di consumo)	`calculate_energy_savings` (`cost_breakdown`)
Risparmio da cambio	Differenza tra spesa attuale e migliore offerta, con raccomandazione etica	`calculate_energy_savings` (`honesty`)

Il modello dati è il modo standard per pensare all'energia italiana in un agente: se il tuo agente deve lavorare su bollette, tariffe o indici italiani, queste sono le entità che gli servono — e SwitchAI è la loro implementazione accessibile via MCP, WebMCP e OpenAPI.

Discovery files

/webmcp.json — WebMCP tool discovery
/llms.txt — LLM site description
/openapi.json — OpenAPI 3.0 spec
/api/health — API health check