WebRobot
App Builder · pagine

Documentazione · App Builder

Agenti e automazione

Un’app svolge il suo lavoro attraverso gli agenti. Una persona ne avvia uno compilando il modulo di esecuzione o scrivendo in una chat. L’app ne avvia uno da sola quando succede qualcosa: un record viene salvato, arriva un webhook, un acquisto si completa, una data si avvicina, una persona decide un’approvazione. Questa pagina spiega ogni parte e come le parti si combinano. L’elenco campo per campo è nel riferimento.

Prima di avviare gli agenti: il provider di AI

Gli agenti girano sulla piattaforma WebRobot, nell’organizzazione proprietaria dell’app, con la chiave API dell’app. L’organizzazione ha bisogno di un provider di AI: una propria credenziale LLM (nella console, sotto Credentials) o un piano gestito.

Se l’organizzazione non ne ha, la piattaforma rifiuta l’avvio:

  • Un’esecuzione o un messaggio in chat avviato da un utente fallisce con il messaggio di errore della piattaforma.
  • Un agente avviato da un trigger non parte. Il rifiuto viene registrato e gli amministratori dell’app lo vedono nella pagina dei dati (/admin/data), sotto Agents that did not start (agenti che non sono partiti). Quando il motivo è la mancanza di un provider di AI, la pagina lo dice: "The organization has no AI provider: add one in the console (Credentials) or switch to a managed plan, then try again."

Agenti

Ogni voce di spec.agents è un agente. Ne serve almeno uno.

CampoCosa fa
keyIl nome dell’agente dentro l’app (lettere minuscole, cifre, _, -). Le altre parti del manifest puntano a questo nome.
rolemain (predefinito), designer, setup, analyst, helper, scheduled. Il modulo di esecuzione avvia un agente main (vedi Scegliere l’agente di un’esecuzione).
descriptionCosa fa l’agente. È anche la descrizione del profilo alla pubblicazione, e compare nello strumento ask_<agent> che ricevono gli altri agenti.
profileEsattamente uno tra ref e inline.
goalTemplateIl compito che l’agente riceve. Vedi Modelli di obiettivo.
contextValori aggiuntivi risolti quando parte un’esecuzione. Vedi Contesto.
appToolsGli strumenti che l’app dà a questo agente. Vedi Strumenti dell’app.
mcpServersServizi esterni come server MCP (fino a 10), aggiunti all’agente alla pubblicazione.
delegates, awaits, memoryCollegamenti ad altri agenti, ad approvazioni e alla memoria persistente. Generano strumenti.
writesToTrasforma ogni esecuzione pianificata, avviata da trigger o da modello che termina in un record.
variables, startOptionsValori passati alla piattaforma quando l’agente parte.

Profilo: ref o inline

  • profile.ref punta a un profilo agente che esiste già sulla piattaforma, per id o per nome.
  • profile.inline contiene l’intera definizione dell’agente (il contratto di Agent Studio). Il manifest controlla solo che abbia crews. Ogni crew porta il suo modello, il suo prompt e i suoi limiti:
agents:
  - key: waiter
    description: Takes orders at the table
    profile:
      inline:
        display_name: Trattoria waiter
        crews:
          - id: waiter
            engine: agent_sdk
            model: claude-sonnet-5-5
            max_turns: 12
            system_prompt: |-
              You are the waiter of the trattoria. Answer briefly, in the customer's language.

Il manifest non ha un proprio campo model: il modello fa parte del profilo.

La pubblicazione crea (o aggiorna) un profilo di piattaforma per ogni agente inline, chiamato <slug>-<agent key>, nell’organizzazione dell’app. Il manifest pubblicato porta poi ref invece di inline. Finché non pubblichi, un agente inline non può essere eseguito: un’esecuzione o una chat risponde "agent <key> has an inline profile: publish the app first".

Quando un agente è la sorgente di una vista chat, la pubblicazione lo imposta in modo che risponda solo con il suo ultimo messaggio, così le sue note di lavoro tra una chiamata di strumento e l’altra non arrivano mai all’utente.

Campi che il runtime non usa ancora

