WebRobot
App Builder · pagine

Documentazione · App Builder

Riferimento del manifest

Questa pagina elenca ogni proprietà accettata dal manifest, generata dallo JSON Schema con cui validano App Studio e il runtime. Una proprietà che non è qui viene rifiutata. Per capire come le parti lavorano insieme leggi le pagine dei concetti: Manifest, Dati, Viste e pagine, Agenti e automazione.

I percorsi sono relativi alla sezione: items[] è un elemento di una lista, {key} è una chiave qualsiasi di una mappa. Obbl. indica le proprietà che devono esserci quando c’è la proprietà che le contiene.

Il documento

ProprietàTipoObbl.PredefinitoDescrizione
apiVersion"webrobot.eu/v1alpha1"sìVersione del formato del manifest. Deve essere esattamente webrobot.eu/v1alpha1; la piattaforma rifiuta qualsiasi altro valore quando l'app viene salvata.
kind"VerticalApp"sìTipo del documento. Deve essere esattamente VerticalApp.
metadataobjectsìIdentità dell'app: slug, nome e testi brevi, lingue e fuso orario. slug e displayName sono obbligatori.
metadata.slugstringsìIdentificatore univoco dell'app: da 3 a 40 caratteri tra lettere minuscole, cifre e trattini, deve iniziare con una lettera e non terminare con un trattino. Determina l'indirizzo predefinito <slug>.webrobot.eu e tiene i dati e le sessioni di accesso dell'app separati da quelli di ogni altra app; al salvataggio deve coincidere con lo slug dell'app sotto cui viene salvata. Valori: formato ^[a-z][a-z0-9-]{1,38}[a-z0-9]$.
metadata.displayNamestringsìNome dell'app così come lo vedono le persone: titolo della scheda del browser, nome nell'intestazione (a meno che non sia impostato branding.wordmark), piè di pagina, email di accesso (ridotto a una sola riga semplice di al massimo 60 caratteri), voci di pagamento al checkout e nome predefinito dell'app per telefono.
metadata.taglinetextFrase breve che descrive l'app. Il runtime la usa come meta description della pagina (per i risultati di ricerca e le anteprime dei link), nella lingua del visitatore.
metadata.descriptiontextDescrizione estesa dell'app. Accettata dallo schema; non ancora usata dal runtime.
metadata.organizationIdstring | integerOrganizzazione proprietaria dell'app. La piattaforma registra il proprietario al salvataggio dell'app e il runtime lo ricava da lì; il runtime non legge questo campo.
metadata.langslista di langLingue in cui l'app è offerta (codici di due lettere, almeno uno, senza duplicati). Se ne elenca più di una, l'intestazione mostra un selettore di lingua; il visitatore ottiene la lingua scelta, altrimenti quella del browser se presente nell'elenco, altrimenti defaultLang. Senza langs, l'app ha solo defaultLang (predefinito en). I testi dell'interfaccia propri del runtime esistono in inglese e in italiano; per le altre lingue si usa l'inglese. Valori: elementi min. 1.
metadata.defaultLanglangLingua usata quando la lingua del visitatore non è tra quelle di langs, e per i messaggi che l'app invia autonomamente (email, notifiche, report programmati). Deve essere una di langs. Predefinito: la prima voce di langs; se nessuno dei due è impostato, en.
metadata.timezonestringFuso orario IANA, ad es. Europe/Rome. Il runtime lo usa come fuso orario di spec.serviceHours quando quel blocco non ne imposta uno (predefinito Europe/Rome). Le espressioni cron di pianificazioni e trigger sono valutate in UTC, non in questo fuso.
metadata.referenceOfstringSolo per i manifest di riferimento che descrivono un'app costruita a mano: che cos'è quell'app. Accettato dallo schema; non usato dal runtime.

spec.pattern

enum · obbligatoria. Il tipo di app: report = un modulo avvia un'esecuzione dell'agente che produce un report; chat = una conversazione con un agente, un'esecuzione in background per ogni messaggio; dashboard = agenti o job pianificati riempiono dati che gli utenti si limitano a leggere; pipeline = un agente configura una pipeline di dati, l'app la esegue e produce un report sul dataset. Obbligatorio. Descrive il progetto; il runtime non cambia comportamento in base a esso: ciò che l'app mostra deriva da views e agents. Valori: report, chat, dashboard, pipeline.

spec.host

string. Nome host completo su cui risponde l'app, al posto del predefinito <slug>.webrobot.eu (l'app continua a rispondere anche sul suo indirizzo predefinito). I link nelle email inviate dall'app e l'indirizzo aperto dall'app per telefono usano questo host. I domini del cliente vanno in domains, non qui.

spec.domains

lista di string. Domini del cliente che servono questa app, ad es. app.example.com. Ognuno richiede un record DNS CNAME che punti all'indirizzo dell'app (<slug>.webrobot.eu); quando l'app viene pubblicata, la piattaforma instrada il dominio verso l'app e ne richiede il certificato TLS.

spec.branding

object. L'aspetto dell'app: colori, font, logo, nome nell'intestazione, pulsanti e larghezza della pagina. Il runtime lo traduce in variabili CSS su ogni pagina; ciò che viene omesso mantiene l'aspetto predefinito del runtime.

ProprietàTipoObbl.PredefinitoDescrizione
themeenumTema cromatico. light (o non impostato): vengono usati palette e tokens. dark: paletteDark e tokensDark li sostituiscono (solo se paletteDark è impostato). auto: segue l'impostazione chiaro/scuro del dispositivo e richiede paletteDark. Valori: light, dark, auto.
palettepaletteI quattro colori principali dell'app. Un colore omesso mantiene il valore predefinito del runtime (primary #1f2a44, accent #2563eb, background #f7f8fa, foreground #161b26). Li usa anche l'app per telefono: background per la barra di stato e la schermata iniziale, primary per lo sfondo dell'icona.
paletteDarkpaletteI colori del tema scuro, usati con theme: dark oppure con theme: auto quando il dispositivo è in modalità scura. Obbligatorio quando theme è auto. Il suo background è anche il colore scuro della schermata iniziale dell'app per telefono.
fontsobjectFamiglie di Google Fonts per il testo dell'app. Ogni nome può contenere solo lettere, cifre e spazi (al massimo 41 caratteri); gli altri nomi vengono ignorati. I font sono caricati con pesi da 400 a 900.
fonts.bodystringFamiglia di font del testo, ad es. Inter. Predefinito: il font di sistema.
fonts.displaystringFamiglia di font dei titoli e del nome dell'app nell'intestazione. Predefinito: il font del testo.
fonts.monostringFamiglia di font monospazio. Il runtime la carica da Google Fonts, ma nessuno stile di pagina la usa ancora.
logostringLogo mostrato prima del nome nell'intestazione e usato per l'icona dell'app per telefono. Può essere markup SVG inline (che inizia con <svg, al massimo 20.000 caratteri, sanificato: script e attributi non sicuri vengono rimossi) oppure un URL di immagine https://; qualsiasi altro valore viene ignorato.
tokensmappa di colorColori aggiuntivi con nome, ognuno pubblicato come variabile CSS --<name> (i trattini bassi diventano trattini; nomi fino a 41 caratteri, valori #rrggbb). Gli stili del runtime leggono questi nomi quando sono impostati: header, band, band-glow, heading, card, card-line, eyebrow, soft, button-ink. Qualsiasi token può essere richiamato anche da wordmark[].color, button e dagli stili inline delle sezioni.
wordmarklista di objectIl nome dell'app nell'intestazione scritto in un massimo di 4 parti, ciascuna con un proprio colore (ad es. due parole in due colori). Se impostato, sostituisce displayName nell'intestazione. Valori: elementi max. 4.
wordmark[].textstringsìTesto di questa parte (al massimo 40 caratteri). Valori: lunghezza max. 40.
wordmark[].colorstringNome di un colore della palette o di un token per questa parte (ad es. accent, o una chiave di tokens); viene applicato come var(--<name>). Senza di esso, la parte ha il colore predefinito dell'intestazione. Valori: formato ^[a-zA-Z][a-zA-Z0-9-]*$.
bylinetextTesto piccolo mostrato dopo il nome nell'intestazione, ad es. by Example Ltd.
buttonstringColore della palette o token usato per i pulsanti principali, i fumetti di chat dell'utente e il bordo dei pulsanti secondari, ad es. primary. Predefinito: accent. Valori: formato ^[a-zA-Z][a-zA-Z0-9-]*$.
widthenumLarghezza massima del contenuto della pagina: normal (predefinito) = 1080px; wide = 1200px. Valori: normal, wide.
tokensDarkmappa di colorI valori di tokens per il tema scuro (theme: dark, oppure theme: auto su un dispositivo in modalità scura). Applicati solo se paletteDark è impostato.
headingWeightenumPeso del font dei titoli (h1–h4): 400, 500, 600, 700, 800 o 900. Predefinito 700. Valori: 400, 500, 600, 700, 800, 900.
headingTrackingenumSpaziatura tra le lettere dei titoli: normal (predefinito) o tight (lettere leggermente più ravvicinate, -0.02em). Valori: normal, tight.
brandWeightenumPeso del font del nome dell'app nell'intestazione: 500, 600, 700, 800 o 900. Predefinito 700. Valori: 500, 600, 700, 800, 900.
buttonShapeenumAngoli di pulsanti, chip e campo di input della chat: pill (predefinito, completamente arrotondati), rounded (raggio 10px) o square (raggio 4px). Valori: pill, rounded, square.
ghostButtonenumStile dei pulsanti secondari: outline (predefinito) = trasparente, con testo e bordo nel colore dei pulsanti; neutral = sfondo delle card, colore normale del testo e bordo grigio. Valori: outline, neutral.

spec.auth

object. Come le persone accedono, che cosa possono usare i visitatori che non hanno effettuato l'accesso, e i ruoli dell'app.

ProprietàTipoObbl.PredefinitoDescrizione
methodenum"magic_link"Metodo di accesso. magic_link (predefinito): la persona inserisce la propria email e riceve un link monouso e un codice di 6 cifre, entrambi validi per 15 minuti (il codice viene invalidato dopo 5 tentativi errati); la sessione dura 30 giorni. none: i visitatori possono aprire ogni pagina senza accedere e l'intestazione non mostra il pulsante di accesso. Valori: magic_link, none.
publicbooleanSe true, i visitatori che non hanno effettuato l'accesso possono aprire ogni pagina dell'app (i roles di una pagina si applicano solo agli utenti autenticati). Ciò che una pagina mostra segue comunque le regole sui dati: i visitatori non vedono mai record che appartengono a un utente. Predefinito false.
anonymousobjectChe cosa possono usare i visitatori che non hanno effettuato l'accesso, quando public non è impostato: le pagine elencate in views e gli agenti elencati in agents.
anonymous.agentslista di keyAgenti indicati come utilizzabili dai visitatori senza accesso. Ciascuno deve essere una chiave di agente. I loro strumenti dell'app sono limitati: nessuno strumento può raggiungere una raccolta ownedBy: org, scrivere in una raccolta ownedBy: app o shared, inviare dati a un servizio esterno (strumenti http diversi da GET) o usare la credenziale dell'utente; la validazione rifiuta questi strumenti e il runtime li blocca. Avviare un'esecuzione o inviare un messaggio in chat richiede comunque l'accesso.
anonymous.viewslista di keyPagine che i visitatori possono aprire senza accedere. Ciascuna deve essere una chiave di vista. Una vista modulo elencata qui accetta invii dai visitatori solo verso una raccolta ownedBy: org (la casella del proprietario), al massimo 5 all'ora dallo stesso indirizzo IP, senza allegati.
roleslista di objectI ruoli dell'app. Un utente autenticato ha un solo ruolo, determinato a ogni richiesta in quest'ordine: il ruolo admin_emails se la sua email è nell'elenco degli amministratori dell'app; altrimenti un ruolo salvato nel suo record utente; altrimenti un ruolo derived la cui raccolta lo nomina; altrimenti il ruolo signup (se non ne è dichiarato nessuno, il ruolo è user). I ruoli sono usati da viste, campi, regole di accesso alle raccolte, approvazioni, limiti e notifiche.
roles[].keykeysìIdentificatore del ruolo, richiamato altrove (ad es. roles: [admin] su una vista, role:<key> nelle notifiche).
roles[].labeltextNome visualizzato del ruolo. Non ancora mostrato dal runtime.
roles[].assignedByenumCome un utente ottiene il ruolo. admin_emails: utenti la cui email è nell'elenco degli amministratori dell'app (gestito fuori dal manifest); questo ruolo è l'amministratore dell'app: accede a tutti i dati ed è esente da limiti e vincoli di piano. signup: ogni utente che accede senza un altro ruolo (conta solo il primo ruolo signup). derived: attribuito finché un record di una raccolta riporta l'email dell'utente (vedi from); prende il posto del ruolo signup, e l'utente mantiene anche le pagine del ruolo signup. admin / invite: il ruolo è rispettato quando è salvato nel record dell'utente; il runtime non ha ancora una pagina o un'API per assegnarlo. Valori: admin_emails, admin, signup, invite, derived.
roles[].fromstring | lista di stringSolo per assignedBy: derived: dove viene cercata l'email dell'utente, nella forma collection:<name>.<emailField> (o un elenco di queste: basta una corrispondenza). Il campo può contenere un'email o un elenco di email; il confronto ignora maiuscole e minuscole. Se corrispondono più ruoli derivati, prevale il primo nell'ordine del manifest.

spec.limits

lista di object. Limiti di frequenza e quote applicati dal runtime. Una richiesta oltre il limite viene rifiutata con HTTP 429 (limit reached: …). Gli amministratori dell'app sono esenti dai limiti sulle esecuzioni e sui record che creano. Ogni finestra è conteggiata a ritroso a partire da adesso (finestra mobile).

ProprietàTipoObbl.PredefinitoDescrizione
[].actionstringsìChe cosa si conta. run: esecuzioni avviate da un utente dal modulo. agent:<key>: esecuzioni di quell'agente avviate da un utente, e anche avvii di quell'agente da trigger, approvazioni e date. agents: ogni avvio di agente causato da un evento (trigger, approvazioni, date). create:<collection>: record creati da un utente, tramite un modulo o uno strumento write/append di un agente. chat e login sono accettati ma non applicati da qui; chat e accesso hanno limiti fissi propri (chat: 30 messaggi all'ora per utente e 60 per IP; accesso: 10 richieste all'ora per IP e 3 per indirizzo email).
[].perenum"user"Di chi si contano insieme le azioni. user (predefinito): ogni utente separatamente; è l'unico valore usato per run, agent:<key> sulle esecuzioni avviate da un utente, e create:<collection>. app: tutti gli avvii dell'app insieme; usato solo per gli avvii di agenti causati da eventi. ip e org sono accettati ma non ancora applicati. Per gli agenti avviati da eventi, un limite si applica solo quando per è scritto esplicitamente come user o app. Valori: user, ip, org, app.
[].maxintegersìConteggio massimo nella finestra (almeno 1). Per run, agent:<key> e create:<collection>, un piano in plans può aumentarlo. Valori: ≥ 1.
[].windowenumsìPeriodo conteggiato: minute, hour, day (24 ore), month (30 giorni) o total (da sempre: una quota, ad es. al massimo N record nel piano). total non si applica agli avvii di agenti causati da eventi. Valori: minute, hour, day, month, total.
[].roleslista di keySi applica solo agli utenti che hanno uno di questi ruoli (vuoto = tutti). Verificato solo per run e agent:<key> sulle esecuzioni avviate da un utente; create:<collection> e gli agenti avviati da eventi lo ignorano. I visitatori non possono avviare esecuzioni, quindi anonymous qui non ha ancora effetto.
[].rollingbooleanFinestra mobile (le ultime 24 ore) invece di quella di calendario. Accettato dallo schema ma ignorato: il runtime conta sempre una finestra mobile a ritroso da adesso.
[].plansmappa di integerUn massimo diverso per chiave di piano o di pacchetto: un utente che ha quel piano ottiene questo valore al posto di max; -1 = illimitato. Con più piani si applica il valore più alto; un utente senza piani ottiene max. Applicato a run, agent:<key> sulle esecuzioni avviate da un utente, e create:<collection> tramite strumenti degli agenti; i moduli e gli agenti avviati da eventi usano solo max. Ogni chiave deve essere un piano o un pacchetto di spec.billing.

spec.agents

lista di object · obbligatoria. Gli agenti dell'app (almeno uno). Ciascuno è un profilo agentico che il runtime avvia per un'esecuzione da modulo, un messaggio in chat, una pianificazione, un trigger, un'istanza di template o una delega. Le chiavi degli agenti sono richiamate come agent:<key> nelle sorgenti delle viste, in billing.costs e in limits. Valori: elementi min. 1.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca dell'agente. Le altre parti del manifest vi fanno riferimento (sorgenti e costi agent:<key>, start.agent, delegates, passaggi dei team, canali). Alla pubblicazione un agente inline diventa un profilo chiamato <slug>-<key>, e una delega verso di esso diventa lo strumento ask_<key> (i trattini diventano trattini bassi). Un team non può usare la stessa chiave.
[].roleenum"main"Solo main (il predefinito) cambia il comportamento: un'esecuzione da modulo sceglie tra gli agenti main (il primo il cui when corrisponde, altrimenti il primo agente main, altrimenti il primo agente), e una vista chat senza un agente noto ripiega sul primo agente main. Gli altri valori (designer, setup, analyst, helper, scheduled) sono etichette: il runtime tratta questi agenti allo stesso modo e li avvia solo quando qualcosa li nomina (una pianificazione, un trigger, un template, una delega, una vista chat). Valori: main, designer, setup, analyst, helper, scheduled.
[].descriptionstringChe cosa fa l'agente, in una frase. La pubblicazione la usa come descrizione del profilo (predefinito <displayName> — <key>), e un altro agente che delega a questo la vede nella descrizione del suo strumento ask_<key>.
[].profilesìIl profilo agentico eseguito dall'agente: esattamente uno tra ref (un profilo esistente) o inline (una definizione pubblicata con l'app). Il template del goal proprio del profilo può includere il goal dell'app come {goal}. Un agente con profilo inline non può essere eseguito finché l'app non è pubblicata (il runtime risponde 409 publish the app first).
[].profile.refinteger | stringId o nome di un profilo agentico esistente dell'organizzazione dell'app. La pubblicazione scrive qui anche l'id del profilo creato da inline. Il runtime avvia questo profilo con il goal dell'agente.
[].profile.inlineobjectUna definizione di agente inline (il contratto di Agent Studio; crews è obbligatorio). Alla pubblicazione diventa un profilo chiamato <slug>-<key>, creato una volta e aggiornato nelle pubblicazioni successive; l'endpoint MCP proprio dell'app (per appTools, delegates, awaits, memory) e i mcpServers vengono aggiunti a ogni crew; una definizione senza orchestration riceve un DAG sulle sue crew. Gli agenti che fanno parte di un team devono essere inline.
[].whenstringCondizione sui valori del modulo di esecuzione che seleziona questo agente tra gli agenti main, ad es. mode == 'market'. Sintassi supportata: field == 'x', field != 'x', field (valore vero), !field, uniti da && e ||; qualsiasi altra espressione è falsa. Viene valutata solo nelle esecuzioni da modulo.
[].goalTemplatestringIl compito inviato all'agente. {name} viene sostituito da un campo del modulo, una chiave di contesto o un valore predefinito: {<field>_label} (etichetta dell'opzione scelta), {<field>_text} (testo estratto da un file caricato), {date} (UTC, YYYY-MM-DD), {lang}, {user} (email), {role}; in una chat anche {message}, {history} e {session}. {?name}...{/name} mantiene il blocco solo quando name non è vuoto, {!name}...{/name} solo quando è vuoto; la validazione rifiuta segnaposto sconosciuti e blocchi non chiusi. Senza di esso, un'esecuzione da modulo invia una riga label: value per ogni campo compilato, e una chat invia la conversazione fin lì e il nuovo messaggio.
[].contextlista di objectValori aggiuntivi risolti all'avvio di un'esecuzione da modulo, prima che venga trattenuto qualsiasi credito, e resi disponibili a goalTemplate sotto la chiave di ciascuna voce. Li risolvono solo le esecuzioni da modulo (non chat, pianificazioni, trigger o istanze di template).
[].context[].keystringsìNome del segnaposto sotto cui viene messo il valore, usato nel goal come {<key>}. Lettere minuscole, cifre e trattini bassi, deve iniziare con una lettera. Valori: formato ^[a-z][a-z0-9_]*$.
[].context[].fromstringsìDa dove proviene il valore. collection:<name>.<field>: quel campo del record in questione (quello scelto in un campo del modulo alimentato da optionsFrom: collection:<name>, altrimenti il record più recente dell'utente in una raccolta di proprietà dell'utente). collection:<name>: i record che l'utente può leggere, come righe JSON (al massimo 30 record, 8000 caratteri). user.<field>: un campo dell'utente autenticato (email, name, plans…). slot:<key>: lo slot Python viene eseguito su {values, lang}; un risultato di tipo oggetto aggiunge i suoi campi ai valori del goal, qualsiasi altro risultato va sotto key. session, page e derived:<extension> sono accettati dallo schema ma non ancora risolti dal runtime.
[].variablesmappa di stringVariabili del profilo che l'app imposta a ogni esecuzione da modulo: {profileVar: template}. Ogni valore viene elaborato come un template del goal (valori del modulo e del contesto, {lang}, {user}) e inviato al profilo come input accanto al goal. Le inviano solo le esecuzioni da modulo.
[].startOptionsobjectCampi aggiuntivi per l'avvio dell'agente. Le chiavi forceReauthor, llmProvider, engine, camoufoxMode, ttlSeconds, activeDeadlineSeconds e clusterSelector sono opzioni di avvio; qualsiasi altra chiave (ad es. current_yaml) viaggia come input accanto al goal. Applicati a esecuzioni da modulo, messaggi in chat e pianificazioni; non alle esecuzioni avviate da trigger, deleghe o istanze di template.
[].appToolslista di appToolStrumenti che l'app stessa fornisce a questo agente, serviti dall'endpoint MCP del runtime (/api/mcp). La pubblicazione assegna a ogni agente un proprio URL e token, così un agente vede solo i propri strumenti più quelli generati dai suoi collegamenti. Il nome di uno strumento può comparire in più agenti solo se fa la stessa cosa (stessa azione, destinazione e limiti). Gli strumenti con extension non vengono serviti.
[].outputenum"markdown"La forma della risposta dell'agente: markdown (predefinito), markdown+json, json, pipeline_yaml, final_block. Accettato dallo schema; non ancora usato dal runtime. Il modo in cui un risultato diventa un record è definito da writesTo.parse. Valori: markdown, markdown+json, json, pipeline_yaml, final_block.
[].resultSchemaobjectJSON Schema della parte strutturata dell'output. Accettato dallo schema; non ancora usato dal runtime.
[].writesToobjectTrasforma ogni esecuzione completata di questo agente (pianificata, da trigger o da istanza di template) in un record di collection (le esecuzioni da modulo e i messaggi in chat non scrivono record). Il record contiene i campi estratti, report (la risposta dal suo primo titolo in poi), completedAt e date, più i valori predefiniti dei campi della raccolta; porta con sé l'utente dell'evento e, per un'istanza di template, l'istanza. La sua scrittura attiva i trigger di inserimento della raccolta.
[].writesTo.collectionstringsìLa raccolta dichiarata in cui viene scritto il record (non una riservata). Un trigger su questa stessa raccolta che avvia questo agente deve avere un filtro where (o op: update), altrimenti la validazione lo rifiuta.
[].writesTo.parseenum"whole"Come la risposta diventa campi. whole (predefinito): nessun campo aggiuntivo, solo report, completedAt, date. markdown_sections: ogni sezione ## Heading diventa un campo con il nome del titolo (in minuscolo, i caratteri non alfanumerici come _). json_last e final_block (stesso comportamento): i campi dell'ultimo blocco delimitato ```json della risposta. Valori: markdown_sections, json_last, final_block, whole.
[].writesTo.keyBystringCampo del record costruito usato come suo id, ad es. date: un'esecuzione successiva con lo stesso valore sostituisce il record (un segnale al giorno). Senza di esso, o quando il campo manca, l'id è <date>_<timestamp>. Ignorato per le esecuzioni da istanza di template, che producono sempre un record per esecuzione.
[].limitsobjectLimiti di esecuzione per l'agente (turni, budget, tempo). Accettati dallo schema; non ancora usati dal runtime. I limiti propri dell'app sugli avvii sono in spec.limits (agent:<key>, agents, run).
[].limits.maxTurnsintegerNumero massimo di turni dell'agente (minimo 1). Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 1.
[].limits.maxBudgetUsdnumberSpesa massima di un'esecuzione, in dollari USA. Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0.
[].limits.timeoutSecondsintegerDurata massima di un'esecuzione, in secondi (minimo 30). Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 30.
[].mcpServerslista di objectServizi esterni (POS, consegne, calendario…) come server MCP, al massimo 10. Alla pubblicazione vengono aggiunti a ogni crew del profilo inline dell'agente (un profilo ref non viene modificato). Non inserire mai segreti qui: il valore di un header può richiamare ${VAR}, una credenziale dell'organizzazione, e la validazione rifiuta un header che sembra un segreto in chiaro. Valori: elementi max. 10.
[].mcpServers[].namestringsìNome del server nell'elenco degli strumenti dell'agente: prima una lettera minuscola, poi lettere minuscole, cifre, _ o -, al massimo 31 caratteri. Un server della crew con lo stesso nome viene sostituito. Valori: formato ^[a-z][a-z0-9_-]{0,30}$.
[].mcpServers[].urlstringsìL'endpoint MCP del server; deve iniziare con https://. Valori: formato ^https://.
[].mcpServers[].headersmappa di stringHeader HTTP inviati al server, ad es. {"Authorization": "Bearer ${POS_API_KEY}"}. Usare solo riferimenti ${VAR}: la validazione rifiuta un valore che, tolti i riferimenti ${VAR}, contiene ancora una sequenza di 20 o più tra lettere, cifre, _ o -.
[].mcpServers[].allow"all" | lista di stringQuali strumenti del server l'agente può usare: all (il predefinito se omesso) o un elenco di nomi di strumenti.
[].delegateslista di stringAgenti a cui questo può affidare un sotto-compito e attenderne il risultato. Ciascuno diventa lo strumento ask_<agent> (argomenti: task, al massimo 8000 caratteri); il runtime avvia quell'agente e attende la sua risposta fino a 150 secondi, altrimenti restituisce still working con l'id dell'esecuzione. La destinazione deve essere pubblicata; un agente non può delegare a se stesso e i cicli di delega vengono rifiutati.
[].awaitslista di stringApprovazioni che questo agente può richiedere. Ciascuna diventa lo strumento request_<approval> (argomenti: summary, al massimo 500 caratteri, e request, un oggetto di al massimo 32.000 caratteri in JSON); restituisce subito lo stato pending, e un trigger sulla decisione dell'approvazione riprende il lavoro.
[].memoryenum"none"Note persistenti che l'agente conserva. none (predefinito): nessuna memoria. user: una nota per ogni utente dell'app. instance: una nota per ogni istanza di template (un template deve istanziare questo agente). Le note (al massimo 4000 caratteri) vengono aggiunte al compito dell'agente quando l'utente è noto, e l'agente le sostituisce con lo strumento generato remember. Valori: none, user, instance.

