Component Variable Propagation#

Variable propagation is the mechanism by which a canvas component's output values are stored in a shared state bag (CanvasState) and made available to downstream components via a {{cpn_id@variable}} reference syntax. It is the primary data-flow channel across an agent pipeline's DAG.

Reference Syntax#

Variable references take one of four forms 1:

cpn_id is a DSL-assigned identifier such as begin_0, llm_0, or cpn_0. The iteration aliases {{item}} and {{index}} are also recognized and map to Globals["__item__"] / Globals["__index__"] 2.

The regex is defined in both the Go runtime and the Python base class — they must stay byte-for-byte identical:

• Go: VarRefPattern in internal/agent/runtime/template.go
• Python: variable_ref_patt in agent/component/base.py

CanvasState — the central store#

CanvasState (in internal/agent/runtime/state.go) is the per-run shared bag:

• Outputs map[string]map[string]any — the primary variable store: Outputs[cpn_id][param_name] = value
• Sys, Env, Globals — system variables, env constants, and loop/global aliases
• History, Retrieval — conversation history and aggregated retrieval chunks
• CancelFlag, RunID, TaskID — run lifecycle metadata

All maps are guarded by a single sync.RWMutex 3. CanvasState is registered with eino's type registry so it round-trips through checkpoint/resume paths 4.

Key accessors:

How outputs are written#

Python side: each component calls set_output(key, value), which stores {value, type} in self._param.outputs[key]. For example, UserFillUp calls self.set_output(k, resolved) for each form field it processes 5. After invocation, the canvas persists each component's output() dict back into the shared graph state.

Go side: the eino statePost handler in scheduler.go flattens every key in a node's output map directly into Outputs[cpnID][key] 6, mirroring the Python convention so {{cpnID@key}} references work identically. Metadata keys (__cpn_id__, state, __legacy_noop__) are skipped.

How references are resolved#

Template resolution (Go): ResolveTemplate(s, state) replaces every {{...}} in a string with its current CanvasState value. Unresolvable refs are loud errors to surface misconfigured canvases early. ResolveTemplateForDisplay is the soft-fail variant (unresolved → ""), mirroring canvas.py's display path.

Python side: get_variable_value(exp) splits cpn_id@var_nm, fetches the component's output(root_key), then calls get_variable_param_value for any dot-path traversal. Traversal handles dict, list/tuple (integer index), JSON strings (auto-parsed once), and object attributes. get_value_with_variable handles mixed strings containing multiple references.

For parameter binding, get_input() on ComponentBase detects whether an input value is a bare reference (is_reff) or a templated string, resolves accordingly, and stores the result via set_input_value.

Lifecycle in the scheduler#

The eino scheduler wires statePre and statePost onto every node as graph options 7:

1. statePre — before a node runs, injects a snapshot of all current Outputs into the input map under "state", and syncs eino's local state into the context-attached CanvasState 8.
2. statePost — after a node runs, writes each output key into both the eino-local state and the context CanvasState via SetVar 6.

This double-write ensures that components reading state via runtime.GetStateFromContext (e.g. Begin, Message, LLM) always see upstream outputs regardless of which state object they hold.

Key files#