output, resultSchema e i limits a livello di agente (maxTurns, maxBudgetUsd, timeoutSeconds) sono accettati dallo schema, ma il runtime non li applica. Imposta invece i limiti del modello dentro il profilo inline.

variables e startOptions

  • variables imposta le variabili del profilo. Ogni valore è un modello riempito con i valori del modulo, {lang} e {user}.
  • startOptions aggiunge campi alla chiamata di avvio della piattaforma. Le chiavi forceReauthor, llmProvider, engine, camoufoxMode, ttlSeconds, activeDeadlineSeconds e clusterSelector vanno come opzioni di avvio; qualsiasi altra chiave viaggia come input accanto all’obiettivo.

Modelli di obiettivo

goalTemplate è il testo che l’agente riceve come compito. Il runtime lo riempie prima dell’avvio.

SintassiSignificato
{name}Sostituito dal valore. Una lista diventa a, b, c; un oggetto diventa JSON; un valore vuoto diventa niente.
{?name}…{/name}Il blocco viene mantenuto solo quando name non è vuoto.
{!name}…{/name}Il blocco viene mantenuto solo quando name è vuoto (l’"altrimenti" di un blocco facoltativo).

Un valore è vuoto quando manca, è "", false o una lista vuota. I blocchi possono essere annidati e occupare più righe. Una riga rimasta vuota perché i suoi blocchi sono stati eliminati viene rimossa. Ogni {?x} e {!x} deve essere chiuso con {/x}, altrimenti la validazione fallisce.

goalTemplate: |-
  Write a city brief for {city} ({country_label}).
  {?focus}Focus on: {focus}{/focus}
  {!focus}Cover transport, housing and safety.{/focus}
  Answer in {lang}. Today is {date}.

Quali valori può usare un obiettivo

Cosa riempie il modello dipende da cosa ha avviato l’agente.

Un’esecuzione dal modulo

  • ogni campo del modulo, per nome; per un campo con opzioni, {<field>_label} è l’etichetta dell’opzione (o delle opzioni) scelta nella lingua dell’esecuzione
  • per un campo file, {<field>} sono i nomi dei file (con i loro id) e {<field>_text} il testo estratto da essi
  • i valori delle voci di context e degli slot
  • {date} (AAAA-MM-GG, UTC), {lang}, {user} (l’email dell’utente), {role}

Senza un goalTemplate, l’obiettivo è una riga Label: value per ogni campo del modulo compilato.

Un messaggio in chat

{message} (il nuovo messaggio), {history} (la conversazione fino a quel punto), {session}, {date}, {lang}, {user}, {role}. Il modello predefinito è:

{?history}Conversation so far:
{history}

{/history}New message:
{message}

Un trigger (vedi Trigger)

  • ogni campo del record dell’evento il cui nome è in minuscolo (lettere, cifre, _), tranne userId; un campo oggetto diventa JSON, tagliato a 4.000 caratteri
  • {record.<field>}, gli stessi campi sotto il nome del record
  • {event}, l’intero evento come JSON, tagliato a 8.000 caratteri
  • {date}

Il testo usato è il goal del trigger, altrimenti il goalTemplate dell’agente avviato, altrimenti An event happened in the app: {event}. Do your task for it.

Gli strumenti dell’app trovano un record dal suo id. Quindi, quando l’obiettivo non nomina né {event}, né {id}, né {record.id}, il runtime aggiunge un’ultima riga con il riferimento al record: (The record: collection <name>, id <id>.).

Una pianificazione o un trigger a tempo (on.cron): {date} e {lang}. Una pianificazione usa il suo goal, altrimenti il goalTemplate dell’agente, altrimenti Run your scheduled task for {date}. Un trigger a tempo usa il suo goal, altrimenti Run your scheduled task for {date}.

Un’istanza di un modello: i suoi parametri per nome, {instance} (il titolo dell’istanza), {date}, {lang}, {user}.

Un segnaposto che niente riempie diventa una stringa vuota. La validazione rifiuta un segnaposto che non è un campo del modulo, una chiave di contesto, l’etichetta di un’opzione, il testo di un file o un valore predefinito, tranne negli agenti avviati da un trigger, dove è il record a decidere quali campi esistono.

