Code Step (code_step)
Alcune logiche sono troppo specifiche per un operator compute, eppure troppo deterministiche per giustificare un agent LLM: riconciliazioni multi-sorgente, calcoli di business su misura, normalizzazioni esotiche. Per questi casi, il nodo code_step esegue codice all'interno di una sandbox, senza chiamata LLM e con un output prevedibile.
Il codice viene modificato direttamente, come qualsiasi altro campo di configurazione: nessuna chiave di code_step è bloccata e non è richiesta alcuna approvazione specifica per il codice. Una modifica si applica non appena la pipeline viene pubblicata, alla successiva esecuzione.
Il modello di esecuzione
code_step esegue Starlark — un dialetto di Python progettato per l'isolamento: nessun accesso al filesystem, nessuna rete, nessun import, né loop while né ricorsione, deterministico, delimitato da un budget di tempo. Il codice vede solo:
- Gli input che gli mappi esplicitamente (
input_paths). - Gli strumenti che autorizzi a chiamare (
allowed_tools).
Tutto il resto è fuori portata. Un code step non può accedere a una risorsa che non gli hai consegnato.
Configurazione
| Campo | Scopo |
|---|---|
| Codice | Il sorgente Starlark che viene eseguito, modificato direttamente. |
Input (input_paths) | Mappatura variabile → selettore. Solo queste chiavi di contesto sono esposte al codice. Le chiavi interne (_*) vengono rifiutate. |
Allowlist di strumenti (allowed_tools) | Gli strumenti chiamabili tramite tool(name, args), massimo 50 chiamate per esecuzione. Ogni chiamata eredita le protezioni proprie dello strumento (protezione SSRF, fatturazione, audit, killswitch). |
Chiave di output (output_key) | Dove porre il risultato (serializzabile in JSON) nel contesto. I nodi a valle leggono questa chiave. Vuota = risultato non memorizzato. |
Budget di esecuzione (timeout_ms) | Tetto di tempo: 5.000 ms per impostazione predefinita, 30.000 ms massimo. Uno step che lo supera fallisce. |
Dov'è il confine di sicurezza
Il linguaggio non è la minaccia: Starlark è isolato per progettazione — da solo non può né leggere un file, né raggiungere la rete, né iterare all'infinito. Il calcolo puro è innocuo.
L'unica vera capacità è il ponte tool(), ed è delimitato dall'allowlist applicata a runtime: il codice può chiamare solo gli strumenti che hai elencato (qualsiasi altra chiamata viene rifiutata), e ognuno porta con sé le proprie protezioni (protezione SSRF, fatturazione, audit, killswitch). L'allowlist si modifica liberamente quanto il codice: è con la scelta degli strumenti che definisci cosa uno step è autorizzato a fare.
Un'allowlist vuota = nessuna capacità di effetto collaterale: lo step si limita a calcolare sui suoi input e produce un output.
Quando usarlo
- Sì: logica deterministica che puoi descrivere con precisione, ma che supera le operazioni
computeintegrate (riconciliare più liste, regole di business composite, formati proprietari). - No: un semplice filtro, aggregazione o proiezione → un operator
computeè sufficiente. - No: un'attività che richiede giudizio o scrittura a testo libero → è un agent, non codice.