Variables and References

Variables are the mechanism by which Canvas nodes exchange data. Every value produced by a component — generated text, search results, categories, user input — is accessible in subsequent nodes through a variable reference.

Syntax

The syntax for referring to a variable is:

{{namespace.path}}

• Double braces: delimit the reference.
• namespace: identifies the source of the value (the node that produced it, or a system namespace).
• path: the name of the output key, optionally with dot notation for nested objects.

Examples:

{{sys.query}}                        → user question text
{{llm_1.content}}                    → response from the first LLM node
{{retrieval_1.formalized_content}}   → text retrieved by Retrieval
{{categorize_1.category}}            → category assigned by Categorize
{{sys.inputs.claimType}}             → value of the "claimType" field from the Begin form

Variables are interpreted everywhere in the Canvas: in prompts, Switch conditions, configuration parameters, and UserFillUp messages.

Type Preservation

Variables preserve the type of the original value:

Type	Example	Notes
String	{{llm_1.content}}	Plain text or Markdown
Number	{{retrieval_1.count}}	Integer
Float	{{categorize_1.confidence}}	Decimal number
Boolean	{{loop_1.exitedEarly}}	true / false
Array	{{retrieval_1.results}}	JSON array
Object	{{iter.item}}	JSON object

When an Array or Object variable is inserted into text (for example in a prompt), it is automatically serialized as JSON. To access specific properties use dot notation:

{{retrieval_1.results.0.content}}       → first element of the array, field "content"
{{iter.item.metadata.phase}}            → field "phase" inside "metadata" of the current element

System Namespace (sys)

The sys namespace contains global variables available in any node of the flow, regardless of execution order.

Variable	Type	Description
{{sys.query}}	string	User message text (conversational mode)
{{sys.user_id}}	string	Authenticated user ID
{{sys.company_id}}	string	Company ID of the current tenant
{{sys.conversation_id}}	string	Current conversation ID
{{sys.timestamp}}	string	ISO 8601 flow start timestamp (e.g. 2026-03-29T14:30:00.000Z)
{{sys.inputs.fieldName}}	any	Value of a Begin form field (task mode)

sys.query vs sys.inputs

In conversational mode, the user's text is always in {{sys.query}}. In task mode, form data is in {{sys.inputs.fieldName}}, while {{sys.query}} may be empty or contain a generic startup text.

Component Namespaces

Each Canvas node exposes its outputs in the namespace identified by its node ID. The ID is visible in the node header in the workspace (e.g. llm_1, retrieval_2, categorize_1).

LLM Node Outputs

{{llm_N.content}}                   → generated text
{{llm_N.usage.promptTokens}}        → tokens in the prompt
{{llm_N.usage.completionTokens}}    → tokens in the response
{{llm_N.usage.totalTokens}}         → total tokens

Retrieval Node Outputs

{{retrieval_N.formalized_content}}  → formatted text ready for LLM prompt
{{retrieval_N.results}}             → JSON array of full results
{{retrieval_N.count}}               → number of results

Structure of each object in retrieval_N.results:

{
  "content": "Passage text...",
  "score": 0.87,
  "sourceType": "document",
  "documentTitle": "Policy RCA 2025.pdf",
  "sectionTitle": "Article 5 - Exclusions",
  "metadata": {
    "documentId": "...",
    "chunkIndex": 3,
    "pageNumber": 12
  }
}

Categorize Node Outputs

{{categorize_N.category}}           → assigned category name
{{categorize_N.confidence}}         → confidence 0.0-1.0
{{categorize_N.reasoning}}          → brief explanation of the choice

Agent Node Outputs

{{agent_N.content}}                 → final processed response
{{agent_N.steps}}                   → array of ReAct steps
{{agent_N.toolCalls}}               → number of tool calls executed

UserFillUp Node Outputs

{{userfillup_N.inputs.fieldName}}   → value of the filled field

VariableAssigner Node Outputs

{{variableassigner_N.varName}}      → value of the assigned variable

VariableAggregator Node Outputs

{{variableaggregator_N.outputName}} → first non-empty value among sources

DataOperations Node Outputs

{{dataoperations_N.result}}         → result of the operation
{{dataoperations_N.count}}          → number of resulting elements

Iteration Node Outputs

