WebRobot
App Builder · pagine

Documentazione · App Builder

Come il runtime serve un’app

Ogni app pubblicata è servita dallo stesso runtime. Il runtime legge il manifest dell’app e fa quello che dice: mostra le pagine, gestisce l’accesso degli utenti, conserva i dati, avvia gli agenti, esegue le pianificazioni e riceve i pagamenti. Sul server non c’è codice tuo. Questa pagina spiega cosa succede e su cosa puoi contare.

Indirizzi

Il runtime sceglie l’app in base all’indirizzo a cui arriva la richiesta.

IndirizzoServe
<slug>.webrobot.euL’app pubblicata.
preview-<slug>.webrobot.euLa bozza salvata (l’anteprima di App Studio).
Un dominio in spec.domainsL’app pubblicata, sul tuo dominio.
spec.hostL’app pubblicata, su quell’host.
  • Un’app con un dominio personalizzato risponde comunque su <slug>.webrobot.eu.
  • Per un dominio in spec.domains, crea un record DNS CNAME che lo punti a <slug>.webrobot.eu, poi pubblica. La pubblicazione instrada il dominio verso il runtime.
  • Un host o un dominio può appartenere a una sola app. La pubblicazione rifiuta un host usato da un’altra app: "host <host> is already used by another app".
  • I link che l’app costruisce (link di accesso, pagine di ritorno da Stripe, email) usano l’indirizzo dell’app stessa, mai l’indirizzo da cui una richiesta dichiara di provenire. Fuori dallo sviluppo locale l’app è servita solo in HTTPS.

L’indirizzo di anteprima non è pubblico. Si apre con il token che App Studio fornisce quando premi Open preview (apri anteprima), valido al massimo un giorno, oppure per un amministratore dell’app che ha effettuato l’accesso. Altrimenti mostra la pagina di accesso.

Dalla richiesta alla pagina

  1. L’app. Il runtime cerca l’app per l’indirizzo e legge il suo manifest pubblicato (la bozza, sull’indirizzo di anteprima). Il manifest viene validato di nuovo: uno non valido non viene servito. Una nuova pubblicazione è online entro circa 30 secondi.
  2. La lingua. Vedi Lingue.
  3. L’utente. Il cookie di sessione, se c’è, dice chi ha effettuato l’accesso. Il ruolo dell’utente viene dal manifest a ogni richiesta (vedi Accesso e utenti).
  4. La pagina. / mostra la vista con chiave home quando l’utente può vederla, altrimenti la prima vista del menu che può aprire, altrimenti la pagina di accesso. /v/<key> mostra una vista; un visitatore che non può vederla viene mandato all’accesso. /r/<id> mostra un’esecuzione.
  5. Azioni. Le azioni del browser (un modulo, un’esecuzione, un messaggio in chat, un acquisto) vanno all’API dell’app sotto /api/…, con i controlli descritti in Sicurezza.

Quando su un indirizzo non è pubblicata nessuna app, le pagine dicono "No app is published on this address." e l’API risponde 404 {"error": "no app on this host"}.

Dati

Ogni app ha il suo archivio di documenti. Ogni record appartiene a un’app e a una raccolta, e ha un id. L’archivio conserva anche i dati propri del runtime per l’app: utenti, sessioni, token di accesso, registro dei crediti, esecuzioni, chat, approvazioni, istanze, file, outbox, credenziali e pochi altri. Un manifest non può dichiararli, mostrarli o darci uno strumento sopra: i loro nomi sono riservati (vedi Validazione).

Cosa tiene separati i dati:

  • Tra app. Un’app legge e scrive solo nel proprio archivio. Due app della stessa organizzazione non condividono nulla.
  • Tra organizzazioni. Gli agenti di ogni app girano sulla piattaforma con la chiave API dell’app, che appartiene all’organizzazione dell’app.
  • Anteprima e app pubblicata. L’anteprima ha il proprio archivio e i propri utenti. Esecuzioni, record e pagamenti fatti nell’anteprima non toccano mai i dati dell’app pubblicata.
  • Tra utenti. Chi legge e scrive quale record segue il proprietario della raccolta (user, instance, app, shared, org) e le sue regole di accesso, allo stesso modo in viste, moduli, strumenti degli agenti e contesto degli agenti. Vedi Dati.

Conservazione. Una raccolta con retentionDays perde i record più vecchi una volta al giorno (in base a createdAt).

Il pianificatore

