Primo progetto
Crea il progetto, collega modello e avatar, recupera la chiave, gestisci ambienti, versioni e pubblicazione.
Quarto passaggio della guida rapida. Il progetto è l'unità che verrà effettivamente pubblicata: raccoglie agente, modello, avatar, knowledge base, domini autorizzati e chiavi.
Prima di iniziare
- Ruolo Amministratore oppure Manager
- Una configurazione di modello AI già salvata
- Il dominio del sito su cui pubblicare il widget, per esempio www.acme.it
- Un nome e una descrizione condivisi con il team, per riconoscere il progetto nell'elenco
Crea il progetto
Apri l'elenco dei progetti
Nel menu laterale seleziona Configurazione, quindi Progetti. La tabella mostra nome, ambiente attivo, modello collegato, stato di pubblicazione e data dell'ultima modifica.
Inserisci nome e descrizione
Seleziona Nuovo progetto e compila i campi identificativi.
| Campo | Obbligatorio | Esempio |
|---|---|---|
| Nome | Sì | Assistenza clienti sito pubblico |
| Descrizione | No | Agente pubblico su www.acme.it, orari, servizi e contatti |
| Workspace | No | sede-milano |
| Lingua principale | Sì | Italiano |
| Lingue aggiuntive | No | Inglese, Tedesco |
Scegli nomi che dicano dove e per chi è pubblicato il progetto: quando ne avrai dieci, Progetto 2 non aiuterà nessuno.
Collega il modello AI
Nella scheda Modello seleziona la configurazione creata al passaggio 3. Il progetto eredita prompt di sistema, parametri e fallback. Puoi sovrascrivere il solo prompt a livello di progetto senza duplicare l'intera configurazione.
Scegli l'avatar
Nella scheda Avatar seleziona l'identità visiva dell'agente: immagine, nome visualizzato e messaggio di benvenuto. Usa un nome che non lasci intendere di parlare con una persona reale, per esempio Assistente Acme.
Salva il progetto
Al salvataggio la piattaforma genera la chiave di progetto e crea automaticamente i tre ambienti: sviluppo, staging e produzione.
Un progetto per punto di contatto
Crea progetti separati quando cambiano pubblico, contenuti o tono: sito pubblico, area riservata rivenditori, portale interno dipendenti. Condividere un solo progetto tra pubblici diversi porta a un prompt pieno di eccezioni e a risposte fuori contesto.
La chiave di progetto
La chiave di progetto identifica pubblicamente il progetto ed è inclusa nello snippet del widget.
Chiave di progetto (esempio)
bp_proj_••••••••Sostituisci con la chiave reale del tuo progetto, visibile in Chiavi e accesso.
| Caratteristica | Comportamento |
|---|---|
| Formato | bp_proj_ seguito da 16 caratteri esadecimali |
| Visibilità | Pubblica: compare nel codice sorgente della pagina |
| Ambito | Un progetto, un ambiente |
| Rigenerazione | Possibile in qualsiasi momento; invalida immediatamente gli snippet pubblicati |
| Protezione | Garantita dall'elenco dei domini autorizzati, non dalla segretezza della chiave |
La chiave di progetto non è una credenziale segreta
La chiave di progetto è visibile a chiunque ispezioni il codice della pagina: è normale e previsto. La sicurezza dipende dall'elenco dei domini autorizzati, non dalla chiave. Non usare mai la chiave di progetto per chiamate server-to-server: per quelle serve una chiave API bp_live_xxxxxxxxxxxxxxxx generata in Tenant → Chiavi API.
Domini autorizzati
Il widget si inizializza solo se la pagina che lo carica appartiene a un dominio presente nell'elenco. Su qualsiasi altro dominio la richiesta viene rifiutata e il widget non compare.
Produzione www.acme.it
acme.it
shop.acme.it
Staging staging.acme.it
Sviluppo localhost
127.0.0.1I sottodomini non sono inclusi automaticamente: www.acme.it non autorizza shop.acme.it. Aggiungi ogni dominio esplicitamente.
Ambienti
Ogni progetto vive in tre ambienti con configurazioni e chiavi separate.
| Ambiente | Scopo | Chiave | Domini tipici |
|---|---|---|---|
| Sviluppo | Prove libere del team, modifiche frequenti | Dedicata | localhost, ambienti locali |
| Staging | Validazione prima della pubblicazione | Dedicata | staging.acme.it |
| Produzione | Servizio visibile al pubblico | Dedicata | www.acme.it |
Sono indipendenti per: prompt di sistema, parametri del modello, data store collegati, strumenti abilitati, webhook, domini autorizzati e limiti di traffico.
Non provare mai in produzione
Prompt e flussi vanno modificati in sviluppo, validati in staging e solo dopo promossi in produzione. Una modifica diretta in produzione è immediatamente visibile a tutti i visitatori e non ha una fase di verifica.
Versioni e pubblicazione
Ogni pubblicazione crea una versione immutabile della configurazione, con numero progressivo, autore, data e note.
Lavora in sviluppo
Modifica prompt, avatar, flussi e data store nell'ambiente di sviluppo. Le modifiche restano come bozza e non influenzano gli altri ambienti.
Promuovi in staging
Seleziona Promuovi e scegli l'ambiente staging. Fai provare la configurazione ai referenti di reparto sul dominio di staging, con le domande reali dei clienti.
Pubblica in produzione
Quando la validazione è conclusa, seleziona Pubblica in produzione. Inserisci una nota di rilascio sintetica ma utile: Aggiunto listino 2026 e regola di handover per i reclami.
Verifica dopo la pubblicazione
Apri il sito in produzione, avvia una conversazione di prova e controlla in Sessioni che la conversazione risulti sulla versione appena pubblicata.
Ripristina se necessario
Dall'elenco versioni puoi ripristinare una versione precedente con Ripristina. Il ripristino è immediato e genera a sua volta una nuova versione, così la cronologia resta completa.
| Operazione | Effetto immediato | Reversibile |
|---|---|---|
| Salvataggio bozza | Solo ambiente di sviluppo | Sì |
| Promozione in staging | Aggiorna staging | Sì |
| Pubblicazione in produzione | Visibile ai visitatori | Sì, tramite ripristino |
| Rigenerazione chiave | Invalida gli snippet pubblicati | No |
| Eliminazione progetto | Disattiva il widget e archivia le sessioni | No |
Struttura di un progetto
Risoluzione dei problemi
Nella quasi totalità dei casi il dominio non è nell'elenco autorizzato oppure lo snippet usa la chiave di un altro ambiente. Verifica entrambi in Chiavi e accesso e in Domini autorizzati.
Gli snippet pubblicati smettono di funzionare immediatamente. Copia la nuova chiave, aggiorna lo snippet sul sito e ripubblica la pagina. Non è possibile ripristinare la chiave precedente.
Le bozze restano in sviluppo finché non le promuovi. Controlla in Versioni quale versione è attiva in produzione e, se necessario, esegui la pubblicazione.
Passaggio 4 completato
Il progetto esiste, ha una chiave e tre ambienti. Continua con la knowledge base per dargli qualcosa da raccontare.