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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
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. | |
metadata | object | sì | Identità dell'app: slug, nome e testi brevi, lingue e fuso orario. slug e displayName sono obbligatori. | |
metadata.slug | string | sì | 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.displayName | string | sì | 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.tagline | text | Frase 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.description | text | Descrizione estesa dell'app. Accettata dallo schema; non ancora usata dal runtime. | ||
metadata.organizationId | string | integer | Organizzazione 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.langs | lista di lang | Lingue 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.defaultLang | lang | Lingua 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.timezone | string | Fuso 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.referenceOf | string | Solo 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
theme | enum | Tema 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. | ||
palette | palette | I 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. | ||
paletteDark | palette | I 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. | ||
fonts | object | Famiglie 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.body | string | Famiglia di font del testo, ad es. Inter. Predefinito: il font di sistema. | ||
fonts.display | string | Famiglia di font dei titoli e del nome dell'app nell'intestazione. Predefinito: il font del testo. | ||
fonts.mono | string | Famiglia di font monospazio. Il runtime la carica da Google Fonts, ma nessuno stile di pagina la usa ancora. | ||
logo | string | Logo 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. | ||
tokens | mappa di color | Colori 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. | ||
wordmark | lista di object | Il 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[].text | string | sì | Testo di questa parte (al massimo 40 caratteri). Valori: lunghezza max. 40. | |
wordmark[].color | string | Nome 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-]*$. | ||
byline | text | Testo piccolo mostrato dopo il nome nell'intestazione, ad es. by Example Ltd. | ||
button | string | Colore 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-]*$. | ||
width | enum | Larghezza massima del contenuto della pagina: normal (predefinito) = 1080px; wide = 1200px. Valori: normal, wide. | ||
tokensDark | mappa di color | I valori di tokens per il tema scuro (theme: dark, oppure theme: auto su un dispositivo in modalità scura). Applicati solo se paletteDark è impostato. | ||
headingWeight | enum | Peso del font dei titoli (h1–h4): 400, 500, 600, 700, 800 o 900. Predefinito 700. Valori: 400, 500, 600, 700, 800, 900. | ||
headingTracking | enum | Spaziatura tra le lettere dei titoli: normal (predefinito) o tight (lettere leggermente più ravvicinate, -0.02em). Valori: normal, tight. | ||
brandWeight | enum | Peso del font del nome dell'app nell'intestazione: 500, 600, 700, 800 o 900. Predefinito 700. Valori: 500, 600, 700, 800, 900. | ||
buttonShape | enum | Angoli di pulsanti, chip e campo di input della chat: pill (predefinito, completamente arrotondati), rounded (raggio 10px) o square (raggio 4px). Valori: pill, rounded, square. | ||
ghostButton | enum | Stile 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
method | enum | "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. | |
public | boolean | Se 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. | ||
anonymous | object | Che 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.agents | lista di key | Agenti 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.views | lista di key | Pagine 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. | ||
roles | lista di object | I 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[].key | key | sì | Identificatore del ruolo, richiamato altrove (ad es. roles: [admin] su una vista, role:<key> nelle notifiche). | |
roles[].label | text | Nome visualizzato del ruolo. Non ancora mostrato dal runtime. | ||
roles[].assignedBy | enum | Come 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[].from | string | lista di string | Solo 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].action | string | sì | 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). | |
[].per | enum | "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. | |
[].max | integer | sì | Conteggio massimo nella finestra (almeno 1). Per run, agent:<key> e create:<collection>, un piano in plans può aumentarlo. Valori: ≥ 1. | |
[].window | enum | sì | 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. | |
[].roles | lista di key | Si 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. | ||
[].rolling | boolean | Finestra 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. | ||
[].plans | mappa di integer | Un 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | 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. | |
[].role | enum | "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. | |
[].description | string | Che 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>. | ||
[].profile | sì | 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.ref | integer | string | Id 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.inline | object | Una 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. | ||
[].when | string | Condizione 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. | ||
[].goalTemplate | string | Il 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. | ||
[].context | lista di object | Valori 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[].key | string | sì | 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[].from | string | sì | 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. | |
[].variables | mappa di string | Variabili 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. | ||
[].startOptions | object | Campi 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. | ||
[].appTools | lista di appTool | Strumenti 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. | ||
[].output | enum | "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. | |
[].resultSchema | object | JSON Schema della parte strutturata dell'output. Accettato dallo schema; non ancora usato dal runtime. | ||
[].writesTo | object | Trasforma 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.collection | string | sì | 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.parse | enum | "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.keyBy | string | Campo 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. | ||
[].limits | object | Limiti 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.maxTurns | integer | Numero massimo di turni dell'agente (minimo 1). Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 1. | ||
[].limits.maxBudgetUsd | number | Spesa massima di un'esecuzione, in dollari USA. Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0. | ||
[].limits.timeoutSeconds | integer | Durata massima di un'esecuzione, in secondi (minimo 30). Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 30. | ||
[].mcpServers | lista di object | Servizi 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[].name | string | sì | 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[].url | string | sì | L'endpoint MCP del server; deve iniziare con https://. Valori: formato ^https://. | |
[].mcpServers[].headers | mappa di string | Header 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 string | Quali strumenti del server l'agente può usare: all (il predefinito se omesso) o un elenco di nomi di strumenti. | ||
[].delegates | lista di string | Agenti 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. | ||
[].awaits | lista di string | Approvazioni 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. | ||
[].memory | enum | "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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
title | text | Titolo del modulo di esecuzione, mostrato quando la vista new_run non ha un titolo proprio. | ||
fields | lista di field | Campi 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. | ||
examples | lista di object | Input 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
jobs | lista di object | Job 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[].key | key | sì | 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[].description | string | Testo libero per chi legge il manifest. Il runtime non lo mostra né lo usa. | ||
jobs[].projectId | integer | string | Id 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[].jobId | integer | string | Id 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[].pipeline | object | Da 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.ref | integer | string | Nome 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.inline | string | La 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.fromAgent | string | Chiave di un agente destinato a produrre lo YAML della pipeline. Accettato dallo schema; non ancora usato dal runtime. | ||
jobs[].pipeline.runBy | string | Chiave 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.datasetMatch | string | Con runBy: un pattern di nome per trovare il dataset dell'agente. Accettato dallo schema; non ancora usato dal runtime. | ||
jobs[].pipeline.extension | string | Nome di codice personalizzato destinato a comporre la pipeline. Accettato dallo schema; non ancora usato dal runtime. | ||
jobs[].params | object | Variabili 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[].perRecord | string | collection:<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[].schedule | string | Un'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 object | Dove 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.kind | enum | sì | 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.target | string | sì | Nome della raccolta (kind collection) o nome dell'indice di ricerca (kind search). Accettato dallo schema; non ancora usato dal runtime. | |
jobs[].ingestTo.mapping | mappa di string | Mappatura delle colonne nella forma {targetField: sourceColumn}. Accettato dallo schema; non ancora usato dal runtime. | ||
jobs[].ingestTo.keyBy | string | Il 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.incremental | boolean | Indica se a ogni esecuzione verrebbero copiate solo le righe nuove. Accettato dallo schema; non ancora usato dal runtime. | ||
jobs[].ingestTo.retentionDays | integer | Giorni 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. | ||
collections | lista di object | Le 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[].name | key | sì | 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[].description | string | Testo breve mostrato accanto alla raccolta nella pagina dati degli amministratori. | ||
collections[].fields | lista di field | I 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[].ownedBy | enum | "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[].parent | string | Raccolta padre: record pensati per stare sotto un record padre. Accettato dallo schema; non ancora usato dal runtime. | ||
collections[].sharing | lista di enum | Inviti 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[].searchable | boolean | Contrassegna la raccolta per la ricerca. Accettato dallo schema; non ancora usato dal runtime. | ||
collections[].access | lista di object | Regole 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[].role | key | sì | 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[].where | mappa di string | number | boolean | Quali 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[].can | lista 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[].retentionDays | integer | I 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. | ||
credentials | lista di object | Chiavi 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[].provider | string | sì | 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[].label | text | Nome del servizio mostrato nella pagina dell'account (predefinito: provider). | ||
credentials[].kind | enum | Come 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[].url | string | kind mcp: l'indirizzo del server MCP dell'utente. Accettato dallo schema; non ancora usato dal runtime (mcp non è disponibile). | ||
credentials[].allowTools | lista di string | kind mcp: gli strumenti del server MCP dell'utente che gli agenti possono chiamare. Accettato dallo schema; non ancora usato dal runtime. | ||
credentials[].scope | enum | "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[].required | boolean | Indica 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[].help | text | Dove l'utente trova la chiave; mostrato sotto il servizio nella pagina dell'account. | ||
credentials[].hostLabel | text | Se 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | 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. | |
[].type | enum | sì | 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. | |
[].title | text | Titolo della vista e sua etichetta nel menu (stringa semplice o una per lingua). Nel menu, una vista senza titolo mostra la propria chiave. | ||
[].source | string | Da 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. | ||
[].param | string | Accettato dallo schema; non ancora usato dal runtime. | ||
[].query | string | Accettato dallo schema; non ancora usato dal runtime. Usare data.filters per filtrare le righe. | ||
[].columns | lista di string | Forma breve di data.fields: i campi della riga da mostrare come colonne, in ordine, con etichette e formati predefiniti. Ignorato quando data.fields è impostato. | ||
[].children | lista di key | type 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. | ||
[].preview | object | Anteprima 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.rows | integer | Righe mostrate agli utenti senza il piano. Predefinito 3; 0 le nasconde tutte. Valori: ≥ 0. | ||
[].preview.hideColumns | lista di string | Accettato dallo schema; non ancora usato dal runtime. | ||
[].preview.unlessPlan | string | Chiave 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. | ||
[].placement | enum | "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. | |
[].printable | boolean | type report: mostra un pulsante Stampa nella pagina dell'esecuzione completata. Predefinito true. | ||
[].roles | lista di key | Ruoli 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. | ||
[].nav | boolean | true | Indica 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. | |
[].content | text | type page: Markdown mostrato prima delle sections (stringa semplice o una per lingua), visualizzato tramite il renderer Markdown sicuro. | ||
[].sections | lista di section | type page: i blocchi della pagina, visualizzati dall'alto verso il basso dopo content. Vedi section. | ||
[].examples | lista di text | type 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. | ||
[].placeholder | text | type chat: segnaposto della casella del messaggio. Predefinito: "Ask anything…" ("Scrivi la tua domanda…" in italiano). | ||
[].data | object | type 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.path | string | Percorso 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.display | enum | Come 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.fields | lista di object | Le 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[].key | string | sì | 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[].label | text | Intestazione della colonna (stringa semplice o una per lingua). Predefinito: l'etichetta del campo della raccolta su una sorgente collection, altrimenti la chiave. | ||
[].data.fields[].format | enum | Come 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.filters | lista di object | Condizioni 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[].field | string | sì | 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[].op | enum | sì | 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[].value | string | number | boolean | sì | Valore confrontato con il campo: testo, numero o booleano. | |
[].data.sort | object | Ordine 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.field | string | sì | 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.dir | enum | desc (predefinito) o asc. Valori: asc, desc. | ||
[].data.limit | integer | Numero massimo di righe (o gruppi) mostrati, 1–200. Predefinito 50. I numeri chiave (kpis) sono calcolati solo su queste righe. Valori: ≥ 1; ≤ 200. | ||
[].data.kpis | lista di object | display 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[].label | text | sì | Testo sotto il numero (stringa semplice o una per lingua). | |
[].data.kpis[].agg | enum | sì | 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[].field | string | Campo 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[].format | enum | Come 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.empty | text | Messaggio mostrato quando non ci sono righe (non per display kpi). Predefinito: "No data yet." ("Ancora nessun dato." in italiano). | ||
[].data.chart | enum | display 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.groupBy | object | Raggruppa 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.field | string | sì | Campo il cui valore forma il gruppo (percorso puntato). Le righe senza valore vanno in un gruppo chiamato "—". | |
[].data.groupBy.bucket | enum | Tratta 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.aggs | lista di object | sì | Le colonne aggregate di ogni gruppo (al massimo 8). count viene sempre aggiunto. Valori: elementi max. 8. | |
[].data.groupBy.aggs[].key | string | sì | 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[].agg | enum | sì | 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[].field | string | Campo letto dall'aggregato (percorso puntato). Non necessario per count. | ||
[].data.groupBy.minCount | integer | I gruppi con meno righe di questo valore vengono esclusi (1–1000, predefinito 1). Deve essere almeno 5 con acrossUsers. Valori: ≥ 1; ≤ 1000. | ||
[].data.groupBy.acrossUsers | boolean | Su 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.actions | lista di recordAction | Pulsanti 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. | ||
[].approvals | lista di string | type 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. | ||
[].template | string | type 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. | ||
[].collection | string | type 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. | ||
[].fields | lista di string | type 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. | ||
[].edit | boolean | false | type 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. | |
[].submit | object | type form: il pulsante, il messaggio dopo il salvataggio e la pagina da aprire in seguito. | ||
[].submit.label | text | Testo del pulsante di invio. Predefinito: "Send" per un nuovo record, "Save" in modifica (in italiano: "Invia", "Salva"). | ||
[].submit.message | text | Messaggio mostrato dopo il salvataggio. Predefinito: "Saved — thank you." ("Salvato, grazie." in italiano). Non mostrato quando redirect è impostato. | ||
[].submit.redirect | string | Chiave di una vista da aprire dopo il salvataggio (/v/<key>). Deve essere una vista di questa app. | ||
[].export | boolean | false | type 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. | |
[].resources | string | type 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. | ||
[].slots | object | type 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.days | lista di integer | Giorni della settimana aperti alle prenotazioni: 1 = lunedì … 7 = domenica. Predefinito da lunedì a venerdì (1–5). | ||
[].slots.from | string | "09:00" | Orario di apertura, HH:MM in tz. Predefinito 09:00. Deve precedere to. Valori: formato ^\d{2}:\d{2}$. | |
[].slots.to | string | "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.minutes | integer | 30 | Durata di ogni fascia in minuti, 5–480. Predefinito 30. Le fasce iniziano a from e si susseguono senza interruzioni. Valori: ≥ 5; ≤ 480. | |
[].slots.tz | string | "Europe/Rome" | Fuso orario IANA degli orari di apertura (ad es. Europe/London). Predefinito Europe/Rome. | |
[].slots.aheadDays | integer | 14 | Per quanti giorni in avanti, a partire da oggi, vengono offerte le fasce (1–120). Predefinito 14. Valori: ≥ 1; ≤ 120. | |
[].slots.minNoticeHours | number | 2 | Ore minime tra il momento attuale e l'inizio di una fascia perché sia prenotabile (decimali ammessi). Predefinito 2. Valori: ≥ 0. | |
[].slots.capacity | integer | 1 | Prenotazioni ammesse per la stessa fascia (e risorsa), ad es. posti in una lezione (1–100). Predefinito 1. Valori: ≥ 1; ≤ 100. | |
[].map | object | type 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.lat | string | "lat" | Campo con la latitudine (un numero, o testo con decimale a punto o virgola). Predefinito lat. | |
[].map.lon | string | "lon" | Campo con la longitudine. Predefinito lon. | |
[].map.title | string | "name" | Campo mostrato in grassetto nel popup di ciascun segnaposto. Predefinito name. | |
[].map.popup | lista di string | Campi 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.tiles | string | Template 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.attribution | string | Attribuzione 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].agent | string | Chiave 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. | ||
[].job | string | Chiave 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. | ||
[].action | enum | "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. | |
[].cron | string | sì | 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. | |
[].owner | enum | "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. | |
[].goal | string | Il 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}. | ||
[].deliver | deliver | Invia 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
modes | lista di enum | sì | 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. | |
currency | string | "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. | |
platformFeePct | number | Pensato 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. | ||
signupCredits | integer | Crediti che un nuovo utente riceve una sola volta, al primo accesso. Valori: ≥ 0. | ||
metering | object | Impostazioni 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.creditEur | number | Valore di un credito in euro (predefinito 0.01). Crediti addebitati = prezzo in euro diviso per questo valore, arrotondato per eccesso. | ||
metering.markupPct | number | Percentuale aggiunta al costo misurato per ottenere il prezzo (predefinito 50). Valori: ≥ 0. | ||
metering.drivers | lista di enum | Quali 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.allowNegative | boolean | Quando 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. | ||
costs | mappa di number | object | Quanto 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. | ||
packs | lista di object | Acquisti 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[].key | key | sì | 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[].credits | integer | Crediti aggiunti al saldo dell'acquirente al completamento del pagamento (nessuno se 0 o assente). Valori: ≥ 0. | ||
packs[].price | number | sì | Prezzo in unità di billing.currency (ad es. 9.9 = 9,90 EUR), addebitato una sola volta. Valori: ≥ 0. | |
packs[].label | text | Nome del pacchetto mostrato nella vista account e in Checkout (predefinito: key). | ||
packs[].unlocks | lista di string | Valori di opzione o viste che un pacchetto dovrebbe sbloccare. Accettato dallo schema; non ancora usato dal runtime. | ||
plans | lista di object | Abbonamenti. 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[].key | key | sì | 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[].price | number | sì | Prezzo per interval in unità di billing.currency. Valori: ≥ 0. | |
plans[].interval | enum | sì | Con quale frequenza viene fatturato l'abbonamento: month o year. Valori: month, year. | |
plans[].label | text | Nome del piano mostrato nella vista account e in Checkout (predefinito: key). | ||
plans[].includes | lista di string | Che cosa include il piano. Accettato dallo schema; non ancora usato dal runtime (non mostrato nella vista account). | ||
plans[].credits | integer | Crediti aggiunti al saldo dell'abbonato a ogni fattura pagata (ogni periodo di fatturazione). I crediti non spesi vengono conservati. Valori: ≥ 0. | ||
plans[].creditsReset | enum | monthly: 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[].transactionFeePct | number | per_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[].roles | lista di key | Ruoli a cui dovrebbe essere consentito acquistare il piano. Accettato dallo schema; non ancora usato dal runtime: ogni utente autenticato può abbonarsi. | ||
transactionFeePct | number | per_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. | ||
sellers | string | per_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. | ||
revenueShare | lista di object | Pagamenti a terzi. Accettato dallo schema; non ancora usato dal runtime (la validazione verifica che to indichi una raccolta dichiarata). | ||
revenueShare[].to | string | sì | collection:<name>: i record che verrebbero pagati. La validazione verifica che la raccolta sia dichiarata; non ancora usato dal runtime. | |
revenueShare[].pct | number | sì | Percentuale (da 0 a 100) di basis che verrebbe pagata. Non ancora usato dal runtime. Valori: ≥ 0; ≤ 100. | |
revenueShare[].basis | string | sì | 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[].payout | enum | "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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
emailOnRunDone | boolean | Invia 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. | ||
digest | string | Cron 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].path | string | sì | Percorso URL dell'endpoint, che inizia con /api/. Non ancora usato dal runtime. Valori: formato ^/api/. | |
[].source | string | sì | Dati che l'endpoint servirebbe. Non ancora usato dal runtime. | |
[].format | enum | "json" | Formato di output: json (predefinito), csv, xml o rss. Non ancora usato dal runtime. Valori: json, csv, xml, rss. | |
[].access | enum | "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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
appId | string | sì | 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,}$. | |
appName | string | Nome sotto l'icona sul telefono (al massimo 30 caratteri). Predefinito: displayName. Valori: lunghezza max. 30. | ||
version | string | Versione mostrata negli store, x.y.z. Predefinito 1.0.0. Valori: formato ^\d+\.\d+\.\d+$. | ||
build | integer | Numero 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. | ||
orientation | enum | "portrait" | Orientamento dello schermo: portrait (predefinito) blocca l'app in verticale; any segue la rotazione del telefono. Valori: portrait, any. | |
capabilities | lista di object | Funzionalità 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[].name | enum | sì | 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[].reason | text | Perché 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. | ||
allowNavigation | lista di string | Altri 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Identificatore dell'estensione. | |
[].description | string | sì | Che cosa fa la logica personalizzata. | |
[].where | string | Dove 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
links | lista di object | Link 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[].label | text | sì | Testo del link. | |
links[].href | string | sì | Destinazione: un percorso di questa app (/…), un'ancora nella pagina (#…) o un URL https://. Valori: formato ^(/(?!/)|#|https://). | |
cta | object | Pulsante di invito all'azione mostrato ai visitatori che non hanno effettuato l'accesso, al posto del pulsante di accesso. | ||
cta.label | text | sì | Testo del pulsante. | |
cta.href | string | sì | Destinazione: un percorso di questa app (/…, ad es. /login), un'ancora (#…) o un URL https://. Valori: formato ^(/(?!/)|#|https://). | |
announcement | text | Una 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Chiave univoca dello slot, richiamata da context[].from: slot:<key> e appTools[].slot. | |
[].description | string | Che cosa calcola lo slot, al massimo 300 caratteri. Per chi legge il manifest; il runtime non lo usa. Valori: lunghezza max. 300. | ||
[].code | string | sì | 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. | |
[].timeoutMs | integer | 3000 | Limite di tempo reale di una chiamata, in millisecondi: da 100 a 10.000, predefinito 3000. Valori: ≥ 100; ≤ 10000. | |
[].example | Un 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
timezone | string | Fuso orario IANA delle fasce, ad es. Europe/Rome. Predefinito: metadata.timezone, altrimenti Europe/Rome. | ||
leadMinutes | integer | 10 | Minuti 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. | |
slots | lista di object | sì | 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[].days | lista di integer | sì | 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[].from | string | sì | Orario di apertura, HH:MM (24 ore, locale), incluso. Valori: formato ^([01][0-9]|2[0-3]):[0-5][0-9]$. | |
slots[].to | string | sì | 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Chiave univoca del team, richiamata da triggers[].start.team e templates[].team. Non può coincidere con la chiave di un agente. | |
[].description | string | Che cosa fa il team. La pubblicazione la usa come descrizione del profilo (predefinito <displayName> — team <key>). | ||
[].title | text | Titolo visualizzato del team. Accettato dallo schema; non ancora usato dal runtime. | ||
[].mode | enum | sì | 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. | |
[].steps | lista di object | mode 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[].agent | string | sì | Chiave dell'agente che esegue questo passaggio (deve essere inline). | |
[].steps[].after | lista di string | I passaggi (chiavi di agente) che questo attende. Predefinito: il passaggio precedente; il primo passaggio non ne ha. | ||
[].lead | string | mode swarm: l'agente che pianifica e chiude il lavoro (obbligatorio per uno swarm). | ||
[].members | lista di string | mode swarm: gli agenti sulla bacheca (almeno uno). | ||
[].maxMinutes | integer | Limite di tempo di uno swarm, in minuti (1–180), passato allo swarm come durata massima. Ignorato per i team sequence. Valori: ≥ 1; ≤ 180. | ||
[].goalTemplate | string | Il 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. | ||
[].writesTo | object | Come 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). | ||
[].profile | object | Impostato dalla pubblicazione: il profilo compilato dal team. Non scriverlo a mano. | ||
[].profile.ref | integer | string | Id 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Chiave univoca del trigger. Un trigger webhook viene chiamato su POST /api/hooks/<key>. | |
[].description | string | A che cosa serve il trigger. Per chi legge il manifest; il runtime non lo usa. | ||
[].on | object | sì | 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.cron | string | Un 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.collection | string | Una 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.op | enum | "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.where | object | Campi 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.webhook | boolean | true: 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.payment | string | Una chiave di piano o di pacchetto, o * per qualsiasi acquisto: scatta una volta per ogni acquisto completato, per l'utente che ha pagato. | ||
[].on.approval | string | Chiave 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.decision | enum | "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.call | string | Chiave 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.callEvent | enum | "ended" | Quale momento di una chiamata lo attiva: started, ended (predefinito) o missed. Solo con call. Valori: started, ended, missed. | |
[].on.date | object | Promemoria: 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.collection | string | sì | La raccolta dichiarata i cui record vengono verificati. | |
[].on.date.field | string | sì | 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.offsetDays | integer | 0 | Giorni 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.hour | integer | 7 | Ora del giorno (UTC, 0–23) a partire dalla quale vengono inviati i promemoria del giorno; predefinito 7. Valori: ≥ 0; ≤ 23. | |
[].start | object | Avvia 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.agent | string | Chiave 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.team | string | Chiave del team da avviare (deve essere pubblicato). | ||
[].start.job | string | Chiave di un job di dati collegato in spec.data.jobs da eseguire. | ||
[].goal | string | Il 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. | ||
[].asUser | boolean | true | true (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. | |
[].notify | notify | Invia un'email in testo semplice invece di avviare un agente (vedi $defs/notify). | ||
[].write | object | Salva 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.collection | string | sì | La raccolta dichiarata in cui viene scritto il record. | |
[].write.fields | mappa di string | Mappatura 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.keyBy | string | Un 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. | ||
[].charge | object | Preleva 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.credits | integer | sì | Crediti prelevati, da 1 a 100.000. Valori: ≥ 1; ≤ 100000. | |
[].charge.reason | string | Testo 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Chiave univoca dell'approvazione, richiamata da agents[].awaits, triggers[].on.approval e views[].approvals; lo strumento generato è request_<key> (i trattini diventano trattini bassi). | |
[].title | text | Etichetta della richiesta mostrata nella vista delle approvazioni. Predefinito: la chiave. | ||
[].description | string | Che cosa viene approvato; entra nella descrizione dello strumento request_<key> che l'agente vede. | ||
[].role | string | Il 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. | ||
[].fields | lista di string | Campi della richiesta mostrati alla persona che decide. Predefinito: tutti i campi della richiesta. | ||
[].timeoutMinutes | integer | Minuti 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. | ||
[].onTimeout | enum | "reject" | La decisione alla scadenza: reject (predefinito) o approve. La decisione viene registrata come approved o rejected, presa da timeout. Valori: approve, reject. | |
[].decidedBy | enum | "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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | sì | Chiave univoca del template, richiamata da una vista instances (template). | |
[].title | text | Titolo della vista delle istanze per questo template. Predefinito: la chiave. | ||
[].description | text | Testo mostrato sotto il titolo della vista delle istanze. | ||
[].agent | string | Chiave dell'agente eseguito da ogni istanza. Esattamente uno tra agent e team. | ||
[].team | string | Chiave del team eseguito da ogni istanza. Esattamente uno tra agent e team. | ||
[].params | lista di field | sì | 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. | |
[].schedule | object | Quando le istanze vengono eseguite autonomamente. Senza un cron un'istanza viene eseguita solo quando il suo proprietario preme Esegui. | ||
[].schedule.cron | string | Cron UTC a 5 campi predefinito di una nuova istanza. Un cron fornito dall'utente può contenere solo cifre, spazi e * , / -. | ||
[].schedule.userCanChange | boolean | true | true (predefinito): l'utente può impostare il proprio cron quando crea o modifica un'istanza. false: ogni istanza usa cron. | |
[].maxPerUser | integer | 5 | Quante istanze (attive o in pausa) può avere un utente: da 1 a 1000, predefinito 5. Valori: ≥ 1; ≤ 1000. | |
[].roles | lista di string | Ruoli autorizzati a creare istanze. Predefinito: tutti gli utenti autenticati; gli amministratori dell'app possono sempre. | ||
[].cost | object | Crediti addebitati all'utente proprietario dell'istanza. | ||
[].cost.perRun | number | Crediti 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.perMonth | number | Crediti mensili per istanza. Accettato dallo schema; non ancora usato dal runtime. Valori: ≥ 0. | ||
[].goal | string | Il 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. | ||
[].deliver | deliver | Invia 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
[].key | key | Chiave del canale, richiamata da triggers[].on.call. Predefinito: il tipo del canale. | ||
[].type | enum | sì | web (le viste chat dell'app), phone, telegram o email. Valori: web, phone, telegram, email. | |
[].agent | string | sì | Chiave dell'agente che risponde su questo canale (deve esistere). | |
[].greeting | text | Primo messaggio al chiamante o visitatore. Accettato dallo schema; non ancora usato dal runtime. | ||
[].language | string | Lingua della conversazione. Accettato dallo schema; non ancora usato dal runtime. | ||
[].voice | string | Voce di un canale telefonico. Accettato dallo schema; non ancora usato dal runtime. | ||
[].number | string | phone: il numero, impostato quando il telefono viene attivato. Accettato dallo schema; non ancora usato dal runtime. | ||
[].address | string | email: 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
hosts | lista di string | sì | 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. | |
notes | string | Perché 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
primary | color | Titoli, nome dell'app nell'intestazione, striscia di annuncio e segnaposti numerati. Predefinito #1f2a44. | ||
accent | color | Link, pulsanti principali (a meno che branding.button indichi un altro colore), evidenziazioni e serie dei grafici. Predefinito #2563eb. | ||
background | color | Sfondo della pagina; card e linee ne derivano. Predefinito #f7f8fa. | ||
foreground | color | Colore 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
value | string | sì | Il valore salvato e passato all'agente. | |
label | text | Ciò che vede la persona; predefinito: il valore. In un modulo di esecuzione l'etichetta scelta è disponibile anche nel goal come {<field>_label}. | ||
gatedBy | string | Chiave 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. | ||
parent | string | Con 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
name | string | sì | 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_]*$. | |
label | text | Testo mostrato accanto al campo (predefinito: name); usato anche nei messaggi di errore e per abbinare le intestazioni delle colonne CSV nella pagina dati. | ||
type | enum | sì | 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. | |
required | boolean | Il 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. | ||
maxLength | integer | Numero 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. | ||
options | lista di option | Le 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. | ||
optionsFrom | string | collection:<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. | ||
dependsOn | string | Nome 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. | ||
visibleWhen | string | Mostra 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. | ||
roles | lista di string | Solo 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. | ||
default | Il 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. | |||
help | text | Suggerimento 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. | ||
gatedBy | string | Chiave 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. | ||
fields | lista di field | type 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. | ||
relation | string | type relation: la raccolta di destinazione. Accettato dallo schema; non ancora usato dal runtime: per scegliere un record, impostare optionsFrom: collection:<name>. | ||
accept | lista di enum | type 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. | ||
maxMb | number | type 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. | ||
multiple | boolean | false | type file: consente fino a 10 file invece di uno (predefinito false). Il valore è allora un elenco di id di file. | |
extract | enum | "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. | |
capture | boolean | type 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
name | string | sì | 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_]*$. | |
description | string | sì | 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. | |
action | enum | sì | 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. | |
collection | string | La 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. | ||
scope | string | user 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. | ||
extension | string | Chiave 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. | ||
slot | string | action 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. | ||
agent | string | L'agente delegato di uno strumento delegate generato (ask_<agent>). Impostato dal runtime a partire da delegates; dichiarare invece delegates. | ||
approval | string | L'approvazione di uno strumento approval generato (request_<approval>). Impostato dal runtime a partire da awaits; dichiarare invece awaits. | ||
http | object | action 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.method | enum | "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.url | string | sì | 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.allowPath | boolean | false | Consente 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.headers | mappa di string | Header 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.timeoutMs | integer | 20000 | Timeout della richiesta in millisecondi: da 1000 a 30.000, predefinito 20.000. Valori: ≥ 1000; ≤ 30000. | |
http.maxBytes | integer | 500000 | Dimensione 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.attribution | string | Licenza 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.credential | object | Una 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.provider | string | sì | Il provider di una credenziale api_key dichiarata in spec.data.credentials. | |
http.credential.header | string | Header 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.format | string | Come 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.query | string | Invia 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
type | "hero" | sì | Tipo di blocco; sempre hero per questo tipo di blocco. | |
id | string | Ancora 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-]*$. | ||
eyebrow | text | Riga breve sopra il titolo (una riga di Markdown). | ||
title | text | sì | Il titolo principale (una riga di Markdown, obbligatorio). Le parole in grassetto vengono mostrate evidenziate. | |
text | text | Testo introduttivo sotto il titolo (Markdown). In un hero split senza aside riempie la colonna destra. | ||
actions | lista di object | Pulsanti sotto il testo, in ordine. Un pulsante verso la pagina di accesso (/login…) viene nascosto agli utenti che hanno già effettuato l'accesso. | ||
actions[].label | text | sì | Testo del pulsante (stringa semplice o una per lingua). | |
actions[].href | string | sì | Link: un percorso della stessa app (/v/…), un'ancora (#…) o un URL https. Qualsiasi altro valore diventa "#". Valori: formato ^(/(?!/)|#|https://). | |
actions[].style | enum | primary (predefinito): un pulsante pieno; ghost: un pulsante con solo il bordo. Valori: primary, ghost. | ||
note | text | Riga piccola sotto i pulsanti, ad es. una riga di fiducia o che cosa è incluso (una riga di Markdown). | ||
layout | enum | stack (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. | ||
aside | text | Colonna 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. | ||
band | boolean | Mostra l'hero su una fascia colorata a tutta larghezza. Predefinito false. | ||
eyebrowStyle | enum | La 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. | ||
type | enum | sì | steps: elementi numerati in ordine (come funziona); cards: elementi senza numeri (funzionalità, piani, casi d'uso). Valori: steps, cards. | |
id | string | Ancora 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-]*$. | ||
title | text | Titolo del blocco (una riga di Markdown). | ||
intro | text | Testo sotto il titolo, prima degli elementi (Markdown). | ||
items | lista di object | sì | Gli elementi della griglia (almeno uno). Valori: elementi min. 1. | |
items[].title | text | Titolo dell'elemento (una riga di Markdown). | ||
items[].text | text | Testo dell'elemento (Markdown). | ||
items[].badge | text | Mostrato 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. | |
id | string | Ancora 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-]*$. | ||
title | text | Titolo del blocco (una riga di Markdown). | ||
content | text | sì | Corpo del blocco, in Markdown (obbligatorio). | |
type | "note" | sì | Tipo di blocco; sempre note per questo tipo di blocco. | |
id | string | Ancora 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-]*$. | ||
content | text | sì | Testo della nota, in Markdown (obbligatorio). | |
type | "html" | sì | Tipo di blocco; sempre html per questo tipo di blocco. | |
id | string | Ancora 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-]*$. | ||
html | text | sì | 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. | |
id | string | Ancora del blocco (lettere minuscole, cifre e -), per link come #book. Valori: formato ^[a-z0-9][a-z0-9-]*$. | ||
title | text | Titolo mostrato sopra la vista incorporata. | ||
view | key | sì | 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. | |
id | string | Ancora 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-]*$. | ||
title | text | Titolo del blocco (testo semplice, il Markdown non viene interpretato). | ||
intro | text | Testo sotto il titolo (testo semplice, il Markdown non viene interpretato). | ||
source | string | sì | 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_]+)$. | |
path | string | Percorso 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})?$. | ||
display | enum | sì | 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. | |
fields | lista di object | Le 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[].key | string | sì | 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[].label | text | Intestazione della colonna (stringa semplice o una per lingua). Predefinito: l'etichetta del campo della raccolta su una sorgente collection, altrimenti la chiave. | ||
fields[].format | enum | Come 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. | ||
filters | lista di object | Condizioni 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[].field | string | sì | 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[].op | enum | sì | 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[].value | string | number | boolean | sì | Valore confrontato con il campo: testo, numero o booleano. | |
sort | object | Ordine 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.field | string | sì | 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.dir | enum | desc (predefinito) o asc. Valori: asc, desc. | ||
limit | integer | Numero massimo di righe (o gruppi) mostrati, 1–200. Predefinito 50. I numeri chiave (kpis) sono calcolati solo su queste righe. Valori: ≥ 1; ≤ 200. | ||
kpis | lista di object | display 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[].label | text | sì | Testo sotto il numero (stringa semplice o una per lingua). | |
kpis[].agg | enum | sì | 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[].field | string | Campo 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[].format | enum | Come 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. | ||
empty | text | Messaggio mostrato quando non ci sono righe (non per display kpi). Predefinito: "No data yet." ("Ancora nessun dato." in italiano). | ||
preview | object | Anteprima 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.rows | integer | Righe mostrate agli utenti senza il piano. Predefinito 3; 0 le nasconde tutte. Valori: ≥ 0. | ||
preview.unlessPlan | string | Chiave 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. | ||
chart | enum | display 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. | ||
groupBy | object | Raggruppa 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.field | string | sì | Campo il cui valore forma il gruppo (percorso puntato). Le righe senza valore vanno in un gruppo chiamato "—". | |
groupBy.bucket | enum | Tratta 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.aggs | lista di object | sì | Le colonne aggregate di ogni gruppo (al massimo 8). count viene sempre aggiunto. Valori: elementi max. 8. | |
groupBy.aggs[].key | string | sì | 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[].agg | enum | sì | 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[].field | string | Campo letto dall'aggregato (percorso puntato). Non necessario per count. | ||
groupBy.minCount | integer | I gruppi con meno righe di questo valore vengono esclusi (1–1000, predefinito 1). Deve essere almeno 5 con acrossUsers. Valori: ≥ 1; ≤ 1000. | ||
groupBy.acrossUsers | boolean | Su 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. | ||
actions | lista di recordAction | Pulsanti 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
channel | "email" | "email" | Canale di consegna; solo email (il predefinito). | |
to | string | lista di string | sì | 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. | |
subject | text | sì | Oggetto (testo o un testo per lingua); segnaposto come in body. Troncato a 200 caratteri. | |
body | text | sì | 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. | |
link | string | Una 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
channel | "email" | "email" | Canale di consegna; solo email (il predefinito). | |
to | string | lista di string | Chi 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. | ||
subject | text | Oggetto. Predefinito: il titolo del report (il suo primo titolo # , altrimenti il nome dell'app). Si possono usare {date} e {title}. | ||
onlyIfNew | boolean | false | true: 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à | Tipo | Obbl. | Predefinito | Descrizione |
|---|---|---|---|---|
type | enum | sì | 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. | |
label | text | Testo del pulsante (predefinito in base al tipo e alla lingua, ad es. Chiama, Indicazioni, Condividi, Aggiungi al calendario). | ||
field | string | Il 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})?$. | ||
title | string | calendar: 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})?$. | ||
start | string | calendar: 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})?$. | ||
end | string | calendar: 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})?$. | ||
location | string | calendar: 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})?$. |