{{iteration_N.results}}             → array with the output of each iteration
{{iteration_N.count}}               → number of completed iterations

Loop Node Outputs

{{loop_N.finalResult}}              → result of the last iteration
{{loop_N.iterations}}               → number of iterations executed
{{loop_N.exitedEarly}}              → true if exited via ExitLoop

Invoke Node Outputs

{{invoke_N.output}}                 → complete output of the sub-Canvas
{{invoke_N.status}}                 → "success" | "error" | "timeout"

Loop Context Variables

Loop context variables are only available inside the nodes that are part of the loop itself.

Iteration Context

Variable	Type	Description
{{iter.item}}	any	Current element of the array being iterated
{{iter.index}}	number	Current index (0-based)
{{iter.total}}	number	Total number of elements in the array

Accessing element properties:

{{iter.item.title}}
{{iter.item.metadata.phase}}
{{iter.item.score}}

Loop Context

Variable	Type	Description
{{loop.iteration}}	number	Current iteration number (1-based)
{{loop.previousResult}}	any	Output of the previous iteration (null on first)

Practical Examples

Passing document context to an LLM

The most common pattern: Retrieval → LLM.

# LLM node User Prompt configuration
userPrompt: |
  Relevant retrieved documents:
  {{retrieval_1.formalized_content}}

  User question:
  {{sys.query}}

  Respond in detail, citing sources with [N].

Using Categorize output in a prompt

After a Categorize node, you can use the category in the LLM prompt to personalize the response.

# In the prompt of an LLM following Categorize
systemPrompt: |
  You are an expert in {{categorize_1.category}}.
  (The question was classified as: {{categorize_1.category}}
  with confidence {{categorize_1.confidence}})

userPrompt: |
  {{sys.query}}

Building an enriched query from form input

With a Begin form that collects type and description:

# Query in the Retrieval node
query: "{{sys.inputs.claimType}} policy coverage {{sys.inputs.description}} date {{sys.inputs.claimDate}}"

Accessing nested JSON

If retrieval_1.results is an array of objects, you can access the first element:

# First search result
"{{retrieval_1.results.0.documentTitle}}"
"{{retrieval_1.results.0.content}}"
"{{retrieval_1.results.0.score}}"

Inside an Iteration, you can access the properties of the current element:

# Inside an Iteration iterating over retrieval_1.results
userPrompt: |
  Analyze this passage from document "{{iter.item.documentTitle}}":
  {{iter.item.content}}
  (Relevance: {{iter.item.score}})

Combining outputs from multiple nodes

With VariableAssigner you can build a text composed from multiple sources:

assignments:
  - name: fullContext
    type: concat
    value: |
      ## Company Information
      {{retrieval_docs.formalized_content}}

      ## Applicable Regulations
      {{retrieval_legal.formalized_content}}

      ## Form Data
      Type: {{sys.inputs.type}}
      Date: {{sys.inputs.date}}

Then in the LLM prompt:

userPrompt: |
  {{variableassigner_1.fullContext}}

  Question: {{sys.query}}

Switch condition based on LLM output

You can use the output of an LLM (with jsonMode) as a Switch condition:

# LLM with jsonMode: true produces {"verdict": "CONFIRMED", "confidence": 0.92}
# In the Switch:
conditions:
  - variable: "{{llm_analysis.content}}"
    operator: contains
    value: '"verdict": "CONFIRMED"'
    goto: message_positive
  - variable: "{{llm_analysis.content}}"
    operator: contains
    value: '"verdict": "NOT_CONFIRMED"'
    goto: userfillup_documents
elseGoto: message_generic

Value Resolution

The Canvas resolves variables only when the node that produced them has already completed execution. If you try to use a variable from a node not yet executed, the value will be undefined.

The engine automatically guarantees the correct order thanks to the DAG structure: a node receives control only after all its predecessors in the graph have finished.

Undefined variables

If a variable is used in a prompt but its value is undefined (node not yet executed or node that produced no output), the resulting text will contain the literal {{variable.name}} unsubstituted. Check the debug panel during tests to verify that all variables are populated correctly.

env namespace

The {{env.variableName}} namespace is reserved for environment variables defined at the Canvas level (configurable from the Canvas settings section). Useful for keys, URLs, or parameters that should not be hard-coded in the flow.

---

Queria v3.1.2 -- Canvas Agent Builder