Documentazione · App Builder
Il manifest
Un documento per app
Ogni app è un manifest: un documento con kind: VerticalApp. Descrive le pagine, i moduli, i dati, i ruoli, gli
agenti, cosa li avvia e come pagano gli utenti. App Studio, il suo co-pilot e il runtime leggono e scrivono lo stesso
documento. Non c'è altro codice sorgente.
Un manifest ha quattro chiavi di primo livello, tutte obbligatorie:
| Chiave | Valore |
|---|---|
apiVersion | Sempre webrobot.eu/v1alpha1. |
kind | Sempre VerticalApp. |
metadata | L'identità dell'app: slug, nome, lingue. |
spec | Tutto ciò che l'app fa. |
Nessun'altra chiave di primo livello è accettata.
metadata
| Campo | Obbligatorio | Cos'è |
|---|---|---|
slug | sì | Il nome univoco dell'app. Dà l'indirizzo predefinito <slug>.webrobot.eu. |
displayName | sì | Il nome dell'app, mostrato nell'intestazione, nella scheda del browser e nell'email di accesso. Una stringa semplice. |
tagline | no | Una riga sull'app. Diventa la descrizione della pagina per i motori di ricerca. Traducibile. |
description | no | Una descrizione più lunga. Traducibile. |
langs | no | Le lingue dell'app, come codici di due lettere, es. [en, it]. Almeno una, senza duplicati. |
defaultLang | no | La lingua usata quando la lingua del visitatore non è in langs. Deve essere una di langs. |
timezone | no | Un fuso orario IANA, es. Europe/Rome. Oggi il runtime lo usa solo per gli orari di servizio che non impostano un proprio fuso. |
organizationId | no | L'organizzazione proprietaria dell'app. La imposta la piattaforma quando pubblichi: non scriverla a mano. |
Regole dello slug
Lo slug deve corrispondere a ^[a-z][a-z0-9-]{1,38}[a-z0-9]$:
- da 3 a 40 caratteri;
- lettere minuscole, cifre e trattini;
- inizia con una lettera e non finisce con un trattino.
Lo slug non cambia più una volta che l'app esiste. Quando salvi una bozza, la piattaforma controlla che
metadata.slug corrisponda all'app che stai salvando.
Versioni
Il manifest non ha un campo versione. La piattaforma numera ogni pubblicazione (versione pubblicata v1, v2…) e App Studio mostra il numero. Vedi Pubblicazione.
Le sezioni di spec
spec richiede due chiavi: pattern e agents. Tutto il resto è facoltativo. Nessuna chiave fuori da questo elenco
è accettata.
| Chiave | A cosa serve | Approfondisci |
|---|---|---|
pattern | La forma dell'app: report, chat, dashboard o pipeline. | sotto |
host | Un nome host predefinito diverso per l'app. | sotto |
domains | I tuoi domini, serviti dall'app. | sotto, Pubblicazione |
branding | Colori, font, logo, tema, pulsanti. | sotto |
header | La barra in alto per i visitatori: link, un invito all'azione, un annuncio. | sotto |
auth | Metodo di accesso, cosa i visitatori possono aprire senza accesso, ruoli. | Accesso e ruoli |
limits | Limiti di frequenza e quote per utente (gli amministratori ne sono esenti). | Agenti e automazione, Dati |
agents | Gli agenti AI dell'app, i loro obiettivi, strumenti e memoria. | Agenti e automazione |
inputForm | Il modulo che un utente compila per avviare un'esecuzione dell'agente principale. | Viste, Dati |
data | Raccolte di record, job di dati, credenziali che gli utenti collegano. | Dati |
views | Le pagine dell'app. | Viste |
schedules | Agenti o job che girano secondo un calendario. | Agenti e automazione |
triggers | Eventi che avviano un agente, una squadra o un job, inviano un'email, scrivono un record o addebitano crediti. | Agenti e automazione |
teams | Agenti che lavorano insieme come uno solo. | Agenti e automazione |
approvals | Punti di controllo umani che un agente attende. | Agenti e automazione, Viste |
templates | Agenti che ogni utente crea per sé, con propri parametri e pianificazione. | Agenti e automazione, Viste |
slots | Piccole funzioni Python che il runtime esegue in una sandbox. | Agenti e automazione |
egress | Gli host esterni che gli strumenti HTTP dell'app possono chiamare. | Agenti e automazione |
channels | Da dove arrivano le conversazioni (la chat web, un numero di telefono, un bot, una casella di posta). | Messaggi |
notifications | Email agli utenti quando la loro esecuzione termina. | Messaggi |
serviceHours | Quando la chat dell'app deve rispondere in fretta. | Agenti e automazione |
billing | Come pagano gli utenti: crediti, pacchetti, piani. | Pagamenti e crediti |
mobile | L'app per telefono e le funzioni del telefono che usa. | Esportazione |
exports | Endpoint che l'app serve ad altri programmi. | Riferimento |
extensions | Logica personalizzata che il manifest non sa ancora esprimere, annotata come lacune documentate. | Riferimento |
L'elenco completo dei campi di ogni sezione è nel riferimento.
Convenzioni comuni
Chiavi
La key di una vista, un agente, un ruolo, una squadra, un job di dati e voci simili segue il pattern
^[a-z][a-z0-9_-]*$: inizia con una lettera minuscola e contiene lettere minuscole, cifre, _ e -.
Il name di un campo è più rigido: ^[a-z][a-z0-9_]*$ (niente trattini), perché i nomi dei campi diventano
segnaposto negli obiettivi degli agenti, come {city}.
Le chiavi devono essere univoche nella propria lista. Le altre parti del manifest vi fanno riferimento per chiave, e la validazione rifiuta un riferimento a una chiave che non esiste (vedi Validazione).
Testo traducibile
Ogni campo mostrato agli utenti come testo (titoli, etichette, aiuti, contenuto delle pagine, opzioni) accetta:
una stringa semplice, usata in ogni lingua:
title: Bookingsoppure una stringa per lingua, con il codice di due lettere come chiave:
title: { en: Bookings, it: Prenotazioni }
Un oggetto richiede almeno una lingua. Sono accettate solo chiavi di due lettere minuscole.
Come il runtime sceglie il testo per una pagina mostrata nella lingua lang:
- la stringa per
lang, se l'oggetto la contiene; - altrimenti la prima stringa dell'oggetto, nell'ordine in cui l'hai scritta;
- altrimenti un valore di riserva scelto dal runtime (spesso la chiave dell'elemento, es. la chiave di una vista nel menu).
Il valore di riserva del passo 2 è la prima lingua scritta, non defaultLang. Scrivi la lingua predefinita per prima
in ogni oggetto per avere lo stesso risultato ovunque.
La lingua della pagina si sceglie così: la lingua che il visitatore ha scelto con il selettore di lingua, altrimenti la
prima lingua delle preferenze del browser. Se quella lingua non è in langs, la pagina usa defaultLang, altrimenti
la prima voce di langs. Vedi Accesso e ruoli.
Le parole proprie del runtime (Sign in, Sign out, Start, Download CSV…) esistono in inglese e in italiano. In ogni altra lingua compaiono in inglese.
Markdown
Il contenuto delle pagine, i blocchi delle pagine, l'annuncio dell'intestazione e i report degli agenti usano un
Markdown ridotto e sicuro: titoli, elenchi, tabelle, grassetto, corsivo, codice e link a indirizzi https:// o a
percorsi della stessa app (/login, /v/new). L'HTML grezzo nel Markdown viene mostrato come testo, mai eseguito.
Una pagina può contenere HTML personalizzato solo in un blocco html, ripulito secondo un elenco di elementi ammessi
(vedi Viste).
Link
Ogni href nel manifest (link dell'intestazione, pulsanti dell'hero) deve iniziare con / (un percorso della stessa
app, non //), # (un'ancora nella pagina) o https://. Qualsiasi altro valore è rifiutato dalla validazione; al
momento della resa un link non sicuro diventa #.
Branding e tema
spec.branding imposta l'aspetto dell'app. Il runtime lo trasforma in variabili CSS su ogni pagina.
| Campo | Cosa fa |
|---|---|
palette | I colori: primary, accent, background, foreground. Ognuno è #rrggbb. |
paletteDark | Gli stessi quattro colori per il tema scuro. |
theme | light, dark o auto. auto segue l'impostazione del dispositivo e richiede paletteDark. dark usa paletteDark quando è impostata. |
tokens | Colori aggiuntivi con nome (#rrggbb), es. uno per ogni valore di stato. Ognuno diventa una variabile CSS --<name> (_ diventa -). |
tokensDark | I token per il tema scuro. |
fonts | body, display (titoli) e mono: nomi di famiglie Google Fonts, caricate con pesi da 400 a 900. Un nome può contenere lettere, cifre e spazi, fino a 41 caratteri; il resto viene ignorato. |
logo | Un SVG in linea (fino a 20.000 caratteri, ripulito) o l'URL https:// di un'immagine. |
wordmark | Il nome dell'app in fino a 4 parti, ognuna con un color facoltativo (una chiave della palette o dei token). Sostituisce displayName nell'intestazione. |
byline | Un testo piccolo dopo il nome, es. "by Acme". Traducibile. |
button | La chiave della palette o dei token usata per i pulsanti principali (predefinita accent). |
buttonShape | pill (predefinito), rounded o square. |
ghostButton | Pulsanti secondari: outline (predefinito, nel colore dei pulsanti) o neutral. |
headingWeight | Da 400 a 900, a passi di 100 (predefinito 700). |
headingTracking | normal o tight (lettere leggermente più vicine nei titoli). |
brandWeight | Peso del nome nell'intestazione: da 500 a 900. |
width | Larghezza della pagina: normal (1080 px) o wide (1200 px). |
Solo i valori di colore nella forma #rrggbb arrivano alla pagina. La validazione rifiuta theme: auto senza
paletteDark.
branding:
theme: auto
palette: { primary: "#14324a", accent: "#c0522b", background: "#faf7f2", foreground: "#1b1f24" }
paletteDark: { primary: "#9cc3e0", accent: "#e58a5f", background: "#111418", foreground: "#e9e6e1" }
fonts: { body: Inter, display: Fraunces }
buttonShape: rounded
width: wide
Intestazione
spec.header è la barra in alto per i visitatori.
| Campo | Cosa fa |
|---|---|
links | Fino a 8 link, ognuno {label, href}. Mostrati ai visitatori senza accesso e agli utenti con accesso che non hanno pagine nel menu. |
cta | Un pulsante {label, href}. Sostituisce il pulsante Sign in per i visitatori senza accesso. |
announcement | Una riga sopra l'intestazione, in Markdown (link ammessi). Mostrata a tutti. |
Gli utenti con accesso vedono il menu dell'app al posto dei link: le loro pagine, più link aggiuntivi per gli amministratori. Vedi Viste.
header:
links:
- { label: { en: How it works, it: Come funziona }, href: "#how-it-works" }
- { label: Pricing, href: /v/pricing }
cta: { label: { en: Start free, it: Inizia gratis }, href: /login }
announcement: { en: "New: [weekly city watch](/v/watches)", it: "Novità: [osservatorio settimanale](/v/watches)" }
L'intestazione mostra anche il selettore di lingua quando langs contiene più di una lingua.
pattern
pattern indica la forma dell'app:
| Valore | Forma |
|---|---|
report | Un utente compila un modulo, un agente lavora, l'utente riceve un report. |
chat | Una conversazione; ogni messaggio avvia l'agente. |
dashboard | Agenti o job girano secondo una pianificazione; gli utenti leggono i risultati. |
pipeline | Un agente configura una pipeline di dati, l'app la esegue e fa un report sui dati. |
Il runtime non cambia comportamento in base a pattern. Ciò che l'app fa dipende dalle sue viste, agenti, trigger e
pianificazioni. App Studio usa pattern per descrivere l'app.
Host e domini
Il runtime sceglie l'app dal nome host di ogni richiesta:
- un'app il cui
spec.host, o uno dei cuispec.domains, è uguale all'host; - altrimenti l'app il cui slug è il sottodominio:
<slug>.webrobot.eu.
Un'app risponde sempre su <slug>.webrobot.eu, anche quando ha un host.
host: un nome host diverso per l'app. Non mettere qui i tuoi domini.domains: i tuoi domini (es.app.example.com). Ognuno richiede un record DNS CNAME che punta a<slug>.webrobot.eu, e un certificato emesso quando pubblichi. Solo nomi di dominio in minuscolo; niente duplicati. Vedi Pubblicazione.
I link di accesso, i reindirizzamenti e le pagine di ritorno dai pagamenti usano sempre l'indirizzo proprio dell'app, mai un nome host inviato dal browser.
YAML o JSON
Il manifest è lo stesso documento in entrambi i formati:
- YAML è più facile da leggere e scrivere a mano. Gli esempi di queste pagine usano YAML.
- JSON è ciò che la piattaforma memorizza e ciò che App Studio salva. Il co-pilot propone i manifest in JSON.
Un modello che scrive un documento JSON lungo a volte chiude una parentesi di troppo o aggiunge un carattere dopo la fine. Quando App Studio legge un manifest proposto dal co-pilot, ripara solo questi due errori, al massimo 6 volte, e non indovina mai il contenuto. Ogni altro errore di sintassi resta un errore.
Validazione
Su un manifest girano due controlli. Si differenziano per ciò che bloccano.
Errori: validateManifest
Gli errori bloccano la pubblicazione. App Studio esegue questo controllo mentre modifichi e mostra il numero di problemi; il pulsante Publish resta disattivato finché ce ne sono. Salvare una bozza con errori è consentito, così il lavoro in corso non va mai perso. Il runtime valida di nuovo il manifest pubblicato prima di servirlo: un'app il cui manifest non è valido non viene servita, e il suo indirizzo mostra "No app is published on this address."
Il controllo ha due parti:
Lo JSON Schema. Tipi, campi obbligatori, enum, pattern, intervalli di valori e chiavi sconosciute. Il messaggio indica il percorso, es.
/spec/views/2/type: must be equal to one of the allowed values.Riferimenti e regole che lo schema non vede. Tra questi:
- ogni nome punta a qualcosa che esiste: viste mostrate in pagine e dashboard, agenti, job di dati, raccolte, piani e pacchetti, campi dei moduli, approvazioni, modelli, ruoli;
- nessuna raccolta usa un nome riservato (i dati propri del runtime, come
users,runs,files); defaultLangè una dilangs;theme: autohapaletteDark;- una vista modulo scrive una raccolta dichiarata che ha dei campi;
- una vista di prenotazione scrive una raccolta
ownedBy: user; - i segnaposto nel
goalTemplatedi un agente sono riempiti da qualcosa (un campo del modulo, una chiave di contesto, un valore predefinito del runtime); - i visitatori senza accesso non possono raggiungere i dati privati del proprietario attraverso un agente;
- le modalità di fatturazione sono coerenti (es.
creditsrichiede un modo per ottenere crediti); - le squadre non hanno cicli, la delega non va in loop, e un'approvazione è decisa da un ruolo che nessuno ottiene
solo registrandosi (o dall'utente che l'ha chiesta, con
decidedBy: requester).
I messaggi sono frasi semplici, es.
view home: a block shows unknown view 'pricing'.
Avvisi: lintManifest
Gli avvisi segnalano problemi di progettazione. Non bloccano mai la pubblicazione, e un'app pubblicata continua a funzionare quando viene aggiunto un nuovo avviso. App Studio li mostra quando il manifest non ha errori, e li rimanda al co-pilot.
I controlli principali:
- Chi riempie ogni raccolta. Una raccolta di record degli utenti (
ownedBy: useroinstance) letta da pagine, strumenti, select o trigger, ma che niente scrive (nessun modulo, prenotazione, strumento di un agente,writesToo scrittura da trigger). - Moduli che non possono salvare. Un modulo per tutti su una raccolta
sharedoapp: lì solo gli amministratori possono aggiungere record. - Amministratori con il menu vuoto. Il ruolo amministratore non è nei
rolesdi nessuna pagina del menu. - L'app per telefono (quando
spec.mobileè impostato). Funzioni del telefono dichiarate ma non usate, o usate ma non dichiarate, e altri controlli che applica anche l'esportazione. Vedi Esportazione.
Un esempio completo
Una piccola app di report: i visitatori vedono una pagina di benvenuto, gli utenti accedono, scelgono una città e un obiettivo, e un agente scrive un brief. Questo manifest supera entrambi i controlli senza errori e senza avvisi.
apiVersion: webrobot.eu/v1alpha1
kind: VerticalApp
metadata:
slug: city-brief
displayName: City Brief
tagline:
en: A one-page brief on a city, for your goal.
it: Un brief di una pagina su una città, per il tuo obiettivo.
langs: [en, it]
defaultLang: en
spec:
pattern: report
branding:
theme: light
palette: { primary: "#14324a", accent: "#c0522b", background: "#faf7f2", foreground: "#1b1f24" }
fonts: { body: Inter, display: Fraunces }
auth:
method: magic_link
anonymous: { views: [home] }
roles:
- { key: admin, assignedBy: admin_emails }
- { key: user, assignedBy: signup }
limits:
- { action: run, per: user, max: 10, window: day, roles: [user] }
agents:
- key: writer
role: main
description: Writes the brief from its own knowledge (no tools).
profile:
inline:
display_name: City Brief writer
crews:
- id: writer
engine: agent_sdk
model: claude-sonnet-5-5
max_turns: 4
system_prompt: >-
You write short, factual city briefs. Use Markdown with a level-1 title and
four level-2 sections. Under 350 words. Never invent figures.
goalTemplate: |-
City: {city_label}
Goal: {goal_kind_label}
{?notes}Notes from the user: {notes}{/notes}
Write the brief in the language with ISO code {lang}.
output: markdown
inputForm:
title: { en: New brief, it: Nuovo brief }
fields:
- name: city
type: select
required: true
label: { en: City, it: Città }
options:
- { value: bologna, label: Bologna }
- { value: lisbon, label: { en: Lisbon, it: Lisbona } }
- name: goal_kind
type: select
required: true
label: { en: Goal, it: Obiettivo }
options:
- { value: live, label: { en: Living there, it: Viverci } }
- { value: visit, label: { en: Visiting, it: Visitarla } }
- name: notes
type: textarea
maxLength: 400
label: { en: Notes (optional), it: Note (facoltative) }
views:
- key: home
type: page
nav: false
sections:
- type: hero
title: { en: "A **one-page brief** on any city", it: "Un **brief di una pagina** su ogni città" }
text: { en: Pick a city and a goal. An AI agent writes the brief., it: Scegli una città e un obiettivo. Un agente AI scrive il brief. }
actions:
- { label: { en: Sign in to start, it: Accedi e inizia }, href: /login }
- { key: new, type: new_run, title: { en: New brief, it: Nuovo brief }, roles: [user, admin] }
- { key: briefs, type: history, title: { en: My briefs, it: I miei brief }, source: run, roles: [user, admin] }
- { key: brief, type: report, source: run, printable: true, nav: false }
- { key: account, type: account, title: { en: Credits, it: Crediti }, roles: [user, admin] }
billing:
modes: [credits]
signupCredits: 100
costs:
agent:writer: 10
packs:
- { key: small, credits: 200, price: 5 }
Cosa fanno le singole parti:
{city_label}e{goal_kind_label}sono segnaposto predefiniti: l'etichetta dell'opzione scelta dall'utente, nella lingua dell'esecuzione.{?notes}…{/notes}è incluso solo quando l'utente ha scritto delle note.- L'agente è
inline: viene creato sulla piattaforma quando l'app è pubblicata. Vedi Agenti e automazione. homeè aperta ai visitatori (auth.anonymous.views). Il suo pulsante di accesso viene nascosto quando l'utente ha già fatto l'accesso.brief(tiporeport) è dove viene mostrata un'esecuzione terminata. Non è nel menu.- Ogni brief costa 10 crediti; i nuovi utenti ne ricevono 100. Vedi Pagamenti e crediti.
Per imparare il manifest passo per passo, segui il tutorial sul manifest.