WebRobot
App Builder · pagine

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:

DoveInvia
triggers[].notifyUn’email quando succede un evento: un record salvato, una data raggiunta, un’approvazione decisa, un acquisto, un webhook, un timer.
schedules[].deliverIl report di un’esecuzione pianificata di un agente.
templates[].deliverIl report di ogni esecuzione di un’istanza di un modello.
notifications.emailOnRunDoneUn’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
CampoSignificato
toUn destinatario o un elenco di massimo 5. Vedi Destinatari.
subject, bodyTesto, 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.
linkLa chiave di una vista (diventa /v/<key>) o un percorso che inizia con /. L’indirizzo completo viene aggiunto alla fine del corpo.
channelSolo 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

ValoreChi la riceve
ownerL’utente a cui appartiene l’evento o l’esecuzione.
adminsGli 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 (admins o role:<key>).
  • subject è per impostazione predefinita il titolo del report (il suo primo titolo # ); si possono usare {date} e {title}.
  • onlyIfNew: true salta 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:

  1. Gli amministratori dell’app aprono /admin/push e 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.
  2. 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.
  3. Ogni notifica descritta sopra va anche sui telefoni dei destinatari, quando sono utenti dell’app con un dispositivo registrato: il notify di 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.

TipoStato
webDisponibile: le viste chat dell’app. Vedi Agenti e automazione.
phoneNon ancora disponibile. La validazione lo accetta, e un trigger può nominarlo in on.call, ma il runtime non riceve ancora chiamate.
telegramNon ancora disponibile.
emailNon 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 quando allowPath: 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.
  • timeoutMs 1.000–30.000 (predefinito 20.000). La risposta viene tagliata oltre maxBytes (1.000–2.000.000, predefinito 500.000).
  • Gli headers fissi non possono contenere credenziali: Authorization, Cookie, X-Api-Key, Host, Forwarded, X-Forwarded-* e Proxy-* 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: org viene 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}; header e format la cambiano; query la 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.