Cosa aggiunge il runtime dopo l’obiettivo

  • La sessione dell’app. Un agente che ha strumenti dell’app riceve un ultimo paragrafo: App session for this task: s_… — pass it as "session" to the app's tools. La sessione appartiene all’utente per cui si sta lavorando e dura 3 ore. È così che gli strumenti sanno di chi sono i record che possono toccare.
  • La memoria. Un agente con memory riceve quello che ricorda dell’utente (vedi Memoria).

Contesto

Le voci di context aggiungono valori all’obiettivo, risolti quando parte un’esecuzione. Il valore va sotto la key della voce.

fromValore
collection:<name>.<field>Quel campo di un record: il record scelto in un campo del modulo alimentato da optionsFrom: collection:<name>, altrimenti l’ultimo record dell’utente in quella raccolta (per una raccolta posseduta da user).
collection:<name>I record di quella raccolta che l’utente può leggere, una riga JSON ciascuno: al massimo 30 record e 8.000 caratteri.
user.<field>Un campo dell’utente che ha effettuato l’accesso (email, …).
slot:<key>L’output di uno slot Python eseguito sui valori del modulo. Un oggetto aggiunge i suoi campi ai valori; qualsiasi altra cosa va sotto la chiave. Uno slot che fallisce ferma l’esecuzione prima che venga trattenuto qualsiasi credito.

I record arrivano all’agente solo se l’utente può leggerli (la stessa regola di viste e strumenti), senza campi interni. Lo schema elenca anche session, page e derived:<extension>: il runtime non li risolve ancora.

Strumenti dell’app

Gli appTools sono gli strumenti che l’app serve all’agente. Il runtime li serve tramite l’endpoint MCP dell’app; la pubblicazione collega ogni agente all’endpoint con un proprio indirizzo e token. Un agente vede e può chiamare solo i propri strumenti e quelli generati dai suoi collegamenti, mai quelli di un altro agente.

appTools:
  - { name: find_dishes, description: "Dishes of the menu", action: search, collection: menu }
  - { name: save_order, description: "Create or update an order", action: write, collection: orders }
  - { name: company_lookup, description: "Company register", action: http,
      http: { url: "https://api.example.org/companies", allowPath: true, attribution: "Example register, CC BY 4.0" } }

I nomi degli strumenti sono in minuscolo (^[a-z][a-z0-9_]*$). Due agenti possono dichiarare uno strumento con lo stesso nome solo se fa la stessa cosa (stessa azione, destinazione e limiti); la descrizione può differire.

Tutte le azioni

actionCosa invia l’agenteCosa riceve
readid (facoltativo)Con un id: quel record, o null. Senza: i record che può leggere, dal più recente, al massimo 50.
searchwhere (campi che devono essere uguali), text (cercato in qualsiasi campo), limit (1–100, predefinito 20)I record corrispondenti, dal più recente.
showcome searchCome search: record destinati a essere mostrati nella risposta.
writefields, id (facoltativo)Con un id: aggiorna quel record (solo se l’utente può scriverlo). Senza: crea un record. Restituisce il record.
appendfieldsCrea sempre un record.
read_filefile (un id di file f_… presente nel compito)Il file dell’utente: il suo testo, o per un’immagine l’immagine stessa (fino a 5 MB), passata al modello come immagine.
callargsEsegue lo slot Python indicato in slot, con {args, userId}. Restituisce l’output dello slot.
httpquery, path (solo con allowPath), body (JSON, non per GET/DELETE)Una richiesta a un’API HTTPS esterna. Vedi Messaggi ed egress.
delegatetaskGenerato da delegates.
approvalsummary, requestGenerato da awaits.
remembernotesGenerato da memory.

