Passa al contenuto principale

Come configurare l'Assistente AI

Collega Agon a un provider AI a tua scelta e iniziano a funzionare l'Assistente AI di supporto, la Modalità azioni AI e le risposte da consulente di business. Il modo più rapido è una chiave API gratuita di Google Gemini, e ci vogliono circa 3 minuti.

Come funziona l'Assistente AI in Agon​

Agon funziona sul tuo computer, e lo stesso vale per la configurazione dell'Assistente AI. L'assistente usa una chiave di un provider AI che appartiene al tuo studio: crei la chiave presso il provider, la incolli in Agon e Agon comunica direttamente con quel provider. Agon non gestisce un proprio servizio AI, e nessun servizio AI è incluso in Agon.

Hai tre opzioni:

OpzioneCosa ti serveIdeale per
Google Gemini (consigliato per iniziare)Un account GooglePartire in pochi minuti
GroqUn account GroqUn provider alternativo con risposte rapide
Un modello locale con OllamaUn computer abbastanza potenteTenere tutti i prompt sul tuo computer

Se non configuri nulla, l'assistente funziona comunque in modalità base (vedi sotto).

Cos'è la modalità base?​

Senza un provider AI, il pannello dell'assistente diventa una ricerca nella documentazione. Scrivi qualche parola chiave e Agon mostra gli articoli di aiuto più pertinenti, presi direttamente da questa documentazione. La modalità base:

  • funziona interamente sul tuo computer, senza connessione internet e senza AI;
  • non può rispondere a domande libere, eseguire azioni AI o dare consigli sul business;
  • mostra un pulsante Configura l'AI nelle Impostazioni che ti riporta a questa configurazione.

Impostazioni → Assistente AI mostra Non configurato · modalità base finché non è collegato alcun provider.

Prima di iniziare​

  • Solo l'account dello studio manager può configurare l'Assistente AI.
  • Leggi Privacy: dove vanno i tuoi prompt più sotto, soprattutto se pensi di menzionare dati dei clienti nella chat.
  • Tratta una chiave API come una password. Chiunque la possieda può usare il tuo account presso il provider.