Ogni pochi minuti un ciclo del pianificatore passa su ogni app pubblicata che ha pianificazioni, trigger, approvazioni, modelli, emailOnRunDone o una conservazione. Un ciclo:

  1. avvia le pianificazioni in scadenza (vedi Pianificazioni);
  2. esegue i trigger a tempo (on.cron) e a data (on.date);
  3. controlla le esecuzioni da modulo che nessuno sta seguendo, quando notifications.emailOnRunDone è attivo;
  4. esegue le istanze dei modelli in scadenza;
  5. cancella i record oltre la conservazione (una volta al giorno);
  6. decide le approvazioni oltre il timeout;
  7. raccoglie le esecuzioni pianificate e avviate da trigger che sono terminate: il loro risultato diventa un record di writesTo, il report viene consegnato, l’istanza viene aggiornata.

Dopo una pausa, il pianificatore recupera al massimo le ultime 3 ore, così un’interruzione non rieseguirà un’intera giornata. Le espressioni cron sono in UTC.

Agenti sulla piattaforma

Il runtime non esegue modelli da sé. Avvia ogni agente sulla piattaforma WebRobot, con la chiave API dell’app, e lo segue fino alla fine.

  • Strumenti dell’app. Un agente con strumenti dell’app li chiama sull’endpoint MCP dell’app (/api/mcp). La pubblicazione dà a ogni agente un proprio indirizzo e token: l’agente vede e chiama solo i propri strumenti. Un’app pubblicata prima dell’introduzione dei token per agente mantiene un unico token per tutti i suoi strumenti finché non viene pubblicata di nuovo.
  • La sessione dell’app. Il runtime mette una sessione di breve durata (3 ore) nel compito dell’agente. L’agente la passa agli strumenti, e il runtime la riconduce all’utente per cui si sta lavorando. È così che uno strumento raggiunge solo i record di quell’utente, anche se un utente chiede all’agente quelli di qualcun altro.
  • Chiavi degli utenti. Una chiave che un utente ha collegato (per uno strumento http) è cifrata a riposo, legata all’app e all’utente, e aggiunta alla richiesta dal runtime. L’agente non la vede mai.
  • Servizi esterni. Gli strumenti http raggiungono solo gli host in spec.egress.hosts, con le protezioni descritte in Egress.
  • Slot. Gli slot Python girano in una sandbox WebAssembly, mai nel runtime.

Gli strumenti dell’app non sono serviti sull’indirizzo di anteprima.

Limiti di frequenza

Alcuni limiti sono fissati dal runtime, qualunque cosa dica il manifest.

CosaLimite
Email di accesso richieste10 all’ora per indirizzo IP; 3 all’ora per indirizzo email (le richieste in più ricevono la stessa risposta, senza email); un tetto orario per app
Codici di accesso digitati20 all’ora per indirizzo IP
Messaggi in chat30 all’ora per utente, 60 all’ora per indirizzo IP
Moduli inviati da visitatori (senza accesso)5 all’ora per indirizzo IP e modulo
Azioni avviate da trigger20 al minuto per app
Email300 al giorno per app, 10 al giorno per destinatario
Notifiche push20 al giorno per utente
Una risposta alla voltaper conversazione in chat

I contatori di accesso, chat e trigger sono tenuti da ogni istanza del runtime. Le tue quote vanno in spec.limits: vedi Pagamenti e crediti.

Sicurezza

Il manifest è scritto da persone e dall’agente builder a partire da testo libero. Il runtime lo tratta come input non fidato, come qualsiasi cosa inviino gli utenti.

Pagine e contenuti

  • I colori devono essere #rrggbb; gli altri valori vengono scartati.
  • I font devono essere nomi semplici (lettere, cifre e spazi, fino a 41 caratteri); vengono caricati da Google Fonts.
  • Logo. Un logo SVG viene ripulito secondo un elenco consentito di elementi e attributi di disegno: niente script, stili, animazioni, link, immagini esterne o url() al di fuori del logo stesso; al massimo 20.000 caratteri. Viene mostrato come immagine, dove il browser non esegue script. L’URL di un logo deve essere https://.
  • I blocchi HTML delle pagine vengono ripuliti secondo un elenco consentito di tag di layout e di testo. Script, gestori di eventi, form, iframe e link non https non sopravvivono mai; lo stile inline conserva solo proprietà di layout e colore, mai url(). I link ad altri siti si aprono in una nuova scheda, senza accesso alla pagina dell’app.
  • Il Markdown (report, risposte della chat, testi delle pagine) viene prima sottoposto a escape e poi visualizzato: titoli, elenchi, tabelle, grassetto e corsivo, codice, link https e percorsi della stessa app, e grafici. Nessun HTML proveniente da un agente arriva alla pagina.
  • I link nel manifest devono essere percorsi della stessa app, #anchors o https://; qualsiasi altra cosa diventa #.