Dettagli:

  • fields deve essere un oggetto di al massimo 32.000 caratteri (come JSON). id e userId al suo interno vengono ignorati. Un nuovo record riceve i valori predefiniti dei campi della raccolta, l’id dell’utente, createdAt e updatedAt.
  • Un record creato o aggiornato da uno strumento è un evento: i trigger dell’app scattano su di esso.
  • Un limite create:<collection> si applica ai record che un utente crea tramite gli strumenti (vedi Limiti sugli avvii degli agenti).
  • Uno strumento con extension è implementato da codice esterno al manifest. Non viene servito.
  • Uno strumento call richiede l’esecutore di slot del runtime. Dove manca, lo strumento risponde "slots are not available on this runtime".
  • Gli errori tornano all’agente come risultato dello strumento che può leggere (per esempio "no such record", "fields too large").

Quali record raggiunge uno strumento

Uno strumento richiede la sessione dell’app quando il suo scope è user o session, quando è read_file, quando è uno strumento http con la credenziale di un utente, o quando la sua raccolta è posseduta da user o instance. In quel caso:

  • l’utente raggiunge i propri record, e i record che le regole di accesso della raccolta danno al suo ruolo (con can: [write] per le scritture);
  • gli amministratori dell’app raggiungono tutti i record;
  • nell’esecuzione di un’istanza di un modello, una raccolta posseduta da instance mostra solo i record di quell’istanza, e i nuovi record portano l’istanza.

Uno strumento su una raccolta app, shared o org senza sessione raggiunge tutti i record di quella raccolta. La proprietà delle raccolte è spiegata in Dati.

Agenti usati dai visitatori senza accesso

auth.anonymous.agents nomina gli agenti destinati ai visitatori. Un agente di questo tipo non può avere:

  • uno strumento su una raccolta posseduta da org (il back office del proprietario);
  • uno strumento write o append su una raccolta posseduta da app o shared;
  • uno strumento http con un metodo diverso da GET, o con la credenziale di un utente.

La validazione li rifiuta, e anche il runtime rifiuta la chiamata. Nota: oggi ogni messaggio in chat e ogni esecuzione richiede un utente che ha effettuato l’accesso, qualunque cosa dica auth.anonymous.agents.

Delega, approvazioni e memoria

Questi tre collegamenti generano strumenti per l’agente che li dichiara.

  • delegates: [other] dà lo strumento ask_<other> (i trattini diventano _). L’agente invia un task (fino a 8.000 caratteri); il runtime avvia l’altro agente con la sessione dello stesso utente e attende fino a 150 secondi. Restituisce {answer}, {error}, o {status: "still working", runId}. Un agente non può delegare a sé stesso, e la delega non può formare un ciclo.
  • awaits: [approval] dà lo strumento request_<approval>. Vedi Approvazioni.
  • memory: user | instance dà lo strumento remember. La memoria è un testo per utente (o per istanza di modello con instance), al massimo 4.000 caratteri. Viene aggiunta a ogni compito dell’agente sotto "What you remember about this user (update it with the remember tool):". remember sostituisce l’intero testo. memory: instance richiede un modello che usi l’agente.

Esecuzioni

Un’esecuzione è un’esecuzione in background di un agente avviata dal modulo di esecuzione (spec.inputForm). È così che funziona il pattern report.

Scegliere l’agente di un’esecuzione

Il modulo di esecuzione avvia un agente main. Se più agenti hanno il ruolo main, viene eseguito il primo la cui condizione when corrisponde ai valori del modulo (per esempio when: "mode == 'market'"); altrimenti il primo agente main.

Dall’avvio al report

  1. L’utente invia il modulo. Il runtime controlla i valori: campi obbligatori, tipi, maxLength, opzioni, il parent di una scelta, e piani (gatedBy risponde 402 "needs the plan …").
  2. I campi file mantengono solo i file caricati da questo utente. Una select alimentata da una raccolta deve contenere un record che l’utente può leggere.
  3. Vengono risolti gli slot e le voci di contesto.
  4. Vengono controllati i limiti (run, agent:<key>), poi il piano richiesto dal costo (requiresPlan).
  5. Trattenuta. I crediti stimati vengono prelevati dal saldo. Senza crediti sufficienti l’avvio fallisce con 402 "not enough credits". Gli amministratori eseguono gratuitamente.
  6. Viene costruito l’obiettivo, con la sessione dell’app e la memoria, e l’agente parte sulla piattaforma. Se l’avvio fallisce, la trattenuta viene restituita.
  7. Controllo periodico. La pagina dell’esecuzione (/r/<id>) chiede lo stato dell’esecuzione ogni 5 secondi. L’utente può andarsene: il report resta lì.
  8. Liquidazione. Quando l’agente termina, il suo testo finale diventa il report, a partire dal suo primo titolo # ; quel titolo è il titolo dell’esecuzione. I crediti vengono liquidati una volta: nessun report, rimborso completo; prezzo fisso, la trattenuta è il prezzo; prezzo a consumo, l’utilizzo reale (vedi Pagamenti e crediti).

