Documentazione · App Builder
Pubblicazione
Bozze e versioni pubblicate
Un'app ha due manifest:
| Bozza | Versione pubblicata | |
|---|---|---|
| Creata con | Save draft | Publish |
| Può contenere errori | Sì. Viene salvata comunque, così il lavoro non va mai perso. | No. La pubblicazione rifiuta un manifest con errori. |
| Agenti | Inline: ogni agente porta con sé il proprio profilo (profile.inline). | Ogni agente fa riferimento a un profilo agente della tua organizzazione (profile.ref). |
| Servita su | preview-<slug>.webrobot.eu | <slug>.webrobot.eu e i tuoi domini personalizzati |
| Vista da | Gli amministratori dell'app | Chiunque l'app lasci entrare |
Salvare una bozza non cambia mai l'app online. L'app online cambia solo quando pubblichi.
Salvare una bozza
Save draft (salva bozza) memorizza il manifest e le posizioni sul canvas (le posizioni sono conservate accanto al
manifest, non al suo interno). La piattaforma controlla solo che il manifest sia un VerticalApp con
apiVersion: webrobot.eu/v1alpha1 e che metadata.slug sia lo slug dell'app. Gli errori trovati dalla validazione
completa vengono mostrati in App Studio ma non bloccano il salvataggio.
Il primo salvataggio crea l'app per la tua organizzazione. Da quel momento lo slug è tuo. Se un'altra organizzazione usa già lo slug, il salvataggio fallisce con slug already taken.
L'anteprima
Il primo salvataggio prepara anche l'indirizzo di anteprima, https://preview-<slug>.webrobot.eu. Mostra sempre la
bozza salvata: salva di nuovo per vedere le ultime modifiche. Una barra in alto dice Preview — draft not yet
published.
L'anteprima non è pubblica. Un visitatore non autorizzato viene mandato alla pagina di accesso, che dice Draft preview: sign in as an admin of the app, or open it from App Studio.
Che cosa cambia rispetto all'app online:
- Gli agenti non vengono eseguiti. Un'esecuzione risponde agent <key> has an inline profile: publish the app first.
- I pagamenti sono disattivati: le pagine dicono Payments are off in the preview.
- I trigger webhook non rispondono.
- Non si possono creare istanze utente dei modelli di agente.
- I dati restano separati: record, utenti e crediti creati nell'anteprima non si mescolano mai con quelli dell'app online.
Che cosa fa Publish
Premi Publish (pubblica) in App Studio. Se hai modifiche non salvate, vengono salvate prima. La pubblicazione parte sempre dalla bozza salvata. Poi questi passaggi vengono eseguiti in ordine, con il tuo account, nell'organizzazione dell'app. Il nome di ogni passaggio è ciò con cui inizia un messaggio di errore.
| Passaggio | Che cosa succede |
|---|---|
validate | La bozza viene validata. La pubblicazione si ferma ai primi errori (ne vengono elencati fino a 5). |
app tools | Solo se un agente usa gli strumenti dell'app (raccolte, slot Python): la piattaforma emette il token che permette agli agenti dell'app di chiamare l'endpoint MCP dell'app, https://<slug>.webrobot.eu/api/mcp. |
agent <key> | Ogni agente con un profilo inline diventa un profilo agente della tua organizzazione chiamato <slug>-<agent key>. Viene creato alla prima pubblicazione e aggiornato nelle successive. Gli vengono collegati i suoi strumenti: l'endpoint MCP dell'app (ogni agente riceve solo i propri strumenti) e i server MCP esterni che hai dichiarato. Un agente dietro una vista chat viene impostato per rispondere solo con il suo ultimo messaggio. |
team <key> | Ogni squadra diventa un profilo agente chiamato <slug>-team-<team key>, costruito dai suoi membri. |
pipelines, job <key> | I job di dati con una pipeline inline vengono applicati come un progetto chiamato <slug>, una pipeline <slug>-<job key> e un job <slug>-<job key>-job. Applicarli di nuovo li aggiorna per nome. |
api key | Solo alla prima pubblicazione: l'app riceve una sua chiave API, etichettata vertical app <slug>. |
credential | Solo alla prima pubblicazione: la chiave viene memorizzata cifrata come credenziale cloud della tua organizzazione chiamata vertical-app-<slug>. Il runtime la usa per agire per conto di questa app, e per nient'altro. |
validate published | Il manifest con i riferimenti ai profili e ai job viene validato di nuovo. |
Poi la piattaforma memorizza il manifest pubblicato:
- Controlla che gli indirizzi dell'app siano liberi. Se un'altra app risponde già su uno dei tuoi domini, la pubblicazione fallisce con host <domain> is already used by another app.
- Aumenta di uno il numero di versione.
- Instrada
<slug>.webrobot.eu,preview-<slug>.webrobot.eue i tuoi domini personalizzati verso il runtime.
Il manifest pubblicato ha profile: { ref: <id> } dove la bozza aveva profile: { inline: … }:
# bozza
spec:
agents:
- key: intake
role: main
profile:
inline:
crews:
- id: intake
engine: agent_sdk
model: claude-sonnet-5-5
system_prompt: You write a pre-visit summary…
# versione pubblicata
spec:
agents:
- key: intake
role: main
profile: { ref: 1234 }
La bozza conserva i profili inline: è ciò che App Studio modifica.
Che cosa vedi
- Successo: Published v<N> — live on https://<slug>.webrobot.eu. Lo stato passa a published v<N>.
- Pubblicata, ma non è stato possibile configurare l'indirizzo: Published v<N>, but its address <url> could not be set up: tell support. La versione è memorizzata; è fallito solo l'instradamento.
- Errore: il messaggio inizia con il passaggio, per esempio
api key: …oagent intake: …. Non viene pubblicato nulla e il numero di versione non cambia. I profili già creati o aggiornati nei passaggi precedenti restano, e la pubblicazione successiva li riutilizza.
Altri errori: save a draft first (non c'è una bozza salvata), stored draft is not valid JSON.
Il runtime conserva per un massimo di 30 secondi il manifest che ha risolto per un indirizzo. Una nuova versione può impiegare questo tempo per comparire sull'indirizzo online.
Chi può pubblicare
| Azione | Ruoli |
|---|---|
| Salvare una bozza, pubblicare un aggiornamento | developer, admin |
| Prima pubblicazione di un'app | admin (crea la chiave API dell'app e la memorizza come credenziale) |
| Eliminare un'app | admin |
| Spostare un'app in un'altra organizzazione | Solo gli amministratori della piattaforma WebRobot |
Un developer che prova la prima pubblicazione riceve un errore che inizia con api key:. Chiedi a un amministratore
dell'organizzazione di pubblicare una volta; dopo, i developer possono pubblicare gli aggiornamenti.
L'indirizzo dell'app
Un'app pubblicata risponde su https://<slug>.webrobot.eu. Lo slug viene fissato al primo salvataggio dell'app:
- da 3 a 40 caratteri;
- lettere minuscole, cifre e trattini;
- inizia con una lettera e non finisce con un trattino.
Applicare una proposta del co-pilot a un'app esistente non cambia mai il suo slug.
Domini personalizzati
Puoi servire l'app anche sui tuoi domini.
- In App Studio apri All settings › App (oppure fai clic sul riquadro Users) e scrivi i domini in Customer
domains (domini del cliente), separati da virgole. Vengono memorizzati in
spec.domains. - Presso il tuo provider DNS, crea per ogni dominio un record CNAME che punta a
<slug>.webrobot.eu. - Pubblica.
spec:
domains:
- booking.example-clinic.com
Alla pubblicazione il dominio viene instradato verso il runtime e WebRobot richiede un certificato TLS per esso. Il certificato viene richiesto solo quando il dominio risolve già all'indirizzo dell'app, così un record DNS mancante non consuma i limiti dell'autorità di certificazione. Se il CNAME non era presente quando hai pubblicato, pubblica di nuovo quando funziona.
Regole:
- ogni dominio deve essere un nome host valido (vedi il riferimento);
- i domini sotto
webrobot.eunon sono domini personalizzati e vengono ignorati; - un dominio può appartenere a una sola app;
- togliere un dominio dal manifest e pubblicare rimuove il suo instradamento e il suo certificato.
Il pannello a destra di App Studio elenca ogni dominio con il CNAME che richiede.
Ripubblicazione
Per modificare un'app online, modifica la bozza, salvala e pubblica di nuovo.
| Che cosa | Alla ripubblicazione |
|---|---|
| Numero di versione | Sale di uno. |
| Profili agente | Vengono aggiornati gli stessi profili, nulla viene duplicato. Se hai eliminato un profilo a mano, viene creato di nuovo. |
| Agenti rimossi dal manifest | I loro profili restano nella tua organizzazione; l'app smette di usarli. |
| Job di dati | Aggiornati per nome. |
| La chiave API e la credenziale dell'app | Conservate. Vengono create solo alla prima pubblicazione. |
| Utenti, crediti, record, esecuzioni | Conservati. I dati dell'app appartengono allo slug, non a una versione. |
| Indirizzo e domini personalizzati | Riapplicati dal nuovo manifest. |
Ritiro ed eliminazione
Non esiste un ritiro separato dalla pubblicazione. Per mettere un'app offline, un amministratore la elimina dall'elenco delle app con Delete. Dopo la conferma:
- l'app smette subito di essere servita, sul suo indirizzo, sull'anteprima e sui domini personalizzati;
- la bozza e il manifest pubblicato vengono rimossi;
- la chiave API dell'app viene revocata e la sua credenziale eliminata;
- gli instradamenti e i certificati dei domini personalizzati vengono rimossi;
- i profili agente e le pipeline che ha creato restano nella tua organizzazione.
Trasferire un'app a un'altra organizzazione
Gli amministratori della piattaforma WebRobot possono trasferire un'app a un'altra organizzazione. Da quel momento l'app appartiene alla nuova organizzazione: è lei a modificarla e pubblicarla, e i pagamenti dei suoi clienti vanno a lei.
- La chiave dell'app della vecchia organizzazione viene revocata.
- Se l'app era pubblicata, viene ripubblicata subito dalla sua bozza nella nuova organizzazione: lì vengono creati nuovi profili agente, pipeline e chiave API. Le modifiche non pubblicate nella bozza vanno online in quel momento.
- I profili agente e i job creati in precedenza restano alla vecchia organizzazione.
- Se quella ripubblicazione fallisce, l'app resta offline finché qualcuno non la pubblica di nuovo in App Studio.