Named Variables

Named Variables turn your graph into a parameterized function. Instead of hardcoding values in node state, you can promote fields to input variables (function parameters) or output variables (return values) — making your agent or server graph reusable and composable.

How It Works

A Named Variable is a graph-level binding with a name, type, direction, and optional default value. Two core nodes interact with them:

Node	Type	What It Does
Get Variable	expression	Reads any variable — resolves to the Python variable name
Set Variable	statement	Writes any variable — generates an assignment

Creating Variables

There are three ways to create a variable:

• Promote a field — Right-click any promotable field on a node (temperature slider, prompt text, model selector) and choose "Promote to Input" or "Promote to Output". The field value becomes the variable's default, and the field shows a colored badge indicating it's bound to a variable.
• Variables Panel — Open the Variables panel in the sidebar and click + next to Inputs, Outputs, or Local to create a variable manually. Double-click the name to rename, the type dropdown to change type, or the = ... area to set a default value.
• Drag and drop — Drag any variable from the panel onto the canvas. A popup appears at the drop point letting you choose Get or Set — the node is created with the variable pre-selected.

What Gets Generated

Each direction maps to a different place in the generated code:

Direction	Codegen	Exposed in contract?
input	Function parameter on run()	Yes
output	Key in return dict	Yes
local	Initialized at top of run() body	No

# Without variables
class AgentRunner:
    def run(self, initial_input: str):
        ...
        return result

# With variables (temperature + context as inputs, score as output, scratch as local)
class AgentRunner:
    def run(self, initial_input: str, temperature: float = 0.7, context: str = ""):
        scratch = ""
        ...
        return {"result": result, "score": score}

Local variables are internal scratch state — use them for accumulators, loop counters, or intermediate results that don't need to be exposed to callers.

Variable Types

Primitive Types

Type	Python Type	Default
str	str	""
int	int	0
float	float	0.0
bool	bool	False

Collection Types

Collection types support inner type parameters. When you select a collection type, a secondary type picker appears for the element type(s).

Type	Python Type	Default	Inner Types
list	list	[]	Element type (e.g. list[int], list[str])
dict	dict	{}	Key + value types (e.g. dict[str, float])
tuple	tuple	()	Element types (e.g. tuple[int, str])
set	set	set()	Element type (e.g. set[str])

Special Types

Type	Python Type	Default	Notes
enum	str (Enum subclass)	First value	Define allowed values as a list of strings. Generates a class Name(str, Enum) at module scope.
any	Any	None	Accepts any value. Useful for pass-through or untyped data.
none	None	None	Explicitly no value.

Enum Variables

When a variable's type is set to enum, the Variables panel shows a value editor where you add, remove, and reorder the allowed string values. The default is the first value in the list.

In the generated code, an enum variable produces a Python Enum class:

class Status(str, Enum):
    IDLE = 'idle'
    RUNNING = 'running'
    DONE = 'done'

def run(self, initial_input: str, status: Status = Status.IDLE):
    ...

Parameterized Type Hints

When collection types have inner type parameters, the generated code includes full Python type hints:

# list[int] variable
def run(self, initial_input: str, scores: list[int] = []):
    ...

# dict[str, float] variable
def run(self, initial_input: str, weights: dict[str, float] = {}):
    ...

When to Use Variables vs. Other Approaches

Mechanism	When to Use
Input Variables	Parameterize your agent for callers — expose temperature, context, custom prompts as function args
Output Variables	Return structured results — score, summary, extracted data as a dict
Local Variables	Internal scratch state — accumulators, counters, buffers that don't leak into the contract
Persona Properties	Compile-time prompt injection — system prompt, constraints, tone baked into the generated code per persona variant
Human Input	CLI-only interactive agents — places a blocking input() call mid-flow for console-based multi-turn interaction
initial_input	The primary user message — always the first parameter on run()

Variables as Agent Contract

When an agent is imported into a Server Graph, the Agent Ref node's ports are derived from the agent's Named Variables — input variables become input ports, output variables become output ports. Local variables are not exposed. This means the Variables panel is the single source of truth for both codegen and federation.

Variables in Server Graphs

Server Graphs have their own variables array on the Server Graph Descriptor. These work the same way — Get Variable reads inputs, Set Variable writes outputs — but at the server level rather than the agent level.