spec.inputForm

object. Il modulo che avvia un'esecuzione (pattern report): i suoi campi diventano i valori del goal dell'agente principale. Viene mostrato nelle viste di tipo new_run.

ProprietàTipoObbl.PredefinitoDescrizione
titletextTitolo del modulo di esecuzione, mostrato quando la vista new_run non ha un titolo proprio.
fieldslista di fieldCampi del modulo di esecuzione. I loro valori riempiono i segnaposto {field} del goalTemplate dell'agente; una select fornisce anche {<field>_label} (l'etichetta dell'opzione scelta) e un campo file {<field>_text}. Senza goalTemplate, il goal è una riga label: value per ogni campo compilato.
exampleslista di objectInput di esempio precompilati, pensati per essere mostrati come chip. Accettati dallo schema; non ancora usati dal runtime (le viste chat hanno i propri examples).

spec.data

object. I dati dell'app: i job di dati della piattaforma i cui dataset possono essere mostrati nelle pagine, le raccolte di record proprie dell'app e le chiavi API che gli utenti collegano per i servizi esterni.

ProprietàTipoObbl.PredefinitoDescrizione
jobslista di objectJob di dati della piattaforma usati dall'app. Un job è raggiungibile tramite la sua chiave da un blocco data di una pagina (source: job:<key>), da una pianificazione (job) o da un trigger (start.job); deve avere projectId e jobId (impostati a mano o compilati quando viene pubblicata una pipeline inline), altrimenti il blocco mostra "Job not linked." e l'avvio viene saltato.
jobs[].keykeysìNome del job all'interno dell'app (lettere minuscole, cifre, _ e -, deve iniziare con una lettera). Richiamato come job:<key> nei blocchi di dati e come job in pianificazioni e trigger; la validazione rifiuta un riferimento a una chiave sconosciuta.
jobs[].descriptionstringTesto libero per chi legge il manifest. Il runtime non lo mostra né lo usa.
jobs[].projectIdinteger | stringId del progetto della piattaforma che contiene il job. Insieme a jobId, il runtime lo usa per avviare il job e per leggere il dataset del suo task più recente. Viene impostato dalla pubblicazione di una pipeline inline.
jobs[].jobIdinteger | stringId del job della piattaforma. Obbligatorio, insieme a projectId, perché il job possa essere avviato o letto; viene impostato dalla pubblicazione di una pipeline inline.
jobs[].pipelineobjectDa dove proviene la pipeline del job. Viene gestito solo inline: la pubblicazione crea (o aggiorna, per nome) un progetto con il nome dello slug dell'app e una pipeline e un job chiamati <slug>-<key>, scrive i loro id in projectId/jobId e sostituisce inline con ref. fromAgent, runBy, datasetMatch ed extension sono accettati dallo schema ma non ancora usati dal runtime.
jobs[].pipeline.refinteger | stringNome o id di una pipeline esistente. La pubblicazione scrive ref: <slug>-<key> dopo aver creato una pipeline inline. Il runtime non risolve ref da solo: per usare un job esistente, impostare anche projectId e jobId.
jobs[].pipeline.inlinestringLa pipeline come testo YAML: un elenco di stage, una specifica di pipeline o un intero documento kind: Pipeline (di cui si conserva lo spec). Alla pubblicazione viene applicata alla piattaforma e gli id del job vengono compilati; qualsiasi altro contenuto fa fallire la pubblicazione con "inline pipeline is not YAML stages or a pipeline spec".
jobs[].pipeline.fromAgentstringChiave di un agente destinato a produrre lo YAML della pipeline. Accettato dallo schema; non ancora usato dal runtime.
jobs[].pipeline.runBystringChiave di un agente destinato a costruire ed eseguire il job autonomamente, mentre l'app trova il dataset in seguito. Accettato dallo schema; non ancora usato dal runtime.
jobs[].pipeline.datasetMatchstringCon runBy: un pattern di nome per trovare il dataset dell'agente. Accettato dallo schema; non ancora usato dal runtime.
jobs[].pipeline.extensionstringNome di codice personalizzato destinato a comporre la pipeline. Accettato dallo schema; non ancora usato dal runtime.
jobs[].paramsobjectVariabili della pipeline collegate a campi del modulo, nella forma {variable: '{field}'}. Accettato dallo schema; non ancora usato dal runtime: i job vengono avviati senza parametri.
jobs[].perRecordstringcollection:<name>: pensato per creare un job (e una pianificazione) per ogni record in fase di esecuzione. La validazione verifica che la raccolta sia dichiarata; non ancora usato dal runtime.
jobs[].schedulestringUn'espressione cron destinata a eseguire il job a intervalli. Accettato dallo schema; non ancora usato dal runtime: per eseguire un job a intervalli, usare spec.schedules con job, oppure un trigger con on.cron e start.job.
jobs[].ingestTo"none" | object | lista di objectDove sarebbero dovute andare le righe del job dopo ogni esecuzione (none, una destinazione o un elenco di destinazioni). Accettato dallo schema; non ancora usato dal runtime: le pagine leggono direttamente il dataset più recente di un job tramite un blocco data.
jobs[].ingestTo.kindenumsìcollection: le righe vanno in una raccolta dell'app; search: le righe vanno in un indice di ricerca. Accettato dallo schema; non ancora usato dal runtime. Valori: collection, search.
jobs[].ingestTo.targetstringsìNome della raccolta (kind collection) o nome dell'indice di ricerca (kind search). Accettato dallo schema; non ancora usato dal runtime.
jobs[].ingestTo.mappingmappa di stringMappatura delle colonne nella forma {targetField: sourceColumn}. Accettato dallo schema; non ancora usato dal runtime.
jobs[].ingestTo.keyBystringIl campo che identifica una riga, così che una nuova esecuzione la aggiorni invece di duplicarla. Accettato dallo schema; non ancora usato dal runtime.
jobs[].ingestTo.incrementalbooleanIndica se a ogni esecuzione verrebbero copiate solo le righe nuove. Accettato dallo schema; non ancora usato dal runtime.
jobs[].ingestTo.retentionDaysintegerGiorni per cui verrebbero conservate le righe copiate (almeno 1). Accettato dallo schema; non ancora usato dal runtime (per i record, vedi collections[].retentionDays). Valori: ≥ 1.
collectionslista di objectLe raccolte di record proprie dell'app, conservate nello store dell'app. Ogni riferimento a una raccolta in qualsiasi punto dello spec (sorgenti collection:<name>, strumenti, trigger, moduli) deve indicarne una dichiarata qui, e il runtime rifiuta di leggere o scrivere una raccolta non dichiarata. I nomi del runtime come users, runs, files, credentials o approvals sono riservati e vengono rifiutati.
collections[].namekeysìNome della raccolta (lettere minuscole, cifre, _ e -, deve iniziare con una lettera). Deve essere univoco e non può essere un nome riservato del runtime. Gli id dei nuovi record iniziano con le sue prime tre lettere.
collections[].descriptionstringTesto breve mostrato accanto alla raccolta nella pagina dati degli amministratori.
collections[].fieldslista di fieldI campi di un record. Determinano le viste modulo (e la pagina dati degli amministratori e l'importazione CSV, da cui i campi file sono esclusi), lo schema degli argomenti degli strumenti write e append degli agenti, le etichette e le etichette delle opzioni nei blocchi di dati, e i valori predefiniti dei nuovi record. Gli strumenti degli agenti possono comunque salvare campi non elencati: l'elenco non viene imposto sulle loro scritture.
collections[].ownedByenum"user"Chi possiede i record, il che stabilisce chi può leggerli (predefinito user). user: ogni record appartiene all'utente che l'ha creato e solo quell'utente lo legge e lo modifica. instance: come user, e un'esecuzione di agente di un'istanza di template raggiunge solo i record di quell'istanza; moduli e scritture dei trigger non possono puntare a questa raccolta. app e shared: un unico insieme di record che ogni utente (autenticato o no, dove la pagina lo consente) può leggere; solo gli amministratori aggiungono record tramite moduli e la pagina dati, gli agenti scrivono tramite i loro strumenti. org: il back office del proprietario: solo gli amministratori lo leggono; gli utenti autenticati e i visitatori autorizzati possono inviarvi record tramite un modulo ma non leggerli. Gli amministratori dell'app leggono e modificano tutto; le regole access concedono di più ad altri ruoli. Valori: user, org, app, shared, instance.
collections[].parentstringRaccolta padre: record pensati per stare sotto un record padre. Accettato dallo schema; non ancora usato dal runtime.
collections[].sharinglista di enumInviti per singolo record (viewer, editor). Accettato dallo schema; non ancora usato dal runtime: usare le regole access per permettere ad altri utenti di raggiungere i record. Valori: viewer, editor.
collections[].searchablebooleanContrassegna la raccolta per la ricerca. Accettato dallo schema; non ancora usato dal runtime.
collections[].accesslista di objectRegole che permettono agli utenti con un dato ruolo di raggiungere record che non possiedono (al massimo 10). Un utente con role legge, e con can: [read, write] anche modifica, i record i cui campi corrispondono a where; senza where, tutti i record. Le applicano viste, blocchi di dati, strumenti dell'app degli agenti, contesto degli agenti e select alimentate dalla raccolta. La validazione rifiuta una regola per un ruolo sconosciuto, una regola senza where per il ruolo assegnato alla registrazione, e una regola di sola lettura su una raccolta app o shared (che tutti leggono già). Valori: elementi max. 10.
collections[].access[].rolekeysìIl ruolo a cui si applica la regola: una chiave di spec.auth.roles (un utente corrisponde anche tramite un ruolo di registrazione che conserva accanto a uno derivato). I ruoli di amministratore non hanno bisogno di regole: gli amministratori raggiungono ogni record.
collections[].access[].wheremappa di string | number | booleanQuali record copre la regola: ogni campo elencato deve corrispondere (al massimo 4). "{user.email}" e "{user.id}" indicano l'email e l'id dell'utente; i valori che contengono @ sono confrontati ignorando maiuscole e minuscole e corrispondono anche a un campo elenco che li contiene; gli altri valori devono essere uguali come testo. Senza where, il ruolo raggiunge ogni record.
collections[].access[].canlista di enum["read"]Che cosa può fare il ruolo sui record corrispondenti (predefinito [read]): read permette di vederli; write permette di modificarli (ad esempio tramite un modulo di modifica o lo strumento write di un agente). Valori: read, write.
collections[].retentionDaysintegerI record più vecchi di questo numero di giorni (da 1 a 3650) vengono eliminati automaticamente, una volta al giorno dallo scheduler del runtime, in base alla data di creazione del record (o dell'ultimo aggiornamento se non ha data di creazione); fino a 5.000 record per raccolta al giorno. Valori: ≥ 1; ≤ 3650.
credentialslista di objectChiavi API che gli utenti dell'app collegano nella pagina dell'account (è richiesta una vista di tipo account quando è dichiarata una credenziale api_key). Le chiavi sono cifrate a riposo, non vengono mai più mostrate (solo le ultime quattro cifre), non vengono mai inserite nel goal di un agente; uno strumento dell'app con azione http e http.credential riceve la chiave aggiunta alla propria richiesta. Oggi funziona solo il tipo api_key; oauth e mcp non sono ancora disponibili.
credentials[].providerstringsìNome del servizio; uno strumento dell'app http punta a questa credenziale con http.credential.provider. Ogni utente (o l'app, con scope org) conserva una chiave per provider.
credentials[].labeltextNome del servizio mostrato nella pagina dell'account (predefinito: provider).
credentials[].kindenumCome si collega l'utente (predefinito api_key). api_key: l'utente incolla una chiave (da 8 a 4.000 caratteri, senza spazi). oauth e mcp: non ancora disponibili; il runtime ignora queste voci. Valori: api_key, oauth, mcp.
credentials[].urlstringkind mcp: l'indirizzo del server MCP dell'utente. Accettato dallo schema; non ancora usato dal runtime (mcp non è disponibile).
credentials[].allowToolslista di stringkind mcp: gli strumenti del server MCP dell'utente che gli agenti possono chiamare. Accettato dallo schema; non ancora usato dal runtime.
credentials[].scopeenum"user"Di chi è la chiave (predefinito user). user: ogni utente salva la propria chiave e lo strumento usa la chiave dell'utente per cui agisce; uno strumento del genere richiede un utente autenticato, quindi non può appartenere a un agente che i visitatori usano senza accedere. org: una sola chiave per tutta l'app, che solo gli amministratori dell'app possono vedere, salvare o rimuovere nella pagina dell'account. Valori: user, org.
credentials[].requiredbooleanIndica che il collegamento è necessario all'app. Accettato dallo schema; non ancora usato dal runtime: nulla obbliga l'utente a collegarsi, e uno strumento che richiede la chiave mancante fallisce con "the user has not connected <provider>: ask them to connect it on their account page".
credentials[].helptextDove l'utente trova la chiave; mostrato sotto il servizio nella pagina dell'account.
credentials[].hostLabeltextSe impostato, la pagina dell'account chiede anche l'host dell'utente (mostrato come segnaposto di quel campo), per gli strumenti il cui URL inizia con https://{host}. L'host deve corrispondere a una voce con carattere jolly di spec.egress.hosts (ad es. *.myshopify.com), altrimenti il salvataggio viene rifiutato.

spec.views

lista di object. Le pagine dell'app. Ogni vista si apre su /v/<key>; le viste che un utente autenticato può aprire (eccetto report e run, e quelle con nav: false) formano il menu. La home page è la vista con chiave home, se il visitatore può aprirla, altrimenti la prima vista del menu.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìNome univoco della vista: lettere minuscole, cifre, _ e -, deve iniziare con una lettera. La vista è servita su /v/<key>; la chiave home la rende la home page. Le altre parti del manifest (children, blocchi di pagina, auth.anonymous.views, submit.redirect) vi fanno riferimento con questa chiave.
[].typeenumsìChe cos'è la vista. new_run: il modulo di input (spec.inputForm) che avvia un'esecuzione; report: dove viene mostrata un'esecuzione completata (/r/<id> usa il suo title e printable; aprire la vista stessa porta alla home page); run: aprirla porta alla home page; history: le esecuzioni dell'utente (accesso richiesto); chat: una conversazione con un agente (solo utenti autenticati); table, cards, list, chart: righe da source organizzate da data; map: righe come segnaposti sulla mappa; dashboard: children affiancati; tabs: children come schede; page: content Markdown e sections; form: aggiunge o modifica un record di collection; booking: fasce orarie libere da prenotare; approvals: richieste di approvazione in sospeso; instances: gli agenti dell'utente creati da un template; account: saldo crediti, pacchetti e piani da acquistare, servizi collegati e movimenti di credito; admin: utenti, crediti ed esecuzioni recenti, per gli amministratori dell'app; review: non ancora visualizzata dal runtime (la pagina lo segnala). Valori: new_run, run, history, report, chat, review, table, cards, chart, dashboard, tabs, account, admin, page, list, approvals, instances, form, booking, map.
[].titletextTitolo della vista e sua etichetta nel menu (stringa semplice o una per lingua). Nel menu, una vista senza titolo mostra la propria chiave.
[].sourcestringDa dove provengono le righe. run (predefinito per table, cards, list, chart e map): le esecuzioni dell'utente autenticato, con i valori del modulo di input come campi; job:<key>: il dataset più recente di un job di dati in data.jobs, interrogato con campi, filtri, ordinamento e limite della vista (in cache per 60 secondi); collection:<name>[.<path>]: record di una raccolta dichiarata che l'utente può leggere (la parte .path imposta data.path); catalog[:<category>]: il catalogo pubblico delle fonti della piattaforma (in cache per 60 secondi); agent:<key>: per il tipo chat, l'agente che risponde (predefinito: l'agente con ruolo main). I nomi vengono verificati in validazione.
[].paramstringAccettato dallo schema; non ancora usato dal runtime.
[].querystringAccettato dallo schema; non ancora usato dal runtime. Usare data.filters per filtrare le righe.
[].columnslista di stringForma breve di data.fields: i campi della riga da mostrare come colonne, in ordine, con etichette e formati predefiniti. Ignorato quando data.fields è impostato.
[].childrenlista di keytype tabs, dashboard o admin: chiavi delle viste contenute, in ordine (ognuna deve esistere). Le viste figlie che l'utente non può aprire vengono escluse. Una dashboard le mostra affiancate, le schede una alla volta (?tab=<key>, predefinita la prima), una vista admin sotto le proprie tabelle (mai un'altra vista admin). L'annidamento è limitato: una vista dashboard o admin mostra le proprie viste figlie solo quando non è a sua volta dentro un'altra vista.
[].previewobjectAnteprima per gli utenti senza piano: con unlessPlan impostato, gli utenti che non hanno quel piano (amministratori esclusi) vedono solo le prime rows righe, una riga che indica quante altre righe sblocca il piano, nessun pulsante sulle righe e nessuna esportazione CSV.
[].preview.rowsintegerRighe mostrate agli utenti senza il piano. Predefinito 3; 0 le nasconde tutte. Valori: ≥ 0.
[].preview.hideColumnslista di stringAccettato dallo schema; non ancora usato dal runtime.
[].preview.unlessPlanstringChiave di un piano o pacchetto in billing; gli utenti i cui piani lo includono vedono tutte le righe. La validazione rifiuta una chiave che non sia un piano o un pacchetto. Senza di esso non c'è anteprima.
[].placementenum"page"Accettato dallo schema (page, predefinito, oppure floating, pensato come fumetto di chat su ogni pagina); non ancora usato dal runtime: ogni vista viene visualizzata come pagina. Valori: page, floating.
[].printablebooleantype report: mostra un pulsante Stampa nella pagina dell'esecuzione completata. Predefinito true.
[].roleslista di keyRuoli che possono aprire la vista (chiavi di auth.roles). Vuoto o assente: ogni utente autenticato. Un utente corrisponde con il proprio ruolo o con uno dei suoi ruoli aggiuntivi; gli amministratori dell'app non sono esenti, quindi elencare il ruolo admin nelle pagine usate dagli amministratori. I visitatori che non hanno effettuato l'accesso vedono una vista solo se auth.public è true, il method di auth è none o la vista è in auth.anonymous.views.
[].navbooleantrueIndica se la vista compare nel menu. Predefinito true. Il menu è mostrato agli utenti autenticati e non elenca mai le viste report o run né le viste che il loro ruolo non può aprire; una vista con nav: false resta raggiungibile tramite il suo URL.
[].contenttexttype page: Markdown mostrato prima delle sections (stringa semplice o una per lingua), visualizzato tramite il renderer Markdown sicuro.
[].sectionslista di sectiontype page: i blocchi della pagina, visualizzati dall'alto verso il basso dopo content. Vedi section.
[].exampleslista di texttype chat: domande di esempio mostrate come chip prima del primo messaggio (al massimo 8); facendo clic su una, la si invia. Valori: elementi max. 8.
[].placeholdertexttype chat: segnaposto della casella del messaggio. Predefinito: "Ask anything…" ("Scrivi la tua domanda…" in italiano).
[].dataobjecttype table, cards, list, chart (e map, per filtri, ordinamento e path): come vengono mostrate le righe provenienti da source: campi, filtri, raggruppamento, ordine, limite, numeri chiave, tipo di grafico e pulsanti di riga.
[].data.pathstringPercorso puntato (al massimo due livelli) verso un elenco all'interno di ogni riga; gli elenchi di tutte le righe vengono appiattiti nelle righe mostrate (ad esempio assets di ciascun segnale). Applicato prima dei filtri. Con una source della vista scritta come collection:<name>.<path>, il runtime lo ricava dalla sorgente quando non è impostato. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
[].data.displayenumCome vengono mostrate le righe. Predefinito: il tipo della vista (table, cards o list); una vista di tipo chart viene sempre mostrata come chart. table (visualizzazione predefinita): una colonna per campo; cards: una griglia, con il primo campo come titolo; list: una riga di testo per ogni riga, con il primo campo in grassetto; kpi: numeri chiave da kpis (mostrati anche senza righe); bar: barre orizzontali, primo campo = etichetta, secondo = valore; chart: un grafico SVG di tipo chart. Valori: table, cards, list, kpi, bar, chart.
[].data.fieldslista di objectLe colonne, in ordine (al massimo 12). Senza fields, il runtime mostra i primi 6 nomi di campo trovati nelle righe. Su una sorgente collection: (senza path) un campo senza label prende l'etichetta del campo della raccolta, e un campo select mostra l'etichetta dell'opzione al posto del valore salvato. Valori: elementi max. 12.
[].data.fields[].keystringsìCampo della riga da mostrare, come percorso puntato di al massimo due livelli (ad es. price o address.city). Per una sorgente job deve essere una colonna del dataset. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
[].data.fields[].labeltextIntestazione della colonna (stringa semplice o una per lingua). Predefinito: l'etichetta del campo della raccolta su una sorgente collection, altrimenti la chiave.
[].data.fields[].formatenumCome viene mostrato il valore. text (predefinito): così com'è; un valore in forma di posizione ("lat,lng") diventa un link a una mappa, un oggetto viene mostrato come JSON e, in una tabella, un testo più lungo di 220 caratteri mostra un estratto semplice con il testo completo al passaggio del mouse. number: numero localizzato, al massimo 2 decimali; money: importo nella billing.currency dell'app (predefinito EUR), senza decimali; percent: il valore è già una percentuale, mostrata con segno e colorata (+12.5%); ratio: una frazione moltiplicata per 100 e mostrata come percentuale (0.25 → +25%); date: giorno, mese abbreviato, anno; link: un URL https come link cliccabile abbreviato (gli altri valori come testo semplice); badge: un'etichetta a pillola; location: una posizione "lat,lng" come link a una mappa. Un valore vuoto mostra un trattino. Valori: text, number, money, percent, ratio, date, link, badge, location.
[].data.filterslista di objectCondizioni che ogni riga deve soddisfare (tutte, al massimo 8), applicate prima di raggruppamento, ordinamento e limite. Su una sorgente job: diventano la clausola WHERE della query sul dataset. Valori: elementi max. 8.
[].data.filters[].fieldstringsìCampo letto dalla condizione, come percorso puntato di al massimo due livelli. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
[].data.filters[].openumsìConfronto. = e != confrontano come testo; >, >=, <, <= confrontano come numeri e scartano le righe il cui valore non è un numero; contains: corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole. Valori: =, !=, >, >=, <, <=, contains.
[].data.filters[].valuestring | number | booleansìValore confrontato con il campo: testo, numero o booleano.
[].data.sortobjectOrdine delle righe, applicato dopo filtri e raggruppamento e prima del limite. Senza di esso le righe mantengono l'ordine della sorgente (una sorgente run mostra prima le più recenti; le righe raggruppate sono ordinate per valore del gruppo, in ordine crescente).
[].data.sort.fieldstringsìCampo in base a cui ordinare (percorso puntato di al massimo due livelli). I numeri sono confrontati come numeri, tutto il resto come testo. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
[].data.sort.direnumdesc (predefinito) o asc. Valori: asc, desc.
[].data.limitintegerNumero massimo di righe (o gruppi) mostrati, 1–200. Predefinito 50. I numeri chiave (kpis) sono calcolati solo su queste righe. Valori: ≥ 1; ≤ 200.
[].data.kpislista di objectdisplay kpi: i numeri chiave, al massimo 6, ciascuno un aggregato sulle righe. Senza kpis viene mostrato un solo numero: il conteggio delle righe. Valori: elementi max. 6.
[].data.kpis[].labeltextsìTesto sotto il numero (stringa semplice o una per lingua).
[].data.kpis[].aggenumsìL'aggregato: count (righe, nessun campo necessario), sum, avg, min, max (sui valori numerici del campo; i non numerici sono ignorati, vuoto se non ce ne sono), last (il valore del campo nella prima riga non vuota nell'ordine corrente). Valori: count, sum, avg, min, max, last.
[].data.kpis[].fieldstringCampo letto dall'aggregato (percorso puntato di al massimo due livelli). Non necessario per count. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
[].data.kpis[].formatenumCome viene mostrato l'aggregato: number, money (valuta dell'app, predefinito EUR), percent, ratio (×100 come percentuale), date, link, badge o text. Predefinito: number per count, valore semplice per gli altri aggregati. Valori: text, number, money, percent, ratio, date, link, badge.
[].data.emptytextMessaggio mostrato quando non ci sono righe (non per display kpi). Predefinito: "No data yet." ("Ancora nessun dato." in italiano).
[].data.chartenumdisplay chart: il tipo di grafico. bar (predefinito): barre raggruppate; line: linee con punti; pie: una fetta per riga, solo dalla prima serie (i valori negativi contano come 0); stacked: barre sovrapposte (valori negativi ignorati). Il primo campo fornisce le etichette, ogni altro campo una serie. Valori: bar, line, pie, stacked.
[].data.groupByobjectRaggruppa le righe (dopo i filtri): una riga per ogni valore di field (date raggruppate per giorno, settimana o mese) con una colonna count e una colonna per ogni aggregato in aggs; i gruppi sono ordinati per valore, in ordine crescente, poi si applicano sort e limit. Usare il campo del gruppo, count e le chiavi degli aggregati come fields. minCount nasconde i gruppi piccoli; acrossUsers su una raccolta di record degli utenti aggrega in forma anonima i record di tutti gli utenti (richiede minCount ≥ 5; nessun record viene mai mostrato).
[].data.groupBy.fieldstringsìCampo il cui valore forma il gruppo (percorso puntato). Le righe senza valore vanno in un gruppo chiamato "—".
[].data.groupBy.bucketenumTratta il campo come una data e raggruppa per day (YYYY-MM-DD), week (la data del lunedì di quella settimana) o month (YYYY-MM), in UTC. Le righe il cui valore non è una data vanno in "—". Senza bucket, ogni valore distinto è un gruppo. Valori: day, week, month.
[].data.groupBy.aggslista di objectsìLe colonne aggregate di ogni gruppo (al massimo 8). count viene sempre aggiunto. Valori: elementi max. 8.
[].data.groupBy.aggs[].keystringsìNome della colonna in cui viene scritto l'aggregato; richiamarlo in fields, sort e kpis. Valori: formato ^[A-Za-z_][A-Za-z0-9_]*$.
[].data.groupBy.aggs[].aggenumsìL'aggregato sulle righe del gruppo: count (righe, nessun campo necessario), sum, avg, min, max (sui valori numerici del campo; i non numerici sono ignorati, vuoto se non ce ne sono), last (il valore del campo nella prima riga non vuota nell'ordine corrente). Valori: count, sum, avg, min, max, last.
[].data.groupBy.aggs[].fieldstringCampo letto dall'aggregato (percorso puntato). Non necessario per count.
[].data.groupBy.minCountintegerI gruppi con meno righe di questo valore vengono esclusi (1–1000, predefinito 1). Deve essere almeno 5 con acrossUsers. Valori: ≥ 1; ≤ 1000.
[].data.groupBy.acrossUsersbooleanSu una sorgente collection: la cui raccolta è ownedBy: user: aggrega i record di tutti gli utenti, non solo di chi guarda, e mostra solo i gruppi (un benchmark anonimo). La validazione lo rifiuta su altre sorgenti e con minCount inferiore a 5; il runtime legge i record di tutti gli utenti solo quando minCount è almeno 5.
[].data.actionslista di recordActionPulsanti su ogni riga (al massimo 4): chiamata, indicazioni stradali, condivisione, aggiunta al calendario. Non mostrati sulle righe di un'anteprima bloccata. share e calendar aggiungono il permesso corrispondente all'app per telefono. Valori: elementi max. 4.
[].approvalslista di stringtype approvals: chiavi delle approvazioni (spec.approvals) elencate dalla vista. Predefinito: tutte. Ogni utente vede solo le richieste in sospeso su cui può decidere, più le 20 decise più di recente. Le chiavi sconosciute vengono rifiutate in validazione.
[].templatestringtype instances: chiave del template (spec.templates) di cui l'utente crea, esegue e mette in pausa le istanze, vedendone l'ultimo risultato. Un utente può avere al massimo maxPerUser istanze del template (predefinito 5). Obbligatorio per questo tipo: una chiave sconosciuta viene rifiutata in validazione.
[].collectionstringtype form: la raccolta dichiarata in cui scrive il modulo. I visitatori senza accesso possono inviare un modulo solo se è in auth.anonymous.views e la raccolta è ownedBy: org (al massimo 5 invii all'ora per indirizzo); una raccolta ownedBy: app o shared accetta nuovi record solo dagli amministratori; una raccolta ownedBy: instance viene rifiutata. type booking: la raccolta delle prenotazioni, che deve essere ownedBy: user; ogni record di prenotazione riceve start, end (ISO, UTC), date, resource (quando ci sono risorse), status (booked o cancelled), userId e bookedBy.
[].fieldslista di stringtype form: nomi dei campi della raccolta da mostrare, in ordine (predefinito: tutti). type booking: i campi aggiuntivi della raccolta richiesti al momento della prenotazione (ad es. note, telefono); vengono conservati solo valori di testo, numerici e booleani, con il testo troncato a 2000 caratteri. Ogni nome deve essere un campo della raccolta.
[].editbooleanfalsetype form: permette a /v/<key>?id=<record> di modificare un record esistente su cui l'utente può scrivere (record proprio o regola di accesso con write). Predefinito false: il modulo crea soltanto record.
[].submitobjecttype form: il pulsante, il messaggio dopo il salvataggio e la pagina da aprire in seguito.
[].submit.labeltextTesto del pulsante di invio. Predefinito: "Send" per un nuovo record, "Save" in modifica (in italiano: "Invia", "Salva").
[].submit.messagetextMessaggio mostrato dopo il salvataggio. Predefinito: "Saved — thank you." ("Salvato, grazie." in italiano). Non mostrato quando redirect è impostato.
[].submit.redirectstringChiave di una vista da aprire dopo il salvataggio (/v/<key>). Deve essere una vista di questa app.
[].exportbooleanfalsetype table, list o cards: aggiunge un link "Download CSV" con le righe che l'utente vede (stessa sorgente, regole di accesso e filtri; al massimo 200 righe, indipendentemente da data.limit). Il CSV è UTF-8 con BOM; le celle che un foglio di calcolo eseguirebbe come formula vengono neutralizzate. Nessun link quando non ci sono righe o le righe sono bloccate da preview. Predefinito false.
[].resourcesstringtype booking: che cosa si prenota (professionisti, sale, tavoli), come collection:<name> di una raccolta che tutti leggono (ownedBy: app o shared). L'utente sceglie prima una risorsa; ogni risorsa ha le proprie fasce orarie, e l'oggetto slots di un record di risorsa sostituisce la regola della vista. I record con active: false sono esclusi; ne vengono elencati al massimo 100.
[].slotsobjecttype booking: la regola di apertura. Le fasce libere sono calcolate per i prossimi aheadDays, escluse quelle già prenotate fino a capacity. Il campo slots di un record di risorsa sostituisce una qualsiasi di queste chiavi per quella risorsa.
[].slots.dayslista di integerGiorni della settimana aperti alle prenotazioni: 1 = lunedì … 7 = domenica. Predefinito da lunedì a venerdì (1–5).
[].slots.fromstring"09:00"Orario di apertura, HH:MM in tz. Predefinito 09:00. Deve precedere to. Valori: formato ^\d{2}:\d{2}$.
[].slots.tostring"18:00"Orario di chiusura, HH:MM in tz. Predefinito 18:00. L'ultima fascia termina entro questo orario. Valori: formato ^\d{2}:\d{2}$.
[].slots.minutesinteger30Durata di ogni fascia in minuti, 5–480. Predefinito 30. Le fasce iniziano a from e si susseguono senza interruzioni. Valori: ≥ 5; ≤ 480.
[].slots.tzstring"Europe/Rome"Fuso orario IANA degli orari di apertura (ad es. Europe/London). Predefinito Europe/Rome.
[].slots.aheadDaysinteger14Per quanti giorni in avanti, a partire da oggi, vengono offerte le fasce (1–120). Predefinito 14. Valori: ≥ 1; ≤ 120.
[].slots.minNoticeHoursnumber2Ore minime tra il momento attuale e l'inizio di una fascia perché sia prenotabile (decimali ammessi). Predefinito 2. Valori: ≥ 0.
[].slots.capacityinteger1Prenotazioni ammesse per la stessa fascia (e risorsa), ad es. posti in una lezione (1–100). Predefinito 1. Valori: ≥ 1; ≤ 100.
[].mapobjecttype map: segnaposti ricavati dalle righe della sorgente della vista, letti con le stesse regole di accesso di una tabella (al massimo 200 righe; le righe senza coordinate valide vengono saltate). Filtri, ordinamento e path provengono da data.
[].map.latstring"lat"Campo con la latitudine (un numero, o testo con decimale a punto o virgola). Predefinito lat.
[].map.lonstring"lon"Campo con la longitudine. Predefinito lon.
[].map.titlestring"name"Campo mostrato in grassetto nel popup di ciascun segnaposto. Predefinito name.
[].map.popuplista di stringCampi i cui valori sono mostrati sotto il titolo nel popup, uno per riga (al massimo 6; i valori vuoti sono esclusi). Valori: elementi max. 6.
[].map.tilesstringTemplate dell'URL delle tile, https con un segnaposto {z} (ad es. https://…/{z}/{x}/{y}.png). Predefinito OpenStreetMap, pensato solo per un uso leggero: un'app molto utilizzata dovrebbe usare un proprio fornitore di tile. Valori: formato ^https://\S+\{z\}\S*$.
[].map.attributionstringAttribuzione mostrata sulla mappa (al massimo 200 caratteri). Predefinito "© OpenStreetMap contributors"; impostarla quando si usano altre tile. Valori: lunghezza max. 200.

spec.schedules

lista di object. Timer dell'app. Le pianificazioni con owner app vengono eseguite nel ciclo (tick) dello scheduler del runtime; ognuna scatta al massimo una volta per tick e, dopo un'interruzione, il tick recupera al massimo le ultime 3 ore.

ProprietàTipoObbl.PredefinitoDescrizione
[].agentstringChiave dell'agente da avviare (con azione run o digest). Il suo goal è goal, altrimenti il goalTemplate dell'agente, altrimenti Run your scheduled task for {date}.; si applicano le sue startOptions. Al termine, la risposta diventa un record della raccolta writesTo dell'agente e viene inviata per email se deliver è impostato. Le esecuzioni non terminate dopo 6 ore vengono segnate come fallite.
[].jobstringChiave di un job di dati in spec.data.jobs da eseguire (con azione run o ingest). Il job deve essere collegato (pubblicato); altrimenti il tick registra not linked. Usato solo quando agent non è impostato.
[].actionenum"run"Che cosa fa la pianificazione. run (predefinito): avvia l'agent, oppure il job. digest: come run per un agente. ingest: come run per un job. settle: controlla fino a 50 esecuzioni da modulo in corso o non ancora regolate e ne regola i crediti. sync: non ancora eseguito dal runtime. Valori: run, sync, settle, ingest, digest.
[].cronstringsìQuando scatta: un cron standard a 5 campi (minuto ora giorno-del-mese mese giorno-della-settimana) in UTC, con *, elenchi, intervalli e passi; la domenica è 0 o 7.
[].ownerenum"app"app (predefinito): la esegue lo scheduler del runtime. platform: un trigger della piattaforma (agente pianificato o cron di un job); il runtime la salta. Valori: platform, app.
[].goalstringIl compito dell'agente a ogni esecuzione. Segnaposto: {date} (UTC, YYYY-MM-DD), {lang} (la lingua predefinita dell'app), {role} (scheduler); {user} è vuoto. Predefinito: il goalTemplate dell'agente, altrimenti Run your scheduled task for {date}.
[].deliverdeliverInvia per email il report di ogni esecuzione completata. Una pianificazione richiede un agent e un to esplicito (admins o role:<key>): una pianificazione a livello di app non ha un proprietario.