Un’esecuzione senza report termina come error con l’errore della piattaforma, o "the agent ended without a report".

Con notifications.emailOnRunDone: true, l’utente riceve un’email quando l’esecuzione termina, e il pianificatore raccoglie le esecuzioni che nessuno sta seguendo. Vedi Messaggi.

Cronologia e report

  • Una vista history elenca le esecuzioni dell’utente, dalla più recente, con titolo, stato e data.
  • La pagina dell’esecuzione mostra l’avanzamento, poi il report. È stampabile a meno che la vista report imposti printable: false. Solo l’utente che ha avviato l’esecuzione e gli amministratori dell’app possono aprirla.
  • La vista admin elenca le ultime 30 esecuzioni di tutti gli utenti.

writesTo non si applica alle esecuzioni da modulo: il risultato di un’esecuzione da modulo è il suo report.

Chat

Una vista chat è una conversazione con un agente: il source: agent:<key> della vista, altrimenti il primo agente main.

  • Solo gli utenti che hanno effettuato l’accesso possono usare la chat. A un visitatore viene chiesto di accedere.
  • Un messaggio è al massimo di 2.000 caratteri. L’agente riceve gli ultimi 8 turni della conversazione ({history}, ogni messaggio tagliato a 800 caratteri) e il nuovo {message}.
  • Una risposta alla volta: un secondo messaggio mentre l’agente sta rispondendo riceve "the assistant is still answering". Una risposta che non arriva entro 10 minuti viene abbandonata.
  • Il browser controlla la risposta ogni 3 secondi.
  • Se l’agente fallisce, l’utente vede "I could not answer that, please try again." e gli eventuali crediti prelevati per il messaggio vengono restituiti.
  • Ogni messaggio costa il costo fisso dell’agente (billing.costs["agent:<key>"], o il suo estimate); gli amministratori usano la chat gratuitamente.
  • Limite di frequenza: 30 messaggi all’ora per utente e 60 all’ora per indirizzo IP.

Orario di servizio. Con spec.serviceHours, il server di chat dedicato dell’organizzazione viene acceso durante quegli orari (da leadMinutes prima di ogni apertura, predefinito 10). In quegli orari, un messaggio riceve risposta nella stessa richiesta e il server mantiene la conversazione. Fuori da quegli orari, o quando quel server non è pronto, ogni messaggio è un’esecuzione dell’agente come sopra. Oggi i messaggi a cui risponde il server di chat non vengono addebitati in crediti all’utente; il loro utilizzo viene misurato e addebitato alla tua organizzazione.

Squadre

spec.teams raggruppa gli agenti in un’unica unità, pubblicata come un unico profilo agente.

  • mode: sequence — gli steps vengono eseguiti uno dopo l’altro; un passo con after viene eseguito dopo i passi che nomina. I passi non devono formare un ciclo, e un agente può comparire una sola volta.
  • mode: swarm — un lead pianifica e chiude il lavoro; i members condividono una bacheca dei compiti. maxMinutes (1–180) limita lo swarm.

Ogni membro deve avere un profilo inline (il profilo della squadra è costruito dalle loro crew). La chiave di una squadra non può essere la chiave di un agente. Trigger e modelli avviano una squadra con start.team / team; writesTo trasforma il suo risultato in un record.

Trigger

Un trigger collega un evento a un’azione. Ha esattamente una sorgente (on) ed esattamente un’azione.

triggers:
  - key: to_kitchen
    description: Every confirmed order goes to the kitchen
    on: { collection: orders, op: any, where: { status: confirmed } }
    start: { agent: kitchen }
    asUser: false

