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, e viene eseguito non appena viene salvato.
Il modello di esecuzione
code_step esegue Starlark — un dialetto di Python progettato per l'isolamento: nessun accesso al filesystem, nessuna rete, nessun import arbitrario, 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 | Gli strumenti chiamabili tramite tool(name, args). Ogni chiamata eredita le protezioni proprie dello strumento (protezione SSRF, fatturazione, audit, killswitch). |
| Chiave di output | Dove porre il risultato nel contesto. I nodi a valle leggono questa chiave. |
| Budget di esecuzione | Tetto di tempo (ms), limitato lato server. Uno step che lo supera viene interrotto. |
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, e ognuno porta con sé le proprie protezioni (protezione SSRF, fatturazione, audit, killswitch). Questo — la scelta degli strumenti — è dove 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.