Accesso e sessioni

  • L’accesso avviene via email: un link valido 15 minuti e utilizzabile una sola volta, e un codice di 6 cifre che scade dopo 5 tentativi sbagliati.
  • L’email di accesso è un testo fisso della piattaforma "sent by WebRobot on behalf of the app". Cambia solo il nome dell’app, ripulito in una sola riga di al massimo 60 caratteri senza link o indirizzi.
  • Il cookie di sessione è HttpOnly, SameSite=Lax, Secure, valido 30 giorni, e firmato per una sola app: una sessione di un’app non ne apre mai un’altra, anche se tutte le app stanno sotto webrobot.eu.
  • Dopo l’accesso, l’utente viene rimandato solo a un percorso della stessa app.

Richieste che modificano qualcosa

Tutte le app condividono il sito webrobot.eu, quindi il runtime non si affida solo ai cookie. Ogni richiesta che modifica qualcosa deve:

  • inviare un corpo JSON (Content-Type: application/json), oppure, per il caricamento di un file, multipart/form-data con l’header X-VK-Upload: 1; altrimenti 415;
  • provenire dall’origine dell’app stessa (header Origin); altrimenti 403 "cross-origin request refused".

Una pagina di un’altra app, o di qualsiasi altro sito, non può agire per conto di un utente che ha effettuato l’accesso.

File

  • Un campo file accetta le estensioni che elenca (predefinite: pdf, docx, xlsx, csv, txt, jpg, jpeg, png, webp), fino al suo maxMb (predefinito 10 MB, mai più di 15 MB).
  • Il contenuto deve corrispondere all’estensione: un file rinominato viene rifiutato ("the file is not a valid pdf").
  • I nomi dei file vengono ripuliti. Dai file PDF, Word, Excel, CSV e di testo viene estratto il testo per l’obiettivo dell’agente.
  • Un file è leggibile solo dall’utente che l’ha caricato e dagli amministratori dell’app. Viene scaricato come allegato, mai mostrato nella pagina.

Webhook e pagamenti

  • Un webhook richiede il segreto del suo trigger; un corpo firmato viene controllato contro manomissioni e riutilizzi (vedi Trigger).
  • Le notifiche di Stripe sono verificate con la firma di Stripe, e ogni sessione di Checkout viene riletta da Stripe prima di aggiungere crediti. I prezzi vengono dal manifest pubblicato, mai dal browser.

Errori

L’API risponde agli errori in JSON con uno stato HTTP:

{ "error": "not enough credits", "needed": 20, "balance": 5 }
StatoSignificato tipico
400Un valore manca o è sbagliato ("Email is required", "invalid choice …").
401Prima effettua l’accesso.
402Crediti insufficienti, o serve un piano. Con un errore sui crediti arrivano needed e balance.
403Non consentito per questo utente o ruolo.
404Record, vista o app inesistente.
409Non possibile ora ("publish the app first", "the assistant is still answering", "already decided").
413, 415Un file o un corpo troppo grande, o di tipo sbagliato.
429È stato raggiunto un limite.

Un tipo di vista che il runtime non visualizza ancora mostra "This view is not rendered by the runtime yet" invece di andare in errore.

Agenti che non sono partiti. Quando l’app avvia un agente da sola (un trigger, la decisione di un’approvazione, una data) e la piattaforma lo rifiuta, o un limite lo blocca, il motivo viene conservato per gli amministratori dell’app. Lo vedono in cima alla pagina dei dati (/admin/data), con l’agente, cosa l’ha avviato e quando. Il motivo più comune, la mancanza di un provider di AI nell’organizzazione, è accompagnato da cosa fare. Gli avvii da pianificazioni e da istanze di modelli non sono elencati lì.

Lingue

  • metadata.langs elenca le lingue dell’app (codici di due lettere); metadata.defaultLang è quella predefinita.
  • La lingua di una pagina è quella scelta dall’utente, altrimenti la prima richiesta dal suo browser, altrimenti quella predefinita. Una lingua che l’app non dichiara non viene mai usata.
  • Il selettore di lingua (/lang?l=<code>) ricorda la scelta per un anno e torna alla pagina in cui l’utente si trovava.
  • Ogni testo del manifest può essere una stringa o una stringa per lingua ({en: "…", it: "…"}). Una lingua mancante ripiega sulla prima indicata.
  • Le parole proprie del runtime (pulsanti, accesso, messaggi) esistono in inglese e in italiano; le altre lingue usano l’inglese.

Stato del servizio

GET /api/health risponde {"ok": true, …} finché il runtime è attivo.