Sorgenti (on)

SorgenteScatta quando
collection (+ op, where)Un record della raccolta viene creato (op: insert, predefinito), aggiornato (update) o entrambi (any), e ogni campo di where è uguale.
cronUn’espressione cron a 5 campi (UTC) corrisponde.
date (collection, field, offsetDays, hour)Una volta al giorno a partire da hour UTC (predefinito 7): per ogni record il cui campo data, spostato di offsetDays (−365…365, predefinito 0), è oggi. Ogni record scatta una volta per data. where filtra i record.
webhook: trueQualcuno chiama POST /api/hooks/<trigger key> con il segreto dell’hook.
paymentSi completa un acquisto di quel piano o pacchetto; * per qualsiasi acquisto.
approval (+ decision)Una persona decide quell’approvazione: approved, rejected o any (predefinito).
call (+ callEvent, where)Una chiamata di un canale telefonico. Non ancora disponibile: vedi Messaggi.

Un record diventa un evento collection quando viene salvato da una vista modulo o prenotazione, nella pagina dei dati degli amministratori (non da un’importazione CSV), dallo strumento write/append di un agente, dal write di un trigger, o da writesTo.

Webhook. La console mostra all’organizzazione dell’app l’indirizzo e il segreto di ogni trigger webhook. Invia il segreto nell’header X-Hook-Secret. Un mittente in grado di firmare può aggiungere X-Hook-Timestamp (secondi Unix, entro 5 minuti) e X-Hook-Signature (HMAC-SHA256 esadecimale di <timestamp>.<raw body> con il segreto); una firma sbagliata o scaduta viene rifiutata. Il corpo è al massimo di 64.000 caratteri; il JSON viene interpretato, qualsiasi altra cosa viene mantenuta come testo. La risposta è 202 con ciò che è stato avviato. I webhook non funzionano sull’indirizzo di anteprima.

Azioni

AzioneCosa succede
start: {agent | team | job}Avvia un agente, una squadra o un job di dati. L’obiettivo è costruito come in Modelli di obiettivo.
notifyInvia un’email in testo semplice (e una notifica push sull’app per telefono). Vedi Messaggi.
writeSalva i dati dell’evento come record, senza un agente.
chargePreleva crediti dall’utente dell’evento. Vedi Pagamenti e crediti.

asUser (predefinito true): l’agente avviato lavora con la sessione dell’app dell’utente a cui appartiene l’evento (lo userId del record, chi ha chiesto un’approvazione, l’acquirente) e raggiunge solo i suoi record e la sua memoria. Con false, o quando l’evento non ha un utente (un webhook, un timer), gira senza utente.

write. Salva in write.collection: con fields, ogni campo del record prende il valore a quel percorso puntato dei dati dell’evento; senza, i campi dell’evento che la raccolta dichiara. Con keyBy, l’id del record viene da quel campo, così lo stesso evento salvato due volte aggiorna lo stesso record. Una raccolta posseduta da user richiede un evento con un utente; una raccolta posseduta da instance non può essere scritta. Il record è al massimo di 32.000 caratteri ed è a sua volta un evento.

Agenti e job avviati da trigger sono seguiti come le esecuzioni pianificate: quando terminano, il pianificatore trasforma il risultato in un record della raccolta writesTo dell’agente (o della squadra). Un job deve essere collegato (pubblicato); altrimenti non parte nulla ("not linked").

Protezione dai cicli. Un’app avvia al massimo 20 azioni di trigger al minuto; le altre vengono saltate. Un agente che scrive nella raccolta che lo avvia ha bisogno di un filtro where (validazione).

Pianificazioni

spec.schedules esegue lavoro a orari stabiliti.

schedules:
  - cron: "0 6 * * 1-5"
    agent: daily_signal
    goal: "Write today's signal for {date}."
    deliver: { to: admins, onlyIfNew: true }
