Operatori

Un operator è un nodo che esegue un'azione deterministica: nessun LLM, nessuna casualità. Per un dato input, l'output è prevedibile.

Perché usarli

Qualsiasi logica che può essere scritta esplicitamente dovrebbe esserlo. Un LLM che "calcola un totale" o "formatta una data" è un anti-pattern: è più lento, più costoso e può commettere errori.

Regola pratica: se puoi scrivere la funzione in 5 righe di Python, è un operator — non un agent.

Tipi disponibili

operator HTTP

Effettua una chiamata HTTP (REST, GraphQL). Configurazione:

• URL (con placeholder dal contesto)
• Metodo, header, body
• Autenticazione: bearer, basic, api_key_header (header personalizzato) o oauth2 (vedi sotto)
• Mappatura della risposta agli slot

operator DB

Esegue una query su un database registrato in Amministrazione → Database. Supporta Postgres, MySQL, MongoDB e il database interno betool per le tabelle definite dall'utente.

file_transform

Trasforma un file. Trasformatori integrati:

• Lettura (PDF con OCR, DOCX, XLSX, CSV)
• Chunking (per pagina, per chunk di token)
• Conversione (HTML → testo, Markdown ↔ HTML)
• Estrazione di struttura (JSON da uno schema)

compute

Calcoli e aggregazioni sugli slot di contesto:

• Filter / map / reduce su liste
• Statistiche colonna per colonna (count, total, pct)
• Proiezioni di schema
• Condizioni logiche composte

payload_mapper

Compone un payload di output dagli slot di contesto. Utile per preparare il body di un operator HTTP a valle.

code_step

Quando la logica deterministica supera ciò che compute può gestire, un code step esegue codice personalizzato in una sandbox — bloccato da revisione umana. Vedi Code Step governati.

Autenticazione e segreti

Gli operator che comunicano con un sistema esterno (HTTP, DB) referenziano un account registrato all'interno dell'organizzazione. Le credenziali non sono mai visibili all'interno della pipeline stessa — viene referenziato solo un nome di account.

Di conseguenza, la rotazione di una password non richiede alcuna modifica a nessuna pipeline.

OAuth2 in uscita (client_credentials)

Per le API che richiedono un token OAuth2 (cloud enterprise, ERP, provider di terze parti), l'operator HTTP supporta la modalità oauth2. Registri una credenziale OAuth2 nell'organizzazione — token_url, client_id, client_secret, scope — e il nodo referenzia solo un identificatore non sensibile.

Al momento della chiamata, betool ottiene un token e lo riutilizza finché resta valido; lo rinnova in modo lazy alla scadenza, senza task in background. Il client_secret non viene mai restituito dall'API di amministrazione (viene esposto solo un indicatore has_secret), e il token ottenuto viene posto come Authorization: Bearer … sulla richiesta in uscita.

La rotazione del segreto dopo una rotazione lato provider non richiede modifiche alla pipeline: la chiamata successiva si rinnova automaticamente.

Idempotenza

Qualsiasi operator che produce un effetto collaterale (POST HTTP, INSERT DB, invio email) deve essere progettato per l'idempotenza lato destinazione. Pratica consigliata:

• Includi un idempotency_key nel payload (in genere exchange_id).
• Verifica lato destinazione se la chiave è già stata elaborata.

betool non riprova automaticamente un operator fallito: è responsabilità della tua pipeline orchestrare la strategia di retry (loop + condition).