WebRobot
App Builder · pagine

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:

ChiaveValore
apiVersionSempre webrobot.eu/v1alpha1.
kindSempre VerticalApp.
metadataL'identità dell'app: slug, nome, lingue.
specTutto ciò che l'app fa.

Nessun'altra chiave di primo livello è accettata.

metadata

CampoObbligatorioCos'è
slugsìIl nome univoco dell'app. Dà l'indirizzo predefinito <slug>.webrobot.eu.
displayNamesìIl nome dell'app, mostrato nell'intestazione, nella scheda del browser e nell'email di accesso. Una stringa semplice.
taglinenoUna riga sull'app. Diventa la descrizione della pagina per i motori di ricerca. Traducibile.
descriptionnoUna descrizione più lunga. Traducibile.
langsnoLe lingue dell'app, come codici di due lettere, es. [en, it]. Almeno una, senza duplicati.
defaultLangnoLa lingua usata quando la lingua del visitatore non è in langs. Deve essere una di langs.
timezonenoUn fuso orario IANA, es. Europe/Rome. Oggi il runtime lo usa solo per gli orari di servizio che non impostano un proprio fuso.
organizationIdnoL'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.

ChiaveA cosa serveApprofondisci
patternLa forma dell'app: report, chat, dashboard o pipeline.sotto
hostUn nome host predefinito diverso per l'app.sotto
domainsI tuoi domini, serviti dall'app.sotto, Pubblicazione
brandingColori, font, logo, tema, pulsanti.sotto
headerLa barra in alto per i visitatori: link, un invito all'azione, un annuncio.sotto
authMetodo di accesso, cosa i visitatori possono aprire senza accesso, ruoli.Accesso e ruoli
limitsLimiti di frequenza e quote per utente (gli amministratori ne sono esenti).Agenti e automazione, Dati
agentsGli agenti AI dell'app, i loro obiettivi, strumenti e memoria.Agenti e automazione
inputFormIl modulo che un utente compila per avviare un'esecuzione dell'agente principale.Viste, Dati
dataRaccolte di record, job di dati, credenziali che gli utenti collegano.Dati
viewsLe pagine dell'app.Viste
schedulesAgenti o job che girano secondo un calendario.Agenti e automazione
triggersEventi che avviano un agente, una squadra o un job, inviano un'email, scrivono un record o addebitano crediti.Agenti e automazione
teamsAgenti che lavorano insieme come uno solo.Agenti e automazione
approvalsPunti di controllo umani che un agente attende.Agenti e automazione, Viste
templatesAgenti che ogni utente crea per sé, con propri parametri e pianificazione.Agenti e automazione, Viste
slotsPiccole funzioni Python che il runtime esegue in una sandbox.Agenti e automazione
egressGli host esterni che gli strumenti HTTP dell'app possono chiamare.Agenti e automazione
channelsDa dove arrivano le conversazioni (la chat web, un numero di telefono, un bot, una casella di posta).Messaggi
notificationsEmail agli utenti quando la loro esecuzione termina.Messaggi
serviceHoursQuando la chat dell'app deve rispondere in fretta.Agenti e automazione
billingCome pagano gli utenti: crediti, pacchetti, piani.Pagamenti e crediti
mobileL'app per telefono e le funzioni del telefono che usa.Esportazione
exportsEndpoint che l'app serve ad altri programmi.Riferimento
extensionsLogica 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: Bookings
    
  • oppure 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:

  1. la stringa per lang, se l'oggetto la contiene;
  2. altrimenti la prima stringa dell'oggetto, nell'ordine in cui l'hai scritta;
  3. 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).

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.

CampoCosa fa
paletteI colori: primary, accent, background, foreground. Ognuno è #rrggbb.
paletteDarkGli stessi quattro colori per il tema scuro.
themelight, dark o auto. auto segue l'impostazione del dispositivo e richiede paletteDark. dark usa paletteDark quando è impostata.
tokensColori aggiuntivi con nome (#rrggbb), es. uno per ogni valore di stato. Ognuno diventa una variabile CSS --<name> (_ diventa -).
tokensDarkI token per il tema scuro.
fontsbody, 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.
logoUn SVG in linea (fino a 20.000 caratteri, ripulito) o l'URL https:// di un'immagine.
wordmarkIl nome dell'app in fino a 4 parti, ognuna con un color facoltativo (una chiave della palette o dei token). Sostituisce displayName nell'intestazione.
bylineUn testo piccolo dopo il nome, es. "by Acme". Traducibile.
buttonLa chiave della palette o dei token usata per i pulsanti principali (predefinita accent).
buttonShapepill (predefinito), rounded o square.
ghostButtonPulsanti secondari: outline (predefinito, nel colore dei pulsanti) o neutral.
headingWeightDa 400 a 900, a passi di 100 (predefinito 700).
headingTrackingnormal o tight (lettere leggermente più vicine nei titoli).
brandWeightPeso del nome nell'intestazione: da 500 a 900.
widthLarghezza 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.

CampoCosa fa
linksFino a 8 link, ognuno {label, href}. Mostrati ai visitatori senza accesso e agli utenti con accesso che non hanno pagine nel menu.
ctaUn pulsante {label, href}. Sostituisce il pulsante Sign in per i visitatori senza accesso.
announcementUna 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:

ValoreForma
reportUn utente compila un modulo, un agente lavora, l'utente riceve un report.
chatUna conversazione; ogni messaggio avvia l'agente.
dashboardAgenti o job girano secondo una pianificazione; gli utenti leggono i risultati.
pipelineUn 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:

  1. un'app il cui spec.host, o uno dei cui spec.domains, è uguale all'host;
  2. 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:

  1. 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.

  2. 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 di langs; theme: auto ha paletteDark;
    • una vista modulo scrive una raccolta dichiarata che ha dei campi;
    • una vista di prenotazione scrive una raccolta ownedBy: user;
    • i segnaposto nel goalTemplate di 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. credits richiede 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: user o instance) letta da pagine, strumenti, select o trigger, ma che niente scrive (nessun modulo, prenotazione, strumento di un agente, writesTo o scrittura da trigger).
  • Moduli che non possono salvare. Un modulo per tutti su una raccolta shared o app: lì solo gli amministratori possono aggiungere record.
  • Amministratori con il menu vuoto. Il ruolo amministratore non è nei roles di 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 (tipo report) è 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.