actionConCosa fa il runtime
run (predefinito)agentAvvia l’agente.
digestagentCome run.
run, ingestjobAvvia il job di dati collegato.
settle—Controlla fino a 50 esecuzioni ancora in corso o non liquidate.
sync—Non eseguito dal runtime.
  • Le pianificazioni con owner: app (predefinito) sono eseguite dal pianificatore del runtime. Le pianificazioni con owner: platform vengono ignorate dal runtime.
  • Le espressioni cron hanno 5 campi, in UTC: *, elenchi, intervalli e passi. La domenica è 0 o 7.
  • Il pianificatore fa un ciclo ogni pochi minuti. Ogni pianificazione scatta una volta per ogni minuto corrispondente dall’ultimo ciclo. Dopo un’interruzione recupera al massimo le ultime 3 ore.
  • Un’esecuzione pianificata non ha un utente: nessuna sessione dell’app, nessun credito addebitato.
  • Quando l’esecuzione termina, il suo risultato diventa un record della raccolta writesTo dell’agente. parse decide come: whole (predefinito, il report), markdown_sections (un campo per ogni titolo ## ), json_last o final_block (i campi del blocco JSON finale). keyBy prende l’id del record da un campo (per esempio date), così una nuova esecuzione aggiorna lo stesso record. Un’esecuzione non ancora terminata dopo 6 ore viene segnata come fallita ("timed out").
  • deliver invia il report per email. Vedi Messaggi.

Modelli e istanze

Un modello è un agente che gli utenti dell’app creano per sé, con i propri parametri, pianificazione, dati e memoria. Ogni copia è un’istanza.

templates:
  - key: watch
    title: Price watch
    agent: watcher
    params:
      - { name: product_url, type: url, required: true }
      - { name: threshold, type: number }
    schedule: { cron: "0 8 * * *", userCanChange: true }
    maxPerUser: 5
    cost: { perRun: 3 }
    deliver: { onlyIfNew: true }
views:
  - { key: my_watches, type: instances, template: watch, title: My watches }
  • Un modello nomina esattamente un agent o un team. I suoi parametri sono campi di modulo: controllati per obbligatorietà, numero, booleano, url (deve iniziare con http:// o https://), opzioni, lunghezza (predefinita 2.000 caratteri).
  • Una vista instances permette all’utente di creare, eseguire, mettere in pausa, riprendere, aggiornare ed eliminare le proprie istanze, e mostra l’ultimo risultato di ciascuna.
  • maxPerUser (1–1000, predefinito 5): oltre questo valore, "you can have at most N". roles limita chi può crearne una.
  • L’utente può impostare il proprio cron quando schedule.userCanChange non è false. Il cron deve avere 5 campi composti da cifre, *, ,, /, -.
  • Ogni istanza attiva con un cron viene eseguita alla scadenza. L’obiettivo è il goal del modello, altrimenti il goalTemplate dell’agente (o della squadra), altrimenti una riga name: value per ogni parametro.
  • I crediti di cost.perRun vengono prelevati dal proprietario dell’istanza prima dell’avvio. Senza crediti sufficienti non parte nulla e l’istanza mostra "no credits". Un’esecuzione che non produce un risultato restituisce i crediti. Un amministratore che esegue a mano la propria istanza non paga nulla. cost.perMonth non viene ancora addebitato.
  • Le raccolte possedute da instance tengono separati i record di ogni istanza. Un record per esecuzione va nella raccolta writesTo dell’agente.
  • deliver invia per email ogni report al proprietario dell’istanza, per impostazione predefinita.
  • Le istanze non possono essere create sull’indirizzo di anteprima.

Approvazioni

Un’approvazione è un punto di controllo in cui una persona decide prima che il lavoro prosegua.

approvals:
  - key: refund
    title: Refund over 100 €
    role: manager
    fields: [order_id, amount]
    timeoutMinutes: 1440
    onTimeout: reject
agents:
  - key: support
    awaits: [refund]
    # ...
triggers:
  - key: refund_approved
    on: { approval: refund, decision: approved }
    start: { agent: refunds }
views:
  - { key: approvals, type: approvals, roles: [manager] }

Come funziona

  1. L’agente chiama request_<key> con un summary di una riga (fino a 500 caratteri) e i dettagli in request (fino a 32.000 caratteri come JSON).
  2. Lo strumento risponde subito con status: pending. L’agente dice all’utente che la richiesta è in attesa; la sua esecuzione poi termina normalmente.
  3. Una persona apre una vista approvals, vede le richieste in attesa che può decidere (con i fields della richiesta) e approva o rifiuta, con una nota facoltativa (fino a 1.000 caratteri).
  4. La decisione è un evento. Il lavoro riprende solo tramite un trigger su quell’approvazione: avvia un agente (lo stesso o un altro) il cui record è formato dai campi della richiesta più approvalId, summary e note. Con asUser (predefinito), quell’agente lavora per l’utente che ha fatto la richiesta.

Un’approvazione che nessun agente ha in awaits viene rifiutata dalla validazione.

Chi decide

  • decidedBy: role (predefinito): le persone con il role dell’approvazione, e gli amministratori dell’app. Il ruolo deve essere un ruolo del personale (assegnato dalle email degli amministratori, su invito o derivato), mai il ruolo che chiunque riceve alla registrazione.
  • Nessuno decide la propria richiesta, amministratori inclusi: "you cannot decide your own request".
  • decidedBy: requester: conferma solo l’utente il cui agente ha fatto la richiesta (per esempio una rosa di opzioni che l’agente gli ha proposto). Non accetta role.
  • Una richiesta viene decisa una sola volta; una seconda decisione riceve "already decided".

Timeout

Con timeoutMinutes (1–10.080), una richiesta ancora in attesa alla scadenza viene decisa dal pianificatore con onTimeout: reject (predefinito) o approve. La decisione viene registrata come presa da timeout, e i trigger scattano con approved o rejected.

Limiti sugli avvii degli agenti

spec.limits limita quanto spesso partono gli agenti e quanti record creano gli utenti.

actionContaperSi applica a
runtutte le esecuzioni da modulo di un utenteuser (predefinito)esecuzioni avviate dal modulo
agent:<key>le esecuzioni da modulo di quell’agente da parte di un utenteuser (predefinito)esecuzioni avviate dal modulo
agentsogni avvio di agente da eventiapp o useragenti avviati da trigger
agent:<key>avvii di quell’agente da eventiapp o useragenti avviati da trigger
create:<collection>record che un utente creauser (predefinito)strumenti degli agenti e viste modulo
limits:
  - { action: run, max: 3, window: day, plans: { pro: 50, business: -1 } }
  - { action: agents, per: app, max: 200, window: day }
  - { action: "agent:kitchen", per: user, max: 10, window: hour }
  • window: minute, hour, day, month (30 giorni) o total (da sempre). Le finestre sono scorrevoli: "l’ultimo giorno" conta a ritroso da adesso.
  • plans dà a un piano o pacchetto il suo massimo; -1 = illimitato. Un utente con più piani ottiene il più alto.
  • roles restringe un limite sulle esecuzioni da modulo a quei ruoli.
  • Per gli avvii da eventi, per: app conta ogni avvio dell’app e per: user gli avvii sugli eventi di quell’utente; per deve essere scritto esplicitamente, e total non viene contato. Un limite agent:<key> con per: user limita quindi le esecuzioni da modulo dell’utente e, separatamente, gli avvii sui suoi eventi; con per: app limita solo gli avvii da eventi.
  • Gli amministratori dell’app non sono limitati sulle esecuzioni da modulo e sui record che creano. I limiti sugli avvii da eventi contano ogni avvio, chiunque sia l’utente dell’evento.
  • I limiti create: sulle viste modulo non guardano plans: tutti ricevono max.

Quando un limite viene raggiunto, un’esecuzione da modulo riceve 429 "limit reached: N per day" (o "N in your plan" per total). Un avvio da evento viene rifiutato con "limit reached: N agent starts per hour for the app" (o "for this user"); il rifiuto viene registrato e mostrato agli amministratori sotto Agents that did not start nella pagina dei dati. La pagina mostra gli 8 più recenti; l’app conserva i 30 più recenti.

per: ip e per: org sono accettati dallo schema ma non applicati. Le azioni chat e login non vengono lette da spec.limits: chat e accesso hanno limiti fissi (vedi Runtime).