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 an input variable — resolves to the Python function parameter name
Set Variable	statement	Writes an output variable — generates an assignment to the return value

Creating Variables

There are two 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+ Input or + Output to create a variable manually. Then drop a Get Variable or Set Variable node on the canvas and select the variable from its dropdown.

What Gets Generated

Input variables become typed parameters on the agent's run() method. Output variables become keys in the return dict.

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

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

Variable Types

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

When to Use Variables vs. Other Approaches

Mechanism	When to Use
Named Variables	Parameterize your agent for callers — expose temperature, context, custom prompts as function args
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 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.