Documentazione · App Builder
Messaggi ed egress
Un’app raggiunge le persone via email e, quando ha un’app per telefono, con notifiche push. I suoi agenti raggiungono il mondo esterno solo attraverso gli host esterni elencati nel manifest. Questa pagina spiega entrambe le cose, e dice chiaramente cosa non è ancora disponibile.
Notifiche
Ogni email che un’app invia è in testo semplice, spedita tramite il servizio email della piattaforma. Ci sono quattro punti che ne inviano una:
| Dove | Invia |
|---|---|
triggers[].notify | Un’email quando succede un evento: un record salvato, una data raggiunta, un’approvazione decisa, un acquisto, un webhook, un timer. |
schedules[].deliver | Il report di un’esecuzione pianificata di un agente. |
templates[].deliver | Il report di ogni esecuzione di un’istanza di un modello. |
notifications.emailOnRunDone | Un’email all’utente quando la sua esecuzione da modulo termina. |
Il notify di un trigger
Un trigger con notify invia un’email invece di avviare un agente.
triggers:
- key: new_booking
on: { collection: bookings, op: insert }
notify:
to: [admins, record.email]
subject: "New booking: {record.name} on {record.date}"
body: |-
{record.name} booked for {record.guests} people on {record.date}.
Phone: {record.phone}
link: bookings
| Campo | Significato |
|---|---|
to | Un destinatario o un elenco di massimo 5. Vedi Destinatari. |
subject, body | Testo, o un testo per lingua. Possono usare i campi del record come {record.<field>} o {<field>}, più {date} e {app} (il nome dell’app). Funzionano anche i blocchi {?x}…{/x} dei modelli di obiettivo. |
link | La chiave di una vista (diventa /v/<key>) o un percorso che inizia con /. L’indirizzo completo viene aggiunto alla fine del corpo. |
channel | Solo email. |
Il testo è nella lingua predefinita dell’app. Ogni email termina con un piè di pagina: il nome dell’app e il suo indirizzo.
Destinatari
| Valore | Chi la riceve |
|---|---|
owner | L’utente a cui appartiene l’evento o l’esecuzione. |
admins | Gli amministratori dell’app. |
role:<key> | Ogni utente che ha quel ruolo. Per un ruolo assegnato dalle email degli amministratori, gli amministratori. |
record.<field> | L’indirizzo email (o l’elenco di indirizzi) in quel campo del record dell’evento. |
record.<field> funziona solo dove l’evento porta con sé un record: un trigger collection, date, approval, call o webhook. Altrove la validazione lo rifiuta, e rifiuta anche un role: non dichiarato. I valori che non sono indirizzi email validi vengono scartati; al massimo 50 indirizzi ricevono un messaggio.
Invio del report
deliver su una pianificazione o su un modello invia per email il report di ogni esecuzione terminata.
schedules:
- cron: "0 7 * * 1"
agent: weekly_digest
deliver: { to: "role:manager", subject: "Weekly digest — {date}", onlyIfNew: true }
- Il report di un modello va per impostazione predefinita al proprietario dell’istanza (
to: owner). - Una pianificazione non ha un proprietario:
deliver.toè obbligatorio (adminsorole:<key>). subjectè per impostazione predefinita il titolo del report (il suo primo titolo#); si possono usare{date}e{title}.onlyIfNew: truesalta l’email quando il report è uguale all’ultimo consegnato.- I grafici del report vengono esclusi dall’email; il Markdown viene mantenuto come testo.
Email di fine esecuzione
Con notifications.emailOnRunDone: true, l’utente che ha avviato un’esecuzione da modulo riceve un’email quando termina:
- con un report: l’oggetto è il titolo del report (o "Your report is ready") e il corpo rimanda alla pagina dell’esecuzione;
- senza report: "Your request did not complete", e il corpo dice che non sono stati addebitati crediti.
Il pianificatore controlla anche le esecuzioni che nessuno sta seguendo, così l’email parte in tempo anche se l’utente ha chiuso la pagina. I testi sono in italiano quando la lingua predefinita dell’app è it, in inglese altrimenti.
notifications.digest non viene usato: metti invece una pianificazione con deliver.
Limiti e duplicati
- Una volta per evento. Ogni messaggio ha un id formato dall’evento e dal destinatario. Un webhook consegnato due volte, o un ciclo del pianificatore ripetuto, non invia mai la stessa email due volte.
- Tetti giornalieri (giorno UTC): al massimo 300 email al giorno per app e 10 al giorno per destinatario. Oltre questi limiti, i messaggi vengono saltati.
- Oggetto fino a 200 caratteri, corpo fino a 20.000.
Notifiche push
Un’app con un’app per telefono può inviare notifiche push. Le attivi dichiarando la capability push in spec.mobile.capabilities (vedi Esportazione).
Cosa succede:
- Gli amministratori dell’app aprono
/admin/pushe incollano le chiavi dei propri account degli store: il JSON dell’account di servizio Firebase (Android) e la chiave APNs (contenuto.p8, key id e team id, 10 lettere o cifre ciascuno; facoltativamente sandbox) per iPhone. Ogni piattaforma è facoltativa. Le chiavi sono cifrate a riposo e non vengono più mostrate; la pagina mostra solo quali piattaforme sono configurate e quanti dispositivi sono registrati. - Dopo l’accesso, l’app per telefono registra il dispositivo per quell’utente. Un utente può avere al massimo 10 dispositivi; i più vecchi vengono rimossi.
- Ogni notifica descritta sopra va anche sui telefoni dei destinatari, quando sono utenti dell’app con un dispositivo registrato: il
notifydi un trigger (stesso oggetto e corpo, e il link) e l’email di fine esecuzione ("Tap to open it."). L’invio del report (deliver) manda solo email.
Limiti e comportamento:
- Al massimo 20 notifiche push al giorno per utente, una volta per evento.
- Titolo fino a 120 caratteri, corpo fino a 240. Un link apre una pagina dell’app.
- Un dispositivo che lo store segnala come non più esistente viene rimosso.
- Senza chiavi per una piattaforma, i suoi dispositivi vengono saltati: l’app funziona anche prima che le push siano configurate.
Canali
spec.channels dichiara da dove arrivano le conversazioni. Lo schema accetta quattro tipi: web, phone, telegram ed email, ciascuno legato a un agente.
| Tipo | Stato |
|---|---|
web | Disponibile: le viste chat dell’app. Vedi Agenti e automazione. |
phone | Non ancora disponibile. La validazione lo accetta, e un trigger può nominarlo in on.call, ma il runtime non riceve ancora chiamate. |
telegram | Non ancora disponibile. |
email | Non ancora disponibile: l’app non riceve email. |
Non esiste un canale SMS o WhatsApp.
Egress: chiamare API esterne
Un agente raggiunge un servizio esterno in uno di due modi:
- uno strumento dell’app
http: una richiesta HTTPS che il runtime fa per l’agente, verso un host elencato nel manifest; - un server MCP in
agents[].mcpServers, aggiunto all’agente alla pubblicazione.
spec.egress.hosts elenca gli host che gli strumenti http dell’app possono chiamare (al massimo 20). Nient’altro è raggiungibile.
egress:
hosts: [api.example.org, "*.myshopify.com"]
notes: "api.example.org: public company register, CC BY 4.0. *.myshopify.com: each user's own shop."
agents:
- key: researcher
# ...
appTools:
- name: company
description: "Look up a company by number: path = /companies/<number>"
action: http
http: { url: "https://api.example.org", allowPath: true, attribution: "Example register, CC BY 4.0" }
Cosa fissa il manifest e cosa compila l’agente
Il manifest fissa il metodo, l’URL di base e gli eventuali header fissi. L’agente compila solo:
query— i parametri della query string (testo, numeri, booleani);path— un percorso aggiunto all’URL di base, solo quandoallowPath: true; lettere, cifre e._~-/, al massimo 300 caratteri, nessun segmento.o..;body— un corpo JSON, non per GET o DELETE, al massimo 100.000 caratteri.
L’agente non imposta mai header, host, metodo o credenziali.
Le protezioni
- Solo HTTPS. L’URL deve restare sull’host dello strumento.
- L’host deve essere in
spec.egress.hosts. Una voce*.<domain>serve solo per l’host di ciascun utente, salvato con la sua credenziale (https://{host}/…nell’URL dello strumento). - Ogni indirizzo a cui l’host si risolve viene controllato al momento della connessione: indirizzi privati, di loopback, link-local e simili vengono rifiutati.
- I redirect non vengono seguiti; la risposta dice dove puntavano.
timeoutMs1.000–30.000 (predefinito 20.000). La risposta viene tagliata oltremaxBytes(1.000–2.000.000, predefinito 500.000).- Gli
headersfissi non possono contenere credenziali:Authorization,Cookie,X-Api-Key,Host,Forwarded,X-Forwarded-*eProxy-*vengono scartati.
Lo strumento restituisce {status, data} per il JSON, altrimenti {status, text, truncated} (testo tagliato a 20.000 caratteri), più source quando lo strumento imposta attribution. Usa egress.notes per annotare perché ogni host è lì e le sue condizioni d’uso.
Le chiavi degli utenti
Uno strumento http può inviare una chiave che l’utente ha collegato per un provider (spec.data.credentials, tipo api_key):
http:
method: GET
url: "https://{host}/admin/api/2024-10/orders.json"
credential: { provider: shopify, header: X-Shopify-Access-Token, format: "{secret}" }
- Gli utenti collegano la loro chiave nella pagina account; una credenziale con
scope: orgviene impostata una volta dagli amministratori dell’app. Le chiavi sono cifrate a riposo e non vengono più mostrate (solo i loro ultimi quattro caratteri), non vengono mai messe in un obiettivo e mai restituite a un agente. - Il runtime aggiunge la chiave alla richiesta: per impostazione predefinita
Authorization: Bearer {secret};headereformatla cambiano;queryla invia invece come parametro della query. - Se la chiave compare nella risposta, viene sostituita con
[credential]. - Se l’utente non ha collegato il provider, lo strumento risponde "the user has not connected
<provider>: ask them to connect it on their account page". - PUT, PATCH e DELETE servono per scrivere sull’account dell’utente stesso, con una credenziale.
Le credenziali di tipo oauth e mcp sono accettate dallo schema ma non sono ancora offerte nella pagina account.
Server MCP
agents[].mcpServers aggiunge server MCP esterni (fino a 10 per agente) all’agente alla pubblicazione. Ognuno ha un name, un URL https://, headers facoltativi e allow ("all" o un elenco di nomi di strumenti). Il valore di un header non deve contenere un segreto: fai riferimento a una credenziale della tua organizzazione come ${VAR}. La validazione rifiuta un header che sembra un segreto in chiaro.