spec.billing

object. Come pagano gli utenti finali. Pacchetti e piani sono pagati tramite Stripe Checkout sull'account collegato del proprietario dell'app, e la piattaforma trattiene una commissione; i crediti vengono spesi per esecuzioni e messaggi in chat. L'uso della piattaforma (LLM, calcolo) viene misurato e addebitato separatamente all'organizzazione del proprietario. Gli amministratori non pagano mai.

ProprietàTipoObbl.PredefinitoDescrizione
modeslista di enumsìI modi in cui pagano gli utenti (almeno uno, senza ripetizioni). La validazione impone: free non può essere combinato con altre modalità; credits richiede pacchetti, piani con crediti o signupCredits; subscription richiede piani. Il runtime addebita quanto indicato in costs qualunque sia la modalità; per_transaction è accettato ma i pagamenti tra utenti non sono ancora disponibili. Valori: elementi min. 1; free, credits, subscription, per_transaction.
currencystring"eur"Valuta dei prezzi di pacchetti e piani, come codice ISO (predefinito eur). Usata per Stripe Checkout e per formattare prezzi e importi nelle pagine.
platformFeePctnumberPensato come percentuale di commissione della piattaforma. Non usato dal runtime: la commissione sui pagamenti è stabilita dalla piattaforma (10% salvo diversa configurazione), mai dal manifest. Valori: ≥ 0; ≤ 100.
signupCreditsintegerCrediti che un nuovo utente riceve una sola volta, al primo accesso. Valori: ≥ 0.
meteringobjectImpostazioni per i costi contrassegnati metered: i crediti vengono trattenuti sulla stima all'avvio di un'esecuzione da modulo e regolati sull'uso misurato al termine (rimborsati per intero se l'esecuzione non produce un report). Se la piattaforma non ha registrato token, viene addebitata la stima.
metering.creditEurnumberValore di un credito in euro (predefinito 0.01). Crediti addebitati = prezzo in euro diviso per questo valore, arrotondato per eccesso.
metering.markupPctnumberPercentuale aggiunta al costo misurato per ottenere il prezzo (predefinito 50). Valori: ≥ 0.
metering.driverslista di enumQuali costi misurati vengono prezzati (predefinito llm_tokens e compute). llm_tokens: i token dell'esecuzione alla tariffa del modello; compute o vm: ore-VM intere della durata dell'esecuzione (almeno una). browser, proxy e storage sono accettati ma non ancora prezzati dal runtime. Valori: llm_tokens, compute, browser, proxy, storage, vm.
metering.allowNegativebooleanQuando il prezzo misurato supera la stima trattenuta e il saldo dell'utente non copre la differenza: con true la si preleva comunque e il saldo va sotto zero; altrimenti (predefinito) il runtime preleva quanto disponibile nel saldo e registra il resto come non pagato.
costsmappa di number | objectQuanto costano le azioni, in crediti, per chiave. agent:<key> stabilisce il prezzo di un'esecuzione da modulo di quell'agente e di ogni messaggio in chat a esso; run è il prezzo di riserva di qualsiasi esecuzione da modulo il cui agente non ha una voce. Le altre chiavi sono accettate ma non addebitate. I crediti vengono trattenuti all'avvio dell'esecuzione (un'esecuzione fallisce con 402 se il saldo è insufficiente) e restituiti se non produce un report; gli amministratori eseguono gratis.
packslista di objectAcquisti una tantum che aggiungono crediti. Sono elencati con un pulsante Acquista nella vista account; il pagamento avviene tramite Stripe Checkout e i crediti vengono aggiunti una volta, al completamento del pagamento. Un acquisto completato attiva anche i trigger con on.payment impostato sulla chiave del pacchetto (o *).
packs[].keykeysìIdentificatore del pacchetto (lettere minuscole, cifre, _ e -), usato dal checkout e dai trigger on.payment. La validazione lo accetta anche dove è prevista una chiave di piano, ma l'acquisto di un pacchetto non assegna all'utente quella chiave come piano.
packs[].creditsintegerCrediti aggiunti al saldo dell'acquirente al completamento del pagamento (nessuno se 0 o assente). Valori: ≥ 0.
packs[].pricenumbersìPrezzo in unità di billing.currency (ad es. 9.9 = 9,90 EUR), addebitato una sola volta. Valori: ≥ 0.
packs[].labeltextNome del pacchetto mostrato nella vista account e in Checkout (predefinito: key).
packs[].unlockslista di stringValori di opzione o viste che un pacchetto dovrebbe sbloccare. Accettato dallo schema; non ancora usato dal runtime.
planslista di objectAbbonamenti. Sono elencati con un pulsante Abbonati nella vista account; finché un abbonamento è attivo, l'utente possiede la chiave del piano, che sblocca ciò che indicano gatedBy, requiresPlan, preview.unlessPlan e i limiti per piano. La chiave viene rimossa quando l'abbonamento termina.
plans[].keykeysìIdentificatore del piano (lettere minuscole, cifre, _ e -), salvato sull'utente abbonato e richiamato da gatedBy, requiresPlan, unlessPlan, dai plans dei limiti e dai trigger on.payment.
plans[].pricenumbersìPrezzo per interval in unità di billing.currency. Valori: ≥ 0.
plans[].intervalenumsìCon quale frequenza viene fatturato l'abbonamento: month o year. Valori: month, year.
plans[].labeltextNome del piano mostrato nella vista account e in Checkout (predefinito: key).
plans[].includeslista di stringChe cosa include il piano. Accettato dallo schema; non ancora usato dal runtime (non mostrato nella vista account).
plans[].creditsintegerCrediti aggiunti al saldo dell'abbonato a ogni fattura pagata (ogni periodo di fatturazione). I crediti non spesi vengono conservati. Valori: ≥ 0.
plans[].creditsResetenummonthly: i crediti del piano intesi come franchigia spesa prima dei pacchetti acquistati; never: si accumulano. Accettato dallo schema; non ancora usato dal runtime: ogni fattura pagata aggiunge i crediti allo stesso saldo. Valori: monthly, never.
plans[].transactionFeePctnumberper_transaction: la commissione sui pagamenti tra utenti per gli abbonati a questo piano. Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0; ≤ 100.
plans[].roleslista di keyRuoli a cui dovrebbe essere consentito acquistare il piano. Accettato dallo schema; non ancora usato dal runtime: ogni utente autenticato può abbonarsi.
transactionFeePctnumberper_transaction: la commissione del proprietario su ogni pagamento tra utenti (il valore predefinito quando un piano non ne imposta una). Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0; ≤ 100.
sellersstringper_transaction: collection:<name> i cui record verrebbero pagati tramite i propri account collegati. La validazione verifica che la raccolta sia dichiarata; non ancora usato dal runtime.
revenueSharelista di objectPagamenti a terzi. Accettato dallo schema; non ancora usato dal runtime (la validazione verifica che to indichi una raccolta dichiarata).
revenueShare[].tostringsìcollection:<name>: i record che verrebbero pagati. La validazione verifica che la raccolta sia dichiarata; non ancora usato dal runtime.
revenueShare[].pctnumbersìPercentuale (da 0 a 100) di basis che verrebbe pagata. Non ancora usato dal runtime. Valori: ≥ 0; ≤ 100.
revenueShare[].basisstringsìA che cosa si applicherebbe la percentuale, a parole (ad es. crediti pagati il cui contenuto è stato usato dall'agente). Non ancora usato dal runtime.
revenueShare[].payoutenum"manual"Come verrebbero pagati i beneficiari: manual (predefinito) dal proprietario, connect tramite i loro account Stripe collegati. Non ancora usato dal runtime. Valori: manual, connect.

spec.notifications

object. Email sulle esecuzioni. emailOnRunDone: invia un'email agli utenti al termine della loro esecuzione da modulo. Per i report periodici usare schedules[].deliver o templates[].deliver.

ProprietàTipoObbl.PredefinitoDescrizione
emailOnRunDonebooleanInvia un'email all'utente al termine della sua esecuzione da modulo: titolo e link del report (/r/<run id>), oppure un avviso che la richiesta non è stata completata e che non sono stati addebitati crediti. Lo stesso messaggio arriva sul telefono quando l'app ha le notifiche push. Con questa opzione attiva, il tick dello scheduler controlla anche fino a 50 esecuzioni in corso ogni volta, così l'email parte anche quando nessuno sta guardando la pagina.
digeststringCron di un riepilogo email periodico. Accettato dallo schema; non ancora usato dal runtime: usare schedules[].deliver o templates[].deliver.

spec.exports

lista di object. Endpoint che l'app servirebbe ad altri programmi. Accettato dallo schema; non ancora usato dal runtime. Per consentire agli utenti di scaricare dati, impostare export: true su una vista table, list o cards: serve in CSV le righe che quell'utente può vedere.

ProprietàTipoObbl.PredefinitoDescrizione
[].pathstringsìPercorso URL dell'endpoint, che inizia con /api/. Non ancora usato dal runtime. Valori: formato ^/api/.
[].sourcestringsìDati che l'endpoint servirebbe. Non ancora usato dal runtime.
[].formatenum"json"Formato di output: json (predefinito), csv, xml o rss. Non ancora usato dal runtime. Valori: json, csv, xml, rss.
[].accessenum"user"Chi potrebbe chiamarlo: user (predefinito), public, signed_url o token. Non ancora usato dal runtime. Valori: public, signed_url, token, user.

spec.mobile

object. L'app per telefono: un unico guscio Capacitor, generato dal manifest, che apre l'indirizzo web di questa app (host, altrimenti <slug>.webrobot.eu), così schermate, agenti e dati sono gli stessi del web e passano per la sessione della persona. Vengono installate solo le funzionalità del telefono elencate qui. Viene esportata come progetto con workflow di build per Android e iOS; l'accesso dal telefono usa il codice di 6 cifre ricevuto per email.

ProprietàTipoObbl.PredefinitoDescrizione
appIdstringsìIdentificatore per gli store in forma DNS inversa, in minuscolo, con almeno tre parti, ad es. com.example.myapp. Diventa il nome del pacchetto Android e il bundle id iOS, e non può cambiare una volta che l'app è in uno store. Valori: formato ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,}$.
appNamestringNome sotto l'icona sul telefono (al massimo 30 caratteri). Predefinito: displayName. Valori: lunghezza max. 30.
versionstringVersione mostrata negli store, x.y.z. Predefinito 1.0.0. Valori: formato ^\d+\.\d+\.\d+$.
buildintegerNumero di build (almeno 1), predefinito 1. I workflow di build vi aggiungono il numero dell'esecuzione CI, così ogni caricamento sugli store ne ha uno più alto. Valori: ≥ 1.
orientationenum"portrait"Orientamento dello schermo: portrait (predefinito) blocca l'app in verticale; any segue la rotazione del telefono. Valori: portrait, any.
capabilitieslista di objectFunzionalità del telefono usate dall'app (al massimo 15, ciascuna una sola volta). Nel guscio entrano solo i relativi plugin e permessi. Ciascuna deve essere usata da qualcosa nell'app (ad es. location da un campo posizione, barcode da un campo codice a barre, camera da un campo file con acquisizione, biometrics da lock), eccetto files, haptics e share; a loro volta un campo posizione, codice a barre o foto, un'azione di condivisione o calendario e lock richiedono ciascuno la dichiarazione della propria funzionalità. Questi controlli vengono eseguiti quando l'app viene progettata e quando l'app per telefono viene esportata. contacts, bluetooth, backgroundLocation, localNotifications e speech non possono ancora essere usati da nessuna parte di un'app. Valori: elementi max. 15.
capabilities[].nameenumsìLa funzionalità: camera, location, backgroundLocation (richiede anche location), push, localNotifications, biometrics, contacts, calendar, microphone, speech, bluetooth, barcode (alza la versione minima di Android a 8), files, share, haptics. Valori: camera, location, backgroundLocation, push, localNotifications, biometrics, contacts, calendar, microphone, speech, bluetooth, barcode, files, share, haptics.
capabilities[].reasontextPerché l'app ha bisogno della funzionalità; il telefono lo mostra quando chiede il permesso (su iOS diventa la usage description). Obbligatorio per camera, location, backgroundLocation, biometrics, contacts, calendar, microphone, speech, bluetooth e barcode; scritto in defaultLang.
allowNavigationlista di stringAltri host che il guscio può aprire all'interno dell'app invece che nel browser. L'host dell'app stessa e Stripe Checkout sono sempre consentiti.
lock"biometric"biometric: quando qualcuno ha effettuato l'accesso, l'app per telefono si apre (e torna dal background) solo dopo Face ID, impronta digitale o il codice del telefono. Richiede la funzionalità biometrics. Senza biometria configurata sul telefono, non c'è alcun blocco.

spec.extensions

lista di object. Documenta logica personalizzata che il manifest non può ancora esprimere. Solo informativo: il runtime non serve nulla da qui, e gli strumenti dell'app contrassegnati con un extension non vengono serviti.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìIdentificatore dell'estensione.
[].descriptionstringsìChe cosa fa la logica personalizzata.
[].wherestringDove si trova il codice dell'app costruita a mano che contiene questa logica. Solo informativo.

spec.header

object. La barra superiore per i visitatori: link alle sezioni della home page, un pulsante di invito all'azione e una striscia di annuncio.

ProprietàTipoObbl.PredefinitoDescrizione
linkslista di objectLink nell'intestazione (al massimo 8). Mostrati ai visitatori che non hanno effettuato l'accesso e agli utenti autenticati che non hanno pagine nel menu; altrimenti l'intestazione mostra le pagine dell'app. Valori: elementi max. 8.
links[].labeltextsìTesto del link.
links[].hrefstringsìDestinazione: un percorso di questa app (/…), un'ancora nella pagina (#…) o un URL https://. Valori: formato ^(/(?!/)|#|https://).
ctaobjectPulsante di invito all'azione mostrato ai visitatori che non hanno effettuato l'accesso, al posto del pulsante di accesso.
cta.labeltextsìTesto del pulsante.
cta.hrefstringsìDestinazione: un percorso di questa app (/…, ad es. /login), un'ancora (#…) o un URL https://. Valori: formato ^(/(?!/)|#|https://).
announcementtextUna riga mostrata sopra l'intestazione su ogni pagina, a tutti. Markdown; link ammessi.

spec.slots

lista di object. Funzioni Python proprie dell'app (al massimo 20), eseguite in una sandbox (WebAssembly, senza rete, senza file, senza variabili d'ambiente, 128 MB di memoria). Una voce di contesto dell'agente from: slot:<key> ne esegue una all'avvio di un'esecuzione da modulo, e uno strumento dell'app con azione call ne esegue una quando l'agente lo chiama. Valori: elementi max. 20.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca dello slot, richiamata da context[].from: slot:<key> e appTools[].slot.
[].descriptionstringChe cosa calcola lo slot, al massimo 300 caratteri. Per chi legge il manifest; il runtime non lo usa. Valori: lunghezza max. 300.
[].codestringsìSorgente Python 3.12, al massimo 64.000 caratteri. Definire main(input) che restituisce dati serializzabili in JSON, oppure stampare un singolo valore JSON; al massimo 256 KB di output. Input: {values, lang} quando viene eseguito per il contesto di un agente, {args, userId} quando viene eseguito come strumento. Uno slot che fallisce interrompe l'esecuzione da modulo prima che venga trattenuto qualsiasi credito. Valori: lunghezza max. 64000.
[].timeoutMsinteger3000Limite di tempo reale di una chiamata, in millisecondi: da 100 a 10.000, predefinito 3000. Valori: ≥ 100; ≤ 10000.
[].exampleUn input di esempio, usato dal test degli slot di App Studio. Il runtime non lo usa.

spec.serviceHours

object. Quando l'agente dell'app deve rispondere velocemente. In queste ore l'host di chat dedicato dell'organizzazione resta acceso e i messaggi in chat ricevono risposta lì, nella stessa richiesta; al di fuori di esse, o quando l'host non è pronto, ogni messaggio in chat è un'esecuzione dell'agente. Il tick dello scheduler accende l'host leadMinutes prima dell'apertura e lo spegne dopo la chiusura.

ProprietàTipoObbl.PredefinitoDescrizione
timezonestringFuso orario IANA delle fasce, ad es. Europe/Rome. Predefinito: metadata.timezone, altrimenti Europe/Rome.
leadMinutesinteger10Minuti prima di ogni apertura in cui viene avviato l'host, così che sia pronto in tempo: da 0 a 60, predefinito 10. Valori: ≥ 0; ≤ 60.
slotslista di objectsìPeriodi di apertura, da 1 a 14. L'app è in servizio quando una qualsiasi fascia copre l'ora locale corrente. Valori: elementi min. 1; elementi max. 14.
slots[].dayslista di integersìGiorni della settimana a cui si applica la fascia: 1 = lunedì … 7 = domenica. Per una fascia che supera la mezzanotte, il giorno è quello in cui inizia. Valori: elementi min. 1.
slots[].fromstringsìOrario di apertura, HH:MM (24 ore, locale), incluso. Valori: formato ^([01][0-9]|2[0-3]):[0-5][0-9]$.
slots[].tostringsìOrario di chiusura, HH:MM (24 ore, locale), escluso. Un orario precedente a from indica che la fascia termina il giorno dopo. Valori: formato ^([01][0-9]|2[0-3]):[0-5][0-9]$.

spec.teams

lista di object. Agenti che lavorano insieme, pubblicati come UN SOLO profilo agentico chiamato <slug>-team-<key>: sequence esegue passaggi i cui output confluiscono nel successivo (un DAG); swarm è un capo con dei membri su una bacheca di attività condivisa. Un team viene avviato da un trigger (start.team) o da un template (team).

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca del team, richiamata da triggers[].start.team e templates[].team. Non può coincidere con la chiave di un agente.
[].descriptionstringChe cosa fa il team. La pubblicazione la usa come descrizione del profilo (predefinito <displayName> — team <key>).
[].titletextTitolo visualizzato del team. Accettato dallo schema; non ancora usato dal runtime.
[].modeenumsìsequence: gli steps vengono eseguiti in ordine (o dopo i passaggi indicati in after) e devono formare un DAG. swarm: il lead pianifica e chiude il lavoro, i members lavorano su una bacheca condivisa. Valori: sequence, swarm.
[].stepslista di objectmode sequence: i passaggi, almeno uno. Ogni passaggio viene eseguito dopo il precedente, o dopo i passaggi elencati nel suo after. Un agente può comparire una sola volta, e i cicli vengono rifiutati.
[].steps[].agentstringsìChiave dell'agente che esegue questo passaggio (deve essere inline).
[].steps[].afterlista di stringI passaggi (chiavi di agente) che questo attende. Predefinito: il passaggio precedente; il primo passaggio non ne ha.
[].leadstringmode swarm: l'agente che pianifica e chiude il lavoro (obbligatorio per uno swarm).
[].memberslista di stringmode swarm: gli agenti sulla bacheca (almeno uno).
[].maxMinutesintegerLimite di tempo di uno swarm, in minuti (1–180), passato allo swarm come durata massima. Ignorato per i team sequence. Valori: ≥ 1; ≤ 180.
[].goalTemplatestringIl compito del team per un'istanza di template quando il template non ha goal; stessi segnaposto del goal del template. Un trigger che avvia il team usa il goal del trigger (o un valore predefinito), non questo.
[].writesToobjectCome per un agente: il risultato di ogni esecuzione del team da trigger o da istanza di template diventa un record di collection (con parse e keyBy).
[].profileobjectImpostato dalla pubblicazione: il profilo compilato dal team. Non scriverlo a mano.
[].profile.refinteger | stringId del profilo pubblicato del team; il runtime avvia il team tramite esso. Un team senza questo valore risulta not published.

spec.triggers

lista di object. Eventi che fanno qualcosa senza l'intervento di una persona: avviare un agente, un team o un job di dati, inviare un'email, salvare un record o addebitare crediti. Un'app non può avviare più di 20 azioni da trigger al minuto (quelle in eccesso vengono saltate), e spec.limits con azione agents o agent:<key> limita gli agenti avviati dai suoi eventi.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca del trigger. Un trigger webhook viene chiamato su POST /api/hooks/<key>.
[].descriptionstringA che cosa serve il trigger. Per chi legge il manifest; il runtime non lo usa.
[].onobjectsìLa sorgente dell'evento: esattamente uno tra cron, collection, webhook, payment, approval, call, date. op e where affinano collection (where anche call e date), decision affina approval, callEvent affina call.
[].on.cronstringUn cron a 5 campi in UTC, verificato dal tick dello scheduler (al massimo una volta per tick, recuperando al massimo 3 ore). Un trigger a tempo non ha utente né record: vengono eseguiti solo start e notify, e il goal è goal oppure Run your scheduled task for {date}. (il goalTemplate dell'agente non viene usato).
[].on.collectionstringUna raccolta dichiarata: scatta quando uno dei suoi record viene scritto da un modulo, una prenotazione, la pagina dati degli amministratori, uno strumento dell'app, il writesTo di un agente o il write di un altro trigger.
[].on.openum"insert"Quali scritture di collection lo attivano: insert (predefinito) per un nuovo record, update per una modifica a uno esistente, any per entrambe. Valori: insert, update, any.
[].on.whereobjectCampi che il record deve avere, confrontati come testo per uguaglianza, ad es. {status: confirmed}. Si applica agli eventi collection, date e call. Un record creato senza il campo riceve prima il valore predefinito del campo della raccolta, quindi un where su un valore predefinito corrisponde.
[].on.webhookbooleantrue: il trigger viene chiamato su POST /api/hooks/<key> con l'header X-Hook-Secret (il segreto degli hook dell'app). Facoltativamente il mittente firma con X-Hook-Timestamp (secondi unix, entro 5 minuti) e X-Hook-Signature (HMAC-SHA256 esadecimale di <timestamp>.<body>). Il corpo (al massimo 64.000 caratteri, JSON o testo) è l'evento; la risposta è 202.
[].on.paymentstringUna chiave di piano o di pacchetto, o * per qualsiasi acquisto: scatta una volta per ogni acquisto completato, per l'utente che ha pagato.
[].on.approvalstringChiave di un'approvazione: scatta quando una richiesta di quell'approvazione viene decisa (da una persona o alla scadenza). Il record contiene i campi della richiesta più approvalId, summary e note.
[].on.decisionenum"any"Quali decisioni lo attivano: approved, rejected o any (predefinito). Una richiesta scaduta viene consegnata come approved o rejected secondo l'onTimeout dell'approvazione, quindi oggi timeout non corrisponde mai. Valori: approved, rejected, timeout, any.
[].on.callstringChiave di un canale telefonico (o phone quando il canale non ha chiave): i momenti della chiamata, con chiamante, trascrizione, durata ed esito nel record. Validato rispetto a spec.channels; il runtime non riceve ancora chiamate, quindi oggi non scatta.
[].on.callEventenum"ended"Quale momento di una chiamata lo attiva: started, ended (predefinito) o missed. Solo con call. Valori: started, ended, missed.
[].on.dateobjectPromemoria: scatta per ogni record di collection la cui data in field, spostata di offsetDays, è oggi (UTC). Verificato dal tick dello scheduler a partire da hour, una volta per record e data, al massimo 200 record per tick; where filtra i record.
[].on.date.collectionstringsìLa raccolta dichiarata i cui record vengono verificati.
[].on.date.fieldstringsìUn campo data (YYYY-MM-DD, letto come mezzanotte UTC) o data-ora del record. I record con valore vuoto o non valido vengono saltati.
[].on.date.offsetDaysinteger0Giorni aggiunti alla data prima del confronto con oggi: -1 = il giorno prima della data, 3 = tre giorni dopo. Da -365 a 365, predefinito 0. Valori: ≥ -365; ≤ 365.
[].on.date.hourinteger7Ora del giorno (UTC, 0–23) a partire dalla quale vengono inviati i promemoria del giorno; predefinito 7. Valori: ≥ 0; ≤ 23.
[].startobjectAvvia esattamente uno tra un agente, un team o un job di dati. Le esecuzioni di agenti e team vengono registrate e raccolte dal tick dello scheduler; il loro risultato va nella raccolta writesTo dell'agente o del team.
[].start.agentstringChiave dell'agente da avviare (deve essere pubblicato). Riceve la sessione dell'app dell'utente dell'evento (con asUser) e la propria memoria relativa a quell'utente.
[].start.teamstringChiave del team da avviare (deve essere pubblicato).
[].start.jobstringChiave di un job di dati collegato in spec.data.jobs da eseguire.
[].goalstringIl compito per un agente o team avviato. {event} è l'evento in JSON (al massimo 8000 caratteri), {record.<field>} o {<field>} un campo del record, {date} la data di oggi (UTC). Predefinito: il goalTemplate dell'agente avviato, altrimenti An event happened in the app: {event}. Do your task for it. Quando il goal non menziona {event}, {id} o {record.id}, vengono aggiunti la raccolta e l'id del record.
[].asUserbooleantruetrue (predefinito): agisce per l'utente a cui appartiene l'evento (l'utente del record, l'acquirente, il richiedente): l'agente riceve la sua sessione dell'app, quindi i suoi strumenti raggiungono solo i suoi record, e notify verso owner e charge usano quell'utente. false: nessun utente.
[].notifynotifyInvia un'email in testo semplice invece di avviare un agente (vedi $defs/notify).
[].writeobjectSalva i dati dell'evento come record, senza un agente (un webhook da un dispositivo, un partner, un modulo esterno). Un trigger cron non lo esegue (un evento a tempo non porta dati). La destinazione non può essere di proprietà instance né essere la raccolta che attiva il trigger; una destinazione di proprietà dell'utente richiede l'utente dell'evento. Il salvataggio del record attiva a sua volta i trigger di quella raccolta.
[].write.collectionstringsìLa raccolta dichiarata in cui viene scritto il record.
[].write.fieldsmappa di stringMappatura campo del record → percorso puntato nei dati dell'evento (ad es. temperature: reading.temp). Predefinito: i valori di primo livello dell'evento i cui nomi sono campi dichiarati dalla raccolta. Gli oggetti vengono salvati come testo JSON (al massimo 4000 caratteri); l'intero record può essere al massimo di 32.000 caratteri.
[].write.keyBystringUn campo mappato il cui valore diventa l'id del record, così che lo stesso evento consegnato due volte aggiorni un solo record invece di crearne due. Senza di esso ogni evento crea un nuovo record.
[].chargeobjectPreleva crediti dall'utente dell'evento, una volta per evento (una commissione di successo quando una pratica viene approvata, una tariffa per contatto). Il saldo può scendere sotto zero. Richiede un evento con un utente: non con cron o webhook.
[].charge.creditsintegersìCrediti prelevati, da 1 a 100.000. Valori: ≥ 1; ≤ 100000.
[].charge.reasonstringTesto della voce di registro che l'utente vede, al massimo 120 caratteri. Predefinito: la chiave del trigger. Valori: lunghezza max. 120.

spec.approvals

lista di object. Punti di controllo umani: un agente che ha l'approvazione in awaits la richiede con lo strumento request_<key>, una persona decide in una vista approvals, e i trigger sull'approvazione riprendono il lavoro.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca dell'approvazione, richiamata da agents[].awaits, triggers[].on.approval e views[].approvals; lo strumento generato è request_<key> (i trattini diventano trattini bassi).
[].titletextEtichetta della richiesta mostrata nella vista delle approvazioni. Predefinito: la chiave.
[].descriptionstringChe cosa viene approvato; entra nella descrizione dello strumento request_<key> che l'agente vede.
[].rolestringIl ruolo che decide (una chiave di auth.roles): un ruolo dello staff (admin, invite o derived), mai il ruolo di registrazione. Gli amministratori dell'app possono sempre decidere; nessuno decide sulla propria richiesta. Obbligatorio a meno che decidedBy sia requester, che non prevede ruolo.
[].fieldslista di stringCampi della richiesta mostrati alla persona che decide. Predefinito: tutti i campi della richiesta.
[].timeoutMinutesintegerMinuti dopo i quali una richiesta in sospeso viene decisa da onTimeout (verificato dal tick dello scheduler): da 1 a 10.080 (7 giorni). Senza di esso una richiesta attende finché qualcuno decide. Valori: ≥ 1; ≤ 10080.
[].onTimeoutenum"reject"La decisione alla scadenza: reject (predefinito) o approve. La decisione viene registrata come approved o rejected, presa da timeout. Valori: approve, reject.
[].decidedByenum"role"role (predefinito): decidono le persone con role (o gli amministratori dell'app), mai sulla propria richiesta. requester: conferma solo l'utente il cui agente l'ha chiesta (la proposta del proprio agente: una rosa di candidati, un piano settimanale); la richiesta richiede la sessione di quell'utente. Valori: role, requester.

spec.templates

lista di object. Agenti che gli utenti dell'app creano per sé (una vista instances li elenca): ogni istanza ha parametri, pianificazione, memoria e record propri. Un'esecuzione di un'istanza parte come un'esecuzione da trigger e il suo risultato diventa un record della raccolta writesTo dell'agente (o del team), contrassegnato con l'istanza.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeysìChiave univoca del template, richiamata da una vista instances (template).
[].titletextTitolo della vista delle istanze per questo template. Predefinito: la chiave.
[].descriptiontextTesto mostrato sotto il titolo della vista delle istanze.
[].agentstringChiave dell'agente eseguito da ogni istanza. Esattamente uno tra agent e team.
[].teamstringChiave del team eseguito da ogni istanza. Esattamente uno tra agent e team.
[].paramslista di fieldsìI parametri che un utente compila quando crea un'istanza (campi di modulo; i nomi devono essere univoci). I valori vengono verificati: obbligatorietà, numeri, booleani, url (un indirizzo http(s)), opzioni; il testo viene troncato a maxLength, predefinito 2000 caratteri. Un campo alimentato da optionsFrom: collection:<name> deve indicare un record che l'utente può leggere.
[].scheduleobjectQuando le istanze vengono eseguite autonomamente. Senza un cron un'istanza viene eseguita solo quando il suo proprietario preme Esegui.
[].schedule.cronstringCron UTC a 5 campi predefinito di una nuova istanza. Un cron fornito dall'utente può contenere solo cifre, spazi e * , / -.
[].schedule.userCanChangebooleantruetrue (predefinito): l'utente può impostare il proprio cron quando crea o modifica un'istanza. false: ogni istanza usa cron.
[].maxPerUserinteger5Quante istanze (attive o in pausa) può avere un utente: da 1 a 1000, predefinito 5. Valori: ≥ 1; ≤ 1000.
[].roleslista di stringRuoli autorizzati a creare istanze. Predefinito: tutti gli utenti autenticati; gli amministratori dell'app possono sempre.
[].costobjectCrediti addebitati all'utente proprietario dell'istanza.
[].cost.perRunnumberCrediti prelevati (arrotondati a un numero intero) all'avvio di ogni esecuzione; senza di essi l'esecuzione non parte. Restituiti se l'avvio fallisce o l'esecuzione termina senza risultato. Le esecuzioni avviate a mano da un amministratore sono gratuite. Valori: ≥ 0.
[].cost.perMonthnumberCrediti mensili per istanza. Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0.
[].goalstringIl compito di ogni esecuzione: i parametri come {name}, {instance} (il titolo dell'istanza), {date} (UTC), {lang} (la lingua predefinita dell'app), {user} (l'email del proprietario). Predefinito: il goalTemplate dell'agente (o del team), altrimenti una riga name: value per ogni parametro compilato.
[].deliverdeliverInvia per email il report di ogni esecuzione completata di un'istanza; to è predefinito a owner, il proprietario dell'istanza.

spec.channels

lista di object. Dove le conversazioni raggiungono un agente: web sono le viste chat dell'app; phone, telegram ed email collegano un agente a un numero, un bot, una casella di posta. Oggi vengono solo validati (l'agente deve esistere; triggers[].on.call deve indicare un canale telefonico): il runtime non collega ancora alcun canale, e le viste chat scelgono il proprio agente con source.

ProprietàTipoObbl.PredefinitoDescrizione
[].keykeyChiave del canale, richiamata da triggers[].on.call. Predefinito: il tipo del canale.
[].typeenumsìweb (le viste chat dell'app), phone, telegram o email. Valori: web, phone, telegram, email.
[].agentstringsìChiave dell'agente che risponde su questo canale (deve esistere).
[].greetingtextPrimo messaggio al chiamante o visitatore. Accettato dallo schema; non ancora usato dal runtime.
[].languagestringLingua della conversazione. Accettato dallo schema; non ancora usato dal runtime.
[].voicestringVoce di un canale telefonico. Accettato dallo schema; non ancora usato dal runtime.
[].numberstringphone: il numero, impostato quando il telefono viene attivato. Accettato dallo schema; non ancora usato dal runtime.
[].addressstringemail: l'indirizzo della casella di posta. Accettato dallo schema; non ancora usato dal runtime.

spec.egress

object. Gli host esterni che gli strumenti http dell'app possono chiamare (API HTTPS pubbliche i cui termini lo consentono). Nient'altro è raggiungibile: l'host dell'URL di ogni strumento http deve essere elencato qui, altrimenti la validazione fallisce, e al momento della chiamata il runtime rifiuta anche qualsiasi host che si risolve in un indirizzo privato o interno e non segue i reindirizzamenti.

ProprietàTipoObbl.PredefinitoDescrizione
hostslista di stringsìHost consentiti (al massimo 20), nomi esatti come api.example.com. Una voce *.<domain> serve solo per l'host proprio dell'utente salvato con la sua credenziale (un URL di strumento che inizia con https://{host}, ad es. *.myshopify.com). Valori: elementi max. 20.
notesstringPerché viene usato ciascun host e i relativi termini d'uso o licenza (al massimo 1000 caratteri). Per i revisori; non usato dal runtime. Valori: lunghezza max. 1000.

Tipi condivisi

Tipi usati in più punti, collegati dalle tabelle sopra.

lang

string. Codice di lingua di due lettere minuscole, ad es. en. Valori: formato ^[a-z]{2}$.

key

string. Un identificatore: inizia con una lettera minuscola, seguita da lettere minuscole, cifre, _ o -. Valori: formato ^[a-z][a-z0-9_-]*$.

color

string. Un colore nel formato #rrggbb (sei cifre esadecimali). Valori: formato ^#[0-9a-fA-F]{6}$.

palette

object. Un insieme dei quattro colori principali. Ciascuno diventa una variabile CSS (--primary, …); un colore omesso mantiene il valore predefinito del runtime.

ProprietàTipoObbl.PredefinitoDescrizione
primarycolorTitoli, nome dell'app nell'intestazione, striscia di annuncio e segnaposti numerati. Predefinito #1f2a44.
accentcolorLink, pulsanti principali (a meno che branding.button indichi un altro colore), evidenziazioni e serie dei grafici. Predefinito #2563eb.
backgroundcolorSfondo della pagina; card e linee ne derivano. Predefinito #f7f8fa.
foregroundcolorColore del testo. Predefinito #161b26.

text

string | object. Un testo mostrato alle persone: una stringa semplice, o una stringa per lingua (ad es. {en: Book, it: Prenota}). Il runtime mostra la lingua del visitatore; se manca, la prima stringa fornita.

option

string | object. Una scelta di un campo select o multiselect: una stringa semplice (valore ed etichetta coincidono) o un oggetto con etichetta propria, vincolo di piano e valore padre.

ProprietàTipoObbl.PredefinitoDescrizione
valuestringsìIl valore salvato e passato all'agente.
labeltextCiò che vede la persona; predefinito: il valore. In un modulo di esecuzione l'etichetta scelta è disponibile anche nel goal come {<field>_label}.
gatedBystringChiave di un piano o pacchetto che sblocca questa opzione. Gli utenti che non lo hanno vedono l'opzione disabilitata, con il piano necessario; gli amministratori dell'app sono esenti. Il server lo impone sul modulo di esecuzione (HTTP 402); i moduli delle raccolte si limitano a disabilitarla nella pagina.
parentstringCon dependsOn sul campo: il valore del campo padre a cui appartiene questa opzione. Il modulo mostra solo le opzioni del padre scelto; il server lo impone sul modulo di esecuzione.

field

object. Un campo di un modulo: il modulo di input delle esecuzioni (spec.inputForm.fields), i record di una raccolta (data.collections[].fields, mostrati dalle viste modulo e dalla pagina dati degli amministratori) o i parametri di un template. Il server ricontrolla ogni valore inviato; il modulo nel browser è solo una comodità.

ProprietàTipoObbl.PredefinitoDescrizione
namestringsìChiave del valore (lettere minuscole, cifre e _, deve iniziare con una lettera). In un modulo di input è anche il segnaposto del goal {name}; per una select, {name_label} fornisce l'etichetta dell'opzione scelta, e per un campo file {name_text} fornisce il testo estratto. Valori: formato ^[a-z][a-z0-9_]*$.
labeltextTesto mostrato accanto al campo (predefinito: name); usato anche nei messaggi di errore e per abbinare le intestazioni delle colonne CSV nella pagina dati.
typeenumsìIl tipo di input e come il valore viene verificato e salvato. text (riga singola), textarea (più righe), email, url, date (selettore di data): testo; i moduli dei record verificano anche il formato dell'email e una data YYYY-MM-DD. number: deve essere un numero (altrimenti "not a number"). boolean: una casella di spunta, salvata come true/false. select: un valore di options (o dei record indicati da optionsFrom); multiselect: un elenco di questi. urls, array: un elenco, un valore per riga (o separati da virgole). file: un caricamento (vedi accept, maxMb, multiple, extract, capture). location: una posizione salvata come "lat,lng" con 6 decimali, dal GPS sui telefoni. barcode: un codice letto con la fotocamera o digitato (una riga, al massimo 512 caratteri). country, city, object, json e relation sono mostrati come semplice campo di testo e salvati come testo (un campo con optionsFrom diventa una select). Valori: text, textarea, number, boolean, select, multiselect, url, urls, email, date, file, country, city, object, array, relation, json, location, barcode.
requiredbooleanIl campo deve avere un valore: il server risponde "<label> is required". Nel modulo di esecuzione anche un booleano obbligatorio non spuntato conta come mancante (da usare per il consenso); nei moduli dei record i booleani non sono mai obbligatori. Un campo file obbligatorio richiede almeno un file caricato.
maxLengthintegerNumero massimo di caratteri per un valore di testo. Il modulo di input rifiuta testo più lungo ("at most N characters"); i moduli dei record lo troncano a questa lunghezza (10.000 caratteri se non impostato); i parametri dei template vengono troncati a questo valore (2.000 se non impostato). Valori: ≥ 1.
optionslista di optionLe scelte di una select o multiselect: stringhe semplici, oppure oggetti con value, label, gatedBy e parent. Un valore non presente nell'elenco viene rifiutato ("invalid choice"). I blocchi di dati mostrano l'etichetta dell'opzione per un valore salvato.
optionsFromstringcollection:<name>[.<labelField>]: le scelte sono i record di quella raccolta che l'utente può leggere (dal più recente, fino a 200), con l'id del record come valore e labelField (o un consueto campo nome) come etichetta; il campo viene mostrato come select (o rimane multiselect). Il server rifiuta un id che l'utente non può leggere. Quando non c'è ancora nulla da scegliere, il modulo lo segnala e rimanda a una vista modulo che ne aggiunge uno. job:<key> non è supportato dal runtime.
dependsOnstringNome di un altro campo dello stesso modulo il cui valore filtra le opzioni di questo campo: vengono mostrate solo le opzioni il cui parent è uguale a quel valore (e le opzioni senza padre), e la scelta viene azzerata quando cambia il padre. Il modulo di input rifiuta inoltre, sul server, un'opzione che non appartiene al padre scelto. La validazione verifica che il campo esista in inputForm.
visibleWhenstringMostra il campo solo quando la condizione è vera sugli altri valori: field == 'x', field != 'x', field (ha un valore) o !field, uniti con && e ||; qualsiasi altra espressione conta come falsa. Nel modulo di input, il valore di un campo nascosto viene scartato sul server.
roleslista di stringSolo gli utenti con uno di questi ruoli vedono il campo. Nel modulo di input il server ignora un valore inviato da altri utenti e usa invece default; nei moduli dei record il campo è solo nascosto nella pagina.
defaultIl valore iniziale nel modulo. Nel modulo di input un campo vuoto lo assume sul server (e gli utenti senza i roles del campo lo ricevono sempre). In una raccolta, i nuovi record privi del campo lo ricevono, chiunque li crei (modulo, strumento di un agente, trigger), quindi un trigger su ad es. status: pending scatta per i record creati senza quel campo.
helptextSuggerimento mostrato nel campo come segnaposto (sotto il campo per i parametri dei template); per un campo di raccolta, anche la descrizione di quel campo negli strumenti write e append degli agenti.
gatedBystringChiave del piano che sblocca l'intero campo. Nel modulo di input, un utente senza il piano che compila il campo riceve 402 "<label> needs the plan <key>" (gli amministratori sono esenti). Solo i piani in abbonamento vengono registrati sugli utenti, quindi una chiave di pacchetto non lo sblocca mai. I moduli dei record non lo verificano.
fieldslista di fieldtype object o array: sottocampi. Il runtime non li visualizza né li verifica ancora; vengono letti solo per individuare le funzionalità del telefono (fotocamera, posizione, codice a barre) che un'app per telefono deve richiedere.
relationstringtype relation: la raccolta di destinazione. Accettato dallo schema; non ancora usato dal runtime: per scegliere un record, impostare optionsFrom: collection:<name>.
acceptlista di enumtype file: le estensioni di file accettate (al massimo 12). Predefinito: pdf, docx, xlsx, csv, txt, jpg, jpeg, png, webp. Il server verifica anche che i byte corrispondano all'estensione e rifiuta gli altri con "this field accepts …". Valori: elementi max. 12; pdf, docx, xlsx, csv, txt, md, json, html, xml, jpg, jpeg, png, webp, gif.
maxMbnumbertype file: il file più grande in MB (predefinito 10, mai più di 15). I file più grandi vengono rifiutati con "the file is larger than N MB". Valori: ≥ 0.1; ≤ 15.
multiplebooleanfalsetype file: consente fino a 10 file invece di uno (predefinito false). Il valore è allora un elenco di id di file.
extractenum"text"type file: text (predefinito) estrae al caricamento il testo di file PDF, Word, Excel, CSV e di testo (fino a 60.000 caratteri per file), e il goal di un'esecuzione dell'agente lo riceve come {<field>_text} (tutti i file di un'esecuzione condividono 30.000 caratteri); none salva il file senza testo. Le immagini non hanno testo: un agente le legge con uno strumento dell'app con azione read_file. Valori: text, none.
capturebooleantype file: scatta una foto con la fotocamera invece di scegliere un file: solo immagini, ridotte prima del caricamento, con la fotocamera nativa all'interno dell'app per telefono. Un'app per telefono costruita dal manifest richiede quindi il permesso per la fotocamera.

appTool

object. Uno strumento che l'app fornisce a un agente tramite il suo endpoint MCP. Lo esegue il runtime, mai l'agente: read/search/show/write/append generici su una raccolta dichiarata, call di uno slot Python, read_file di un file caricato, http verso un'API esterna consentita. Uno strumento su una raccolta di proprietà user o instance (e qualsiasi strumento con scope user o session) prende la sessione dell'app dal compito dell'agente, e raggiunge solo i record di quell'utente più quelli che le regole di accesso della raccolta concedono al suo ruolo.

ProprietàTipoObbl.PredefinitoDescrizione
namestringsìNome dello strumento chiamato dall'agente: lettere minuscole, cifre e _, deve iniziare con una lettera. Univoco per app, a meno che due agenti dichiarino lo stesso strumento con la stessa azione, destinazione e limiti. Valori: formato ^[a-z][a-z0-9_]*$.
descriptionstringsìChe cosa fa lo strumento, per l'agente (lo vede nel proprio elenco di strumenti). Due agenti possono descrivere uno strumento condiviso con parole proprie.
actionenumsìread: un record per id, oppure senza id i 50 più recenti che l'utente può leggere. search/show (stesso comportamento): i record che corrispondono a where (campi uguali) e text, dal più recente, limit 1–100, predefinito 20. write: aggiorna un record per id (richiede accesso in scrittura) o ne crea uno; append: ne crea uno; i record creati ricevono i valori predefiniti dei campi della raccolta, contano per i limiti create:<collection> e attivano i trigger. call: esegue lo slot Python. read_file: il testo (o l'immagine) di un file caricato dall'utente della sessione. http: una richiesta a un'API HTTPS esterna (vedi http). delegate, approval, remember sono generati da delegates, awaits e memory: non dichiararli a mano. Valori: read, search, write, append, show, call, delegate, approval, remember, http, read_file.
collectionstringLa raccolta dichiarata che lo strumento legge o scrive (non una riservata); obbligatoria per read, search, show, write, append. Per un agente che i visitatori usano senza accedere, uno strumento non può raggiungere una raccolta org né scrivere in una raccolta app o shared.
scopestringuser o session: lo strumento prende la sessione dell'app e agisce per quell'utente. Uno strumento su una raccolta di proprietà user o instance, read_file e uno strumento http con una credenziale per utente prendono la sessione indipendentemente da questo valore. all e context:<key> sono accettati dallo schema; il runtime non attribuisce loro ancora un significato particolare.
extensionstringChiave di un'estensione dell'app originale che implementa lo strumento. Questi strumenti non vengono serviti dal runtime e la validazione li salta, finché non diventano uno slot o un server MCP.
slotstringaction call: chiave dello slot Python che implementa lo strumento. Lo slot riceve {args, userId} (args dall'agente) e il suo valore di ritorno torna all'agente.
agentstringL'agente delegato di uno strumento delegate generato (ask_<agent>). Impostato dal runtime a partire da delegates; dichiarare invece delegates.
approvalstringL'approvazione di uno strumento approval generato (request_<approval>). Impostato dal runtime a partire da awaits; dichiarare invece awaits.
httpobjectaction http: la richiesta eseguita dal runtime. L'agente compila solo query (testo, numeri, booleani), path (aggiunto a url, quando allowPath) e body (JSON, al massimo 100.000 caratteri; non per GET o DELETE); mai header, host, metodo o credenziali. Solo https, nessun reindirizzamento seguito, indirizzi verificati al momento della connessione (nessuna rete privata o di loopback). La risposta è {status, data} per JSON, altrimenti {status, text} (al massimo 20.000 caratteri, con truncated), più source quando attribution è impostato.
http.methodenum"GET"Metodo HTTP: GET (predefinito), POST, PUT, PATCH o DELETE. Un agente che i visitatori usano senza accedere può avere solo strumenti GET. Lo schema prevede PUT, PATCH e DELETE per scrivere sull'account proprio dell'utente con una credenziale; il runtime non lo impone. Valori: GET, POST, PUT, PATCH, DELETE.
http.urlstringsìURL di base, solo https://. Il suo host deve essere elencato in spec.egress.hosts. https://{host}/… è l'host proprio dell'utente salvato con la sua credenziale (il suo negozio): richiede credential e una voce *.<domain> in spec.egress.hosts a cui l'host salvato corrisponda. Valori: formato ^https://([A-Za-z0-9.-]+|\{host\})(/[^\s?#]*)?$.
http.allowPathbooleanfalseConsente all'agente di aggiungere un percorso sotto url (ad es. /company/{number}): lettere, cifre, . _ ~ - /, al massimo 300 caratteri, senza segmenti . o ... Predefinito false: un percorso viene rifiutato.
http.headersmappa di stringHeader fissi e non segreti (ad es. Accept). Gli header chiamati Authorization, Cookie, X-Api-Key, Host, X-Forwarded*, Forwarded o Proxy-* vengono scartati; una chiave va in credential.
http.timeoutMsinteger20000Timeout della richiesta in millisecondi: da 1000 a 30.000, predefinito 20.000. Valori: ≥ 1000; ≤ 30000.
http.maxBytesinteger500000Dimensione massima della risposta in byte: da 1000 a 2.000.000, predefinito 500.000. Oltre questo limite la risposta viene troncata e contrassegnata truncated. Valori: ≥ 1000; ≤ 2000000.
http.attributionstringLicenza o attribuzione della fonte, restituita come source con ogni risultato (ad es. TED, CC BY 4.0). Al massimo 200 caratteri. Valori: lunghezza max. 200.
http.credentialobjectUna chiave collegata per questo provider (una credenziale api_key in spec.data.credentials: quella dell'utente della sessione, o quella dell'app quando il suo scope è org), aggiunta dal runtime; l'agente non la vede mai, ed è mascherata come [credential] nella risposta. Header predefinito: Authorization: Bearer {secret}. Se la chiave non è collegata, lo strumento risponde 409 chiedendo all'utente di collegarla nella pagina del suo account.
http.credential.providerstringsìIl provider di una credenziale api_key dichiarata in spec.data.credentials.
http.credential.headerstringHeader che trasporta la chiave, ad es. X-Shopify-Access-Token, X-API-Key. Predefinito Authorization. Valori: formato ^[A-Za-z0-9-]{1,60}$.
http.credential.formatstringCome viene costruito il valore dell'header attorno a {secret}: Bearer {secret} (predefinito), Token {secret}, {secret}. Al massimo 60 caratteri. Valori: lunghezza max. 60.
http.credential.querystringInvia la chiave come questo parametro di query invece che in un header. Valori: formato ^[A-Za-z0-9_-]{1,40}$.

section

object | object | object | object | object | object | object. Un blocco di una vista pagina, visualizzato dall'alto verso il basso. Il type del blocco ne seleziona la forma: hero, steps, cards, text, note, html, view o data. Il testo passa per il renderer Markdown sicuro; i link possono essere solo percorsi della stessa app, ancore o https.

ProprietàTipoObbl.PredefinitoDescrizione
type"hero"sìTipo di blocco; sempre hero per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
eyebrowtextRiga breve sopra il titolo (una riga di Markdown).
titletextsìIl titolo principale (una riga di Markdown, obbligatorio). Le parole in grassetto vengono mostrate evidenziate.
texttextTesto introduttivo sotto il titolo (Markdown). In un hero split senza aside riempie la colonna destra.
actionslista di objectPulsanti sotto il testo, in ordine. Un pulsante verso la pagina di accesso (/login…) viene nascosto agli utenti che hanno già effettuato l'accesso.
actions[].labeltextsìTesto del pulsante (stringa semplice o una per lingua).
actions[].hrefstringsìLink: un percorso della stessa app (/v/…), un'ancora (#…) o un URL https. Qualsiasi altro valore diventa "#". Valori: formato ^(/(?!/)|#|https://).
actions[].styleenumprimary (predefinito): un pulsante pieno; ghost: un pulsante con solo il bordo. Valori: primary, ghost.
notetextRiga piccola sotto i pulsanti, ad es. una riga di fiducia o che cosa è incluso (una riga di Markdown).
layoutenumstack (predefinito): tutto in una colonna. split: due colonne, titolo e pulsanti a sinistra, aside (o il testo) a destra. Impostare aside rende anch'esso l'hero diviso. Valori: stack, split.
asidetextColonna destra di un hero diviso: una card HTML (ad es. una conversazione di esempio o un mockup di prodotto), ripulita come un blocco html. Impostarla rende l'hero diviso.
bandbooleanMostra l'hero su una fascia colorata a tutta larghezza. Predefinito false.
eyebrowStyleenumLa riga sopra il titolo: text (predefinito) testo semplice, pill in una pillola, pill-dot in una pillola con un punto. Valori: text, pill, pill-dot.
typeenumsìsteps: elementi numerati in ordine (come funziona); cards: elementi senza numeri (funzionalità, piani, casi d'uso). Valori: steps, cards.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
titletextTitolo del blocco (una riga di Markdown).
introtextTesto sotto il titolo, prima degli elementi (Markdown).
itemslista di objectsìGli elementi della griglia (almeno uno). Valori: elementi min. 1.
items[].titletextTitolo dell'elemento (una riga di Markdown).
items[].texttextTesto dell'elemento (Markdown).
items[].badgetextMostrato sopra il titolo dell'elemento: un'emoji da sola viene mostrata come icona, qualsiasi altro testo come piccolo badge.
type"text"sìTipo di blocco; sempre text per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
titletextTitolo del blocco (una riga di Markdown).
contenttextsìCorpo del blocco, in Markdown (obbligatorio).
type"note"sìTipo di blocco; sempre note per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
contenttextsìTesto della nota, in Markdown (obbligatorio).
type"html"sìTipo di blocco; sempre html per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
htmltextsìHTML personalizzato (obbligatorio; vengono letti al massimo 100.000 caratteri). Vengono mantenuti solo tag di layout, testo, tabella, immagine, link e details; nessun elemento script, form, iframe o style. Attributi: class, id, href, src, alt, title, width, height, colspan, rowspan, open e style; href e src devono essere percorsi della stessa app, ancore o https. Lo stile inline mantiene solo proprietà di colore, sfondo, font, spaziatura, bordo, dimensione e layout flex/grid, mai url() o import.
type"view"sìTipo di blocco; sempre view per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -), per link come #book. Valori: formato ^[a-z0-9][a-z0-9-]*$.
titletextTitolo mostrato sopra la vista incorporata.
viewkeysìChiave di un'altra vista di questa app (non la pagina stessa). Il blocco viene omesso quando il visitatore non può aprire quella vista, quando è una page o, per i visitatori che non hanno effettuato l'accesso, quando è history, account, report o run. Una vista report o run mostra l'ultimo report completato dell'utente con un link a esso.
type"data"sìTipo di blocco; sempre data per questo tipo di blocco.
idstringAncora del blocco (lettere minuscole, cifre e -, deve iniziare con una lettera o una cifra), per link come #how-it-works. Valori: formato ^[a-z0-9][a-z0-9-]*$.
titletextTitolo del blocco (testo semplice, il Markdown non viene interpretato).
introtextTesto sotto il titolo (testo semplice, il Markdown non viene interpretato).
sourcestringsìDa dove provengono le righe (obbligatorio). run: le esecuzioni dell'utente autenticato (nessuna per i visitatori); catalog[:<category>]: il catalogo pubblico delle fonti della piattaforma, una categoria o un elenco separato da virgole (predefinito: tutte; in cache 60 secondi); job:<key>: il dataset più recente di un job di dati in data.jobs (in cache 60 secondi; "Job not linked" quando il job non ha id di progetto e di job); collection:<name>: record di una raccolta dichiarata che chi guarda può leggere (ownedBy: app o shared per tutti). Valori: formato ^(run|catalog(:[a-z_,]+)?|job:[a-z0-9_-]+|collection:[a-z0-9_]+)$.
pathstringPercorso puntato (al massimo due livelli) verso un elenco all'interno di ogni riga; gli elenchi di tutte le righe vengono appiattiti nelle righe mostrate (ad esempio assets di ciascun segnale). Applicato prima dei filtri. Con una source della vista scritta come collection:<name>.<path>, il runtime lo ricava dalla sorgente quando non è impostato. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
displayenumsìCome vengono mostrate le righe. Obbligatorio. table (visualizzazione predefinita): una colonna per campo; cards: una griglia, con il primo campo come titolo; list: una riga di testo per ogni riga, con il primo campo in grassetto; kpi: numeri chiave da kpis (mostrati anche senza righe); bar: barre orizzontali, primo campo = etichetta, secondo = valore; chart: un grafico SVG di tipo chart. Valori: table, cards, list, kpi, bar, chart.
fieldslista di objectLe colonne, in ordine (al massimo 12). Senza fields, il runtime mostra i primi 6 nomi di campo trovati nelle righe. Su una sorgente collection: (senza path) un campo senza label prende l'etichetta del campo della raccolta, e un campo select mostra l'etichetta dell'opzione al posto del valore salvato. Valori: elementi max. 12.
fields[].keystringsìCampo della riga da mostrare, come percorso puntato di al massimo due livelli (ad es. price o address.city). Per una sorgente job deve essere una colonna del dataset. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
fields[].labeltextIntestazione della colonna (stringa semplice o una per lingua). Predefinito: l'etichetta del campo della raccolta su una sorgente collection, altrimenti la chiave.
fields[].formatenumCome viene mostrato il valore. text (predefinito): così com'è; un valore in forma di posizione ("lat,lng") diventa un link a una mappa, un oggetto viene mostrato come JSON e, in una tabella, un testo più lungo di 220 caratteri mostra un estratto semplice con il testo completo al passaggio del mouse. number: numero localizzato, al massimo 2 decimali; money: importo nella billing.currency dell'app (predefinito EUR), senza decimali; percent: il valore è già una percentuale, mostrata con segno e colorata (+12.5%); ratio: una frazione moltiplicata per 100 e mostrata come percentuale (0.25 → +25%); date: giorno, mese abbreviato, anno; link: un URL https come link cliccabile abbreviato (gli altri valori come testo semplice); badge: un'etichetta a pillola; location: una posizione "lat,lng" come link a una mappa. Un valore vuoto mostra un trattino. Valori: text, number, money, percent, ratio, date, link, badge, location.
filterslista di objectCondizioni che ogni riga deve soddisfare (tutte, al massimo 8), applicate prima di raggruppamento, ordinamento e limite. Su una sorgente job: diventano la clausola WHERE della query sul dataset. Valori: elementi max. 8.
filters[].fieldstringsìCampo letto dalla condizione, come percorso puntato di al massimo due livelli. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
filters[].openumsìConfronto. = e != confrontano come testo; >, >=, <, <= confrontano come numeri e scartano le righe il cui valore non è un numero; contains: corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole. Valori: =, !=, >, >=, <, <=, contains.
filters[].valuestring | number | booleansìValore confrontato con il campo: testo, numero o booleano.
sortobjectOrdine delle righe, applicato dopo filtri e raggruppamento e prima del limite. Senza di esso le righe mantengono l'ordine della sorgente (una sorgente run mostra prima le più recenti; le righe raggruppate sono ordinate per valore del gruppo, in ordine crescente).
sort.fieldstringsìCampo in base a cui ordinare (percorso puntato di al massimo due livelli). I numeri sono confrontati come numeri, tutto il resto come testo. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
sort.direnumdesc (predefinito) o asc. Valori: asc, desc.
limitintegerNumero massimo di righe (o gruppi) mostrati, 1–200. Predefinito 50. I numeri chiave (kpis) sono calcolati solo su queste righe. Valori: ≥ 1; ≤ 200.
kpislista di objectdisplay kpi: i numeri chiave, al massimo 6, ciascuno un aggregato sulle righe. Senza kpis viene mostrato un solo numero: il conteggio delle righe. Valori: elementi max. 6.
kpis[].labeltextsìTesto sotto il numero (stringa semplice o una per lingua).
kpis[].aggenumsìL'aggregato: count (righe, nessun campo necessario), sum, avg, min, max (sui valori numerici del campo; i non numerici sono ignorati, vuoto se non ce ne sono), last (il valore del campo nella prima riga non vuota nell'ordine corrente). Valori: count, sum, avg, min, max, last.
kpis[].fieldstringCampo letto dall'aggregato (percorso puntato di al massimo due livelli). Non necessario per count. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
kpis[].formatenumCome viene mostrato l'aggregato: number, money (valuta dell'app, predefinito EUR), percent, ratio (×100 come percentuale), date, link, badge o text. Predefinito: number per count, valore semplice per gli altri aggregati. Valori: text, number, money, percent, ratio, date, link, badge.
emptytextMessaggio mostrato quando non ci sono righe (non per display kpi). Predefinito: "No data yet." ("Ancora nessun dato." in italiano).
previewobjectAnteprima per gli utenti senza piano: con unlessPlan impostato, gli utenti che non hanno quel piano (amministratori esclusi) vedono solo le prime rows righe, una riga che indica quante altre righe sblocca il piano, e nessun pulsante sulle righe.
preview.rowsintegerRighe mostrate agli utenti senza il piano. Predefinito 3; 0 le nasconde tutte. Valori: ≥ 0.
preview.unlessPlanstringChiave di un piano o pacchetto in billing; gli utenti i cui piani lo includono vedono tutte le righe. La validazione rifiuta una chiave che non sia un piano o un pacchetto.
chartenumdisplay chart: il tipo di grafico. bar (predefinito): barre raggruppate; line: linee con punti; pie: una fetta per riga, solo dalla prima serie (i valori negativi contano come 0); stacked: barre sovrapposte (valori negativi ignorati). Il primo campo fornisce le etichette, ogni altro campo una serie. Valori: bar, line, pie, stacked.
groupByobjectRaggruppa le righe (dopo i filtri): una riga per ogni valore di field (date raggruppate per giorno, settimana o mese) con una colonna count e una colonna per ogni aggregato in aggs; i gruppi sono ordinati per valore, in ordine crescente, poi si applicano sort e limit. Usare il campo del gruppo, count e le chiavi degli aggregati come fields. minCount nasconde i gruppi piccoli; acrossUsers su una raccolta di record degli utenti aggrega in forma anonima i record di tutti gli utenti (richiede minCount ≥ 5; nessun record viene mai mostrato).
groupBy.fieldstringsìCampo il cui valore forma il gruppo (percorso puntato). Le righe senza valore vanno in un gruppo chiamato "—".
groupBy.bucketenumTratta il campo come una data e raggruppa per day (YYYY-MM-DD), week (la data del lunedì di quella settimana) o month (YYYY-MM), in UTC. Le righe il cui valore non è una data vanno in "—". Senza bucket, ogni valore distinto è un gruppo. Valori: day, week, month.
groupBy.aggslista di objectsìLe colonne aggregate di ogni gruppo (al massimo 8). count viene sempre aggiunto. Valori: elementi max. 8.
groupBy.aggs[].keystringsìNome della colonna in cui viene scritto l'aggregato; richiamarlo in fields, sort e kpis. Valori: formato ^[A-Za-z_][A-Za-z0-9_]*$.
groupBy.aggs[].aggenumsìL'aggregato sulle righe del gruppo: count (righe, nessun campo necessario), sum, avg, min, max (sui valori numerici del campo; i non numerici sono ignorati, vuoto se non ce ne sono), last (il valore del campo nella prima riga non vuota nell'ordine corrente). Valori: count, sum, avg, min, max, last.
groupBy.aggs[].fieldstringCampo letto dall'aggregato (percorso puntato). Non necessario per count.
groupBy.minCountintegerI gruppi con meno righe di questo valore vengono esclusi (1–1000, predefinito 1). Deve essere almeno 5 con acrossUsers. Valori: ≥ 1; ≤ 1000.
groupBy.acrossUsersbooleanSu una sorgente collection: la cui raccolta è ownedBy: user: aggrega i record di tutti gli utenti, non solo di chi guarda, e mostra solo i gruppi (un benchmark anonimo). La validazione lo rifiuta su altre sorgenti e con minCount inferiore a 5; il runtime legge i record di tutti gli utenti solo quando minCount è almeno 5.
actionslista di recordActionPulsanti su ogni riga (al massimo 4): chiamata, indicazioni stradali, condivisione, aggiunta al calendario. Non mostrati sulle righe di un'anteprima bloccata. share e calendar aggiungono il permesso corrispondente all'app per telefono. Valori: elementi max. 4.

notify

object. Un'email in testo semplice che l'app invia quando il trigger scatta (invece di avviare un agente); lo stesso messaggio arriva anche sui telefoni dei destinatari quando l'app ha le notifiche push. subject e body possono usare {record.<field>} (o {<field>}), {date} (UTC) e {app} (il nome dell'app), nella lingua predefinita dell'app. Inviata una volta per evento; al massimo 300 email per app al giorno e 10 per destinatario al giorno, al massimo 50 destinatari per email.

ProprietàTipoObbl.PredefinitoDescrizione
channel"email""email"Canale di consegna; solo email (il predefinito).
tostring | lista di stringsìChi la riceve: owner (l'utente dell'evento o dell'esecuzione), admins (le email degli amministratori dell'app), role:<role key> (gli utenti con quel ruolo; le email degli amministratori per un ruolo admin), record.<field> (un indirizzo email, o un elenco, nel record; solo per eventi con un record: collection, date, approval, call o webhook). Un valore o un elenco di massimo 5.
subjecttextsìOggetto (testo o un testo per lingua); segnaposto come in body. Troncato a 200 caratteri.
bodytextsìTesto del messaggio (testo o un testo per lingua), con {record.<field>}, {<field>}, {date}, {app} e blocchi {?name}…{/name}. Viene aggiunto un piè di pagina con il nome e l'indirizzo dell'app; al massimo 20.000 caratteri.
linkstringUna chiave di vista (diventa /v/<key>) o un percorso che inizia con /, aggiunto al testo come link completo all'app (e aperto dalla notifica push).

deliver

object. Invia per email il report di ogni esecuzione completata, pianificata o da istanza di template, come testo semplice (Markdown mantenuto, grafici rimossi): per un template, al proprietario dell'istanza come impostazione predefinita; per una pianificazione, ad admins o a un ruolo. Soggetto agli stessi limiti giornalieri di notify.

ProprietàTipoObbl.PredefinitoDescrizione
channel"email""email"Canale di consegna; solo email (il predefinito).
tostring | lista di stringChi lo riceve: owner (il proprietario dell'istanza; il predefinito), admins, role:<role key>. record.<field> qui viene rifiutato (un report non ha un record). Un valore o un elenco di massimo 5.
subjecttextOggetto. Predefinito: il titolo del report (il suo primo titolo # , altrimenti il nome dell'app). Si possono usare {date} e {title}.
onlyIfNewbooleanfalsetrue: salta l'email quando il report è uguale all'ultimo consegnato per questa pianificazione o istanza. Predefinito false.

recordAction

object. Un pulsante mostrato su ogni record di un elenco di dati (actions di un blocco di dati o dei dati di una vista): chiamata, indicazioni stradali, condivisione o aggiunta al calendario. I pulsanti di chiamata, indicazioni e calendario vengono omessi per un record il cui campo è vuoto o non valido.

ProprietàTipoObbl.PredefinitoDescrizione
typeenumsìcall: compone il numero di telefono in field (mostrato solo se ha almeno 5 cifre). directions: apre un percorso verso l'indirizzo o la posizione "lat,lng" in field (Apple Maps su iPhone, Google Maps altrove). share: apre il pannello di condivisione di sistema con il testo di field (il primo valore di testo del record se non impostato; copiato negli appunti dove la condivisione non è disponibile). calendar: aggiunge un evento da title, start, end e location (il calendario del telefono nell'app per telefono, un file .ics sul web). Valori: call, directions, share, calendar.
labeltextTesto del pulsante (predefinito in base al tipo e alla lingua, ad es. Chiama, Indicazioni, Condividi, Aggiungi al calendario).
fieldstringIl campo del record usato dal pulsante: il numero di telefono (call), l'indirizzo o la posizione (directions), il testo da condividere (share). Un nome puntato legge un campo di un oggetto annidato. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
titlestringcalendar: il campo con il titolo dell'evento (fino a 200 caratteri). Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
startstringcalendar: il campo data o data-ora in cui inizia l'evento. Il pulsante viene mostrato solo quando contiene una data valida; una data senza orario crea un evento di un'intera giornata. Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
endstringcalendar: il campo data o data-ora in cui termina l'evento. Senza di esso l'evento dura un'ora (un giorno per un evento di un'intera giornata). Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.
locationstringcalendar: il campo con il luogo dell'evento (fino a 200 caratteri). Valori: formato ^[A-Za-z_][A-Za-z0-9_]{0,63}(\.[A-Za-z_][A-Za-z0-9_]{0,63})?$.