Using variables

When building complex behavior graphs, you often need to carry data from one part of the graph to another, keep track of counters inside loops, or store intermediate results.

Variables allow you to store and read temporary data within a behavior graph. They are run-scoped, meaning they only exist for the duration of a single execution and are cleared when the behavior finishes.

Setting variables

Use the Set Variable node to store one or more values:

• Variables: A list of variable entries to set. For each entry:
  • Key: The name of the variable (e.g. "myCounter").
  • Value: Any valid JSON expression (e.g. 0, true, "inProgress", or { "attempts": 1 }).

You can also store the output of another node by using its reference, such as llm.outputText.

Reading a variable

Using $variables

The built-in $variables object is automatically available in all expressions and template strings:

• Expression: $variables.myCounter + 1
• Template String: The current status is: {{$variables.status}}

You can also access nested properties on JSON objects natively, like $variables.myObject.metadata.source.

Using the Get Variable node

You can also use the Get Variable node if you want to visually represent the retrieval or define a fallback if the variable is not defined.

Example: tracking background state

While the Loop node provides a built-in index for simple loops, variables are essential when your state updates independently of how many times a loop has run.

A powerful use case is processing an active background stream. Imagine you want to split a streaming LLM response into separate chat messages as they arrive:

1. Initialize: Set a "processedCount" variable to 0.
2. Poll: Inside a loop, read the current accumulated stream text, then split it into an array of segments.
3. Compare: Check if the length of the segments array is greater than $variables.processedCount.
4. Process & Update: If true, process the new segment, increment processedCount, and route back to step 2. If false, wait a short duration and route back to step 2 without incrementing.

In this scenario, the loop might run dozens of times before a new segment is ready. The processedCount variable safely tracks your progress regardless of the loop's own execution count.