Crea una chiave API Gemini in 3 minuti​

  1. Apri la pagina delle chiavi API di Google AI Studio nel browser e accedi con il tuo account Google.
  2. Clicca Create API key (Google potrebbe chiamarlo Get API key; con l'interfaccia in italiano il nome compare tradotto). Se Google ti chiede di scegliere o creare un progetto, accetta quello predefinito.
  3. Clicca l'icona di copia accanto alla nuova chiave. È una lunga stringa di lettere e numeri.
  4. In Agon, apri Impostazioni → Assistente AI. [SCREENSHOT: Impostazioni → Assistente AI con l'elenco dei provider e il campo Chiave API]
  5. In Provider AI, scegli Google Gemini.
  6. Incolla la chiave nel campo Chiave API e clicca Verifica e salva.
  7. Agon verifica subito la chiave con Google. Se funziona, vedi Chiave API salvata e verificata. e un badge Chiave attiva · Google Gemini.

Fatto: apri l'assistente e fagli una domanda.

Le schermate di Google cambiano di tanto in tanto. Se un pulsante ha un nome diverso, cerca "API keys" nel menu di Google AI Studio. Il link Ottieni una chiave API Google Gemini accanto all'elenco dei provider in Agon apre sempre la pagina giusta.

Usare Groq in alternativa​

  1. Apri la pagina delle chiavi API della console di Groq e accedi o crea un account.
  2. Clicca Create API Key, dagli un nome (ad esempio "Agon") e copia la chiave. Groq la mostra una sola volta.
  3. In Agon, apri Impostazioni → Assistente AI, scegli Groq in Provider AI, incolla la chiave in Chiave API e clicca Verifica e salva.

Un badge Chiave attiva · Groq conferma che funziona.

Usare un modello locale con Ollama​

Con Ollama il modello AI gira sul tuo computer, quindi i prompt non ne escono mai. Ti serve un computer con memoria sufficiente per far girare un modello. Le risposte sono di solito più lente di quelle di un provider nel cloud, e la loro qualità dipende dal modello che scegli. È un'opzione avanzata. Non serve nessuna chiave API, e non devi mai modificare file né riavviare Agon.

  1. Scarica e installa Ollama da ollama.com, poi scarica almeno un modello, ad esempio eseguendo ollama pull llama3.1 in un terminale. Ollama deve essere in esecuzione ogni volta che usi l'assistente.
  2. In Agon, apri Impostazioni → Assistente AI. [SCREENSHOT: Impostazioni → Assistente AI con Ollama (local) selezionato e il selettore del modello]
  3. In Provider AI, scegli Ollama (local).
  4. Agon verifica se Ollama è raggiungibile sul tuo computer:
    • Se Ollama non è raggiungibile, la pagina te lo segnala e offre un link Installa Ollama. È il messaggio normale per chi non ha ancora installato o avviato Ollama: è un suggerimento, non un errore. Installa Ollama (o assicurati che sia in esecuzione), poi torna a questa pagina.
    • Se Ollama è in esecuzione ma non hai ancora scaricato nessun modello, la pagina ti dice di aprire un terminale ed eseguire ollama pull <modello> (ad esempio ollama pull llama3.1), poi di tornare qui.
  5. Una volta installato almeno un modello, scegli dal menu a tendina Modello — che sostituisce il campo Chiave API per questo provider — e clicca Verifica e salva.

Fatto: nessun file .env, nessuna chiusura di Agon, nessun riavvio. La modifica ha effetto subito, proprio come salvare una chiave Gemini o Groq.

Impostazioni → Assistente AI ora mostra Configurato · Ollama (local). Se in seguito salvi una chiave di un provider con Usa invece la chiave del tuo provider, quella chiave ha la precedenza sul modello locale.

Privacy: dove vanno i tuoi prompt​

  • Direttamente dal tuo computer al provider che hai scelto. Quando usi Gemini o Groq, la tua domanda e le informazioni che servono all'assistente per rispondere viaggiano direttamente dal computer su cui gira Agon a quel provider. Non passano mai dallo sviluppatore di Agon né da alcun server gestito per Agon.
  • Con Ollama, nulla esce dal tuo computer.
  • La tua chiave resta sul tuo computer. Agon la conserva cifrata nel database locale del tuo studio e non la mostra più dopo il salvataggio. Rimuovi chiave in Impostazioni → Assistente AI la cancella in qualsiasi momento.
  • I piani gratuiti possono usare i tuoi dati. I piani gratuiti di alcuni provider possono usare i dati che invii per addestrare o migliorare i propri modelli. Per le domande che includono dati dei tuoi clienti, usa un piano a pagamento o un modello locale. I termini cambiano nel tempo, quindi controlla i termini attuali e l'informativa privacy del tuo provider prima di iniziare: termini dell'API Gemini · informativa privacy di Groq.
  • Il controllo è del tuo studio. È il tuo studio ad avere l'accordo con il provider, quindi ai sensi del GDPR quel provider è un responsabile del trattamento per il tuo studio. La guida GDPR spiega cosa significa per te.

Una buona abitudine: non incollare nella chat dati sensibili dei clienti (ad esempio note sulla salute) a meno che tu non sia a tuo agio con i termini del tuo provider.

Se prevedi un uso intenso​

Ogni provider limita quante richieste una chiave può fare al minuto e al giorno. I piani gratuiti hanno limiti bassi. Se più persone usano l'assistente contemporaneamente, o se usi la Modalità azioni AI nelle ore di punta, potresti vedere un messaggio che indica che il tuo provider AI sta limitando le richieste.

Per risolvere, aumenta i limiti presso il provider:

  • Google Gemini: attiva la fatturazione sul progetto Google Cloud a cui appartiene la tua chiave. Google AI Studio mostra il tuo livello attuale e come passare a quello superiore.
  • Groq: controlla i tuoi limiti e le opzioni di upgrade nella console di Groq.

La stessa chiave continua a funzionare in Agon dopo l'upgrade. Non ti serve una nuova chiave e non c'è nulla da cambiare in Agon. Il provider ti fattura direttamente tutto ciò che supera il suo piano gratuito. Un piano a pagamento è anche la scelta consigliata per i dati dei clienti (vedi la sezione sulla privacy qui sopra).

Cosa fare se qualcosa va storto?​

Agon dice che la mia chiave non è valida Controlla di aver copiato l'intera chiave senza spazi in più e che il provider scelto corrisponda alla chiave: una chiave Groq non funziona come chiave Gemini. Verifica che la chiave non sia stata cancellata nella console del provider. Una chiave appena creata può impiegare un minuto per iniziare a funzionare: attendi e clicca di nuovo Verifica e salva.

L'assistente dice che il mio provider AI sta limitando le richieste Hai raggiunto il limite del tuo provider. Attendi un minuto e riprova, oppure aumenta i tuoi limiti (vedi Se prevedi un uso intenso).

L'assistente mostra solo articoli di aiuto L'assistente è in modalità base perché nessun provider è collegato. Segui i passaggi qui sopra per aggiungere una chiave. Impostazioni → Assistente AI mostra Non configurato · modalità base quando nessun provider è attivo.

Ricevo "Questa azione richiede Agon AI, che è disattivato" nel mezzo di un'azione La Modalità azioni AI non può completare una richiesta senza un provider. Aggiungi una chiave in Impostazioni → Assistente AI, poi ripeti la richiesta.

La mia chiave funzionava e ora l'assistente non risponde La chiave potrebbe essere stata cancellata, essere scaduta o aver esaurito la quota presso il provider. Crea una nuova chiave e salvala con Cambia in Impostazioni → Assistente AI.

Voglio cambiare provider o sostituire la mia chiave In Impostazioni → Assistente AI, clicca Cambia accanto al badge Chiave attiva, scegli il provider, incolla la nuova chiave e clicca Verifica e salva.

Voglio smettere di usare la mia chiave In Impostazioni → Assistente AI, clicca Rimuovi chiave e conferma. Agon cancella la chiave dal database del tuo studio e l'assistente passa subito alla modalità base, senza riavvio. Se pensi che la chiave possa essere stata diffusa, cancellala (revocala) anche nella console del tuo provider (Google AI Studio o la console di Groq) così nessun altro potrà usarla.

Impostazioni → Assistente AI dice che Ollama (local) non è raggiungibile Ollama non è installato o non è in esecuzione. Installalo da ollama.com (o avvialo se è già installato), poi riapri Impostazioni → Assistente AI: la verifica avviene di nuovo automaticamente, senza nulla da riavviare.

Non compare nessun modello nel menu a tendina Apri un terminale ed esegui ollama pull <modello> (ad esempio ollama pull llama3.1) per scaricare un modello, poi riapri il menu Provider AI, oppure esci e torna su Impostazioni → Assistente AI, così può trovare il modello appena scaricato.

Domande frequenti​

L'Assistente AI ha un costo? Agon non lo fa pagare. Il tuo provider potrebbe farlo: i piani gratuiti hanno limiti di utilizzo, e tutto ciò che li supera ti viene fatturato direttamente dal provider.

Lo sviluppatore di Agon può vedere le mie domande? No. I prompt vanno dal tuo computer direttamente al provider che hai scelto, oppure restano sul tuo computer con Ollama.

Quale provider dovrei scegliere? Gemini è il più rapido da configurare. Per i dati dei clienti, un piano a pagamento di qualsiasi provider o un modello locale è la scelta più sicura.