Canvas Components

The Canvas provides 15 components divided into six functional categories. Each component has configuration parameters, produces outputs identifiable with variables, and serves a precise purpose in the flow.

Basic Flow

Basic flow components handle the entry point, logical branching, and final output to the user.

---

Begin

Function: Mandatory entry point of every Canvas. Defines how the flow is started and what initial data is available.

When to use: It is the first node of every Canvas. Every flow must have exactly one Begin node.

Parameter	Type	Description
mode	task | conversational	task: starts with a structured form. conversational: chat integration, automatically receives {{sys.query}}.
inputFields	Array	Only for task mode. Defines the input form fields.

Structure of an inputFields field:

Subfield	Type	Description
name	string	Field identifier, usable as {{sys.inputs.name}}
label	string	Label visible in the form
type	string | text | select | date | number	Field type
options	Array	Only for select: list of available options
required	boolean	Whether the field is required before launch
placeholder	string	Suggested text in the field

Available outputs:

Variable	Description
{{sys.query}}	User message text (conversational mode)
{{sys.inputs.fieldName}}	Value of a form field (task mode)
{{sys.user_id}}	Current user ID
{{sys.company_id}}	Current company ID
{{sys.conversation_id}}	Current conversation ID
{{sys.timestamp}}	Flow start timestamp (ISO 8601)

Example — Insurance form:

mode: task
inputFields:
  - name: claimType
    label: Claim Type
    type: select
    options: [Auto, Life, Home, Liability, Other]
    required: true
  - name: claimDate
    label: Date of Incident
    type: date
    required: true
  - name: description
    label: Description of Event
    type: text
    required: true
    placeholder: Describe the incident in detail
  - name: policyNumber
    label: Policy Number
    type: string
    required: true

---

Message

Function: Output node that presents the final result to the user. It is the terminal node of a flow or a branch.

When to use: At the end of every branch of the flow to show a response. A flow can have multiple Message nodes (one for each Switch branch).

Parameter	Type	Description
content	string	Content to display. Accepts variables like {{llm_1.content}}. Can be static text.
format	markdown | plain	Text rendering format. Use markdown for LLM responses.
showCitations	boolean	Whether to show source badges and [N] citations. Default: true.

Available outputs: The Message node does not produce variable outputs (it is a terminal node).

Example — Static response for out-of-scope topics:

content: |
  I'm sorry, this question falls outside the scope
  of the current assistant. For requests of this type,
  please contact the relevant team directly.
format: markdown
showCitations: false

Example — Dynamic response from LLM:

content: "{{llm_1.content}}"
format: markdown
showCitations: true

---

Switch

Function: Routing node that evaluates logical conditions and directs execution toward different branches.

When to use: When the flow must behave differently based on a category, a keyword in a response, or a field value.

Parameter	Type	Description
conditions	Array	List of conditions evaluated in order. The first true one is followed.
elseGoto	string	ID of the node to reach if no condition is true.

Structure of a condition:

Subfield	Type	Description
variable	string	Variable to evaluate (e.g. {{categorize_1.category}})
operator	string	Comparison operator (see table below)
value	string	Value to compare against
goto	string	ID of the destination node if the condition is true

Available operators:

Operator	Meaning
equals	Equal to (case-insensitive)
not_equals	Not equal to
contains	Contains the string
not_contains	Does not contain the string
starts_with	Starts with
ends_with	Ends with
greater_than	Greater than (numeric)
less_than	Less than (numeric)
is_empty	Value is empty or null
is_not_empty	Value is not empty

Available outputs: The Switch node does not produce variable outputs; it only handles routing.

Example — Routing by category:

conditions:
  - variable: "{{categorize_1.category}}"
    operator: equals
    value: "Technical"
    goto: llm_technical
  - variable: "{{categorize_1.category}}"
    operator: equals
    value: "Commercial"
    goto: llm_commercial
elseGoto: message_generic

---

Artificial Intelligence

Components that involve language models and information retrieval.

---

LLM

Function: Calls a language model with a configurable prompt and produces text output. It is the primary component for generating responses, analyses, classifications, and text transformations.

When to use: To generate responses for the user, analyze retrieved content, synthesize information, or classify text in freeform mode.

Parameter	Type	Description
model	writer | planner	writer: Qwen3-80B, articulate responses and deep reasoning. planner: Qwen3-30B, fast classifications and simple tasks.
systemPrompt	string	Context instructions for the model (persona, rules, output format). Accepts variables.
userPrompt	string	The actual request text to the model. Accepts variables.
temperature	number	Response creativity. 0.1-0.3 for factual answers, 0.7-0.9 for creative text. Default: 0.3.
maxTokens	number	Maximum response length in tokens. Default: 2048. Max: 8192.
jsonMode	boolean	If true, the model produces a valid JSON object. Useful for extracting structured data. Default: false.

Available outputs:

Variable	Description
{{llm_N.content}}	Full text generated by the model
{{llm_N.usage.promptTokens}}	Tokens used in the prompt
{{llm_N.usage.completionTokens}}	Tokens used in the response

Example — Analysis with JSON Mode:

model: planner
systemPrompt: |
  You are a classifier. Respond ONLY with valid JSON,
  no additional text.
userPrompt: |
  Classify this text as POSITIVE, NEGATIVE or NEUTRAL.
  Text: {{sys.query}}

  Respond with: {"sentiment": "POSITIVE|NEGATIVE|NEUTRAL", "confidence": 0.0-1.0}
temperature: 0.1
jsonMode: true

Example — Document analysis:

model: writer
systemPrompt: |
  You are a senior insurance assessor. Analyze the provided documentation
  and deliver a detailed technical assessment.
  Always cite sources with [N]. Respond in English.
userPrompt: |
  Claim type: {{sys.inputs.claimType}}
  Date: {{sys.inputs.claimDate}}

  Policy and applicable regulatory documents:
  {{retrieval_1.formalized_content}}

  Event description:
  {{sys.inputs.description}}

  Provide: 1) Coverage assessment 2) Applicable regulations 3) Additional documentation required
temperature: 0.2
maxTokens: 4096

---

Retrieval

Function: Performs a hybrid search (semantic + full-text) across company documents, the Knowledge Base, and enabled external sources. Returns the passages most relevant to the query.

When to use: Whenever the flow needs documentary context. It is the node that connects user questions to the organization's information assets.

Parameter	Type	Description
query	string	Search text. Use {{sys.query}} or a processed variable. Accepts static text combined with variables.
topK	number	Maximum number of passages to retrieve. Range: 5-50. Default: 10.
scoreThreshold	number	Minimum relevance threshold (0.0-1.0). Passages below threshold are excluded. Default: 0.5.
useReranking	boolean	Whether to apply the BGE reranker to reorder results. Recommended for quality. Default: true.
companyDocs	boolean	Search in uploaded company documents. Default: true.
knowledgeBase	boolean	Search in the curated Knowledge Base. Default: true.
legalSources	boolean	Search in Normattiva (Italian and European regulatory sources). Default: false.
foodSources	boolean	Search in Open Food Facts (food products). Default: false.
chemSources	boolean	Search in ECHA/REACH (chemicals, SDS). Default: false.
pharmaSources	boolean	Search in FDA/ClinicalTrials/PubMed (drugs, trials, publications). Default: false.
aeSources	boolean	Search in Agenzia delle Entrate (Italian tax regulations). Default: false.
topicIds	Array	List of topic IDs to limit the search to specific categories. Optional.

Available outputs:

Variable	Description
{{retrieval_N.formalized_content}}	Formatted text of found passages, ready for an LLM prompt. Includes titles and references.
{{retrieval_N.results}}	JSON array of full results with score, metadata, source.
{{retrieval_N.count}}	Number of passages retrieved.

Example — Multi-source legal search:

query: "{{sys.inputs.claimType}} insurance policy coverage {{sys.inputs.description}}"
topK: 20
useReranking: true
companyDocs: true
knowledgeBase: true
legalSources: true

---

Categorize

Function: Classifies input text into one of the predefined categories using a fast LLM model. Automatically routes execution to the corresponding branch.

When to use: For intelligent routing based on question content, without rigid conditions. More robust than Switch for semantic categorization.

Parameter	Type	Description
input	string	Text to classify. Usually {{sys.query}}.
categories	Array	List of categories with label, description, and destination node.
minConfidence	number	Minimum required confidence. If classification falls below this threshold, the other category is used. Default: 0.6.

Structure of a category:

Subfield	Type	Description
name	string	Category name (used as the output value)
description	string	Description to help the model classify correctly
goto	string	ID of the destination node for this category

Available outputs:

Variable	Description
{{categorize_N.category}}	Name of the assigned category
{{categorize_N.confidence}}	Classification confidence (0.0-1.0)
{{categorize_N.reasoning}}	Brief explanation of the classification

Example — Routing by question type:

input: "{{sys.query}}"
minConfidence: 0.65
categories:
  - name: Technical
    description: Questions about products, technical specifications, manuals, installations, faults
    goto: llm_technical
  - name: Commercial
    description: Questions about prices, offers, contracts, promotions, availability
    goto: llm_commercial
  - name: Regulatory
    description: Questions about laws, regulations, certifications, legal obligations
    goto: retrieval_regulatory
  - name: Other
    description: Questions not relevant to the company's scope
    goto: message_out_of_scope

---

Agent

Function: Executes an autonomous ReAct (Reasoning + Acting) cycle. The model decides which tool to use, calls it, evaluates the result, and decides whether further steps are needed or the response is complete.

When to use: For tasks that require multi-step reasoning not determinable in advance. Agent is more flexible than a fixed sequence but slower. Use the writer model for maximum quality.

Parameter	Type	Description
systemPrompt	string	Description of the role and instructions for the agent.
userPrompt	string	The task to execute. Accepts variables.
tools	Array	List of available tools (see table below).
maxRounds	number	Maximum number of ReAct iterations. Default: 5. Max: 10.
model	writer | planner	Model to use. writer for complex tasks.

Available tools:

Tool ID	Description
retrieval	Search in company documents and KB
legal_search	Search in Legal Sources (Normattiva)
pharma_search	Search in Pharma Sources (FDA/PubMed)
food_search	Search in Food Sources (Open Food Facts)
chem_search	Search in Chem Sources (ECHA/REACH)
graph_query	Query the Neo4j graph (entities and relationships)

Available outputs:

Variable	Description
{{agent_N.content}}	Final response produced by the agent
{{agent_N.steps}}	JSON array of ReAct steps executed
{{agent_N.toolCalls}}	Total number of tool calls made

Example:

systemPrompt: |
  You are an expert researcher in European food regulations.
  Use the available tools to answer precisely,
  always citing regulatory sources.
userPrompt: "{{sys.query}}"
tools: [retrieval, food_search, legal_search]
maxRounds: 6
model: writer

---

User Interaction

---

UserFillUp

Function: Suspends flow execution and displays a form to the user to collect additional information. When the user submits the form, execution resumes from the next point.

When to use: When the flow needs documents, data, or clarifications that were not available at startup. Typical in claim management, audit, or due diligence flows.

Parameter	Type	Description
message	string	Message shown to the user before the form. Explains what is needed and why. Accepts variables.
fields	Array	Form fields (same structure as Begin inputFields, with addition of type: file).
tips	string	Optional tips shown below the form (e.g. "Accepts PDF, JPG, PNG up to 10MB").

Additional field type for UserFillUp:

Type	Description
file	File upload. Supports PDF, DOCX, images. The file is vectorized and available as a temporary document.

Available outputs:

Variable	Description
{{userfillup_N.inputs.fieldName}}	Value of the field filled in by the user
{{userfillup_N.inputs.fileName}}	Reference to the uploaded file (if type: file)

Example:

message: |
  The initial documentation is not sufficient to confirm
  coverage. We ask you to provide the following documents:
fields:
  - name: damagePictures
    label: Photos of the damage
    type: file
    required: true
  - name: appraisal
    label: Technical appraisal (if available)
    type: file
    required: false
  - name: notes
    label: Additional notes
    type: text
    required: false
    placeholder: Additional information about the incident
tips: "Accepted formats: PDF, JPG, PNG, DOCX. Maximum size: 20MB per file."

---

Data Manipulation

Components for transforming, combining, and filtering data within the flow.

---

VariableAssigner

Function: Creates or transforms variables by combining existing values. Useful for building composed texts, merging arrays, or preparing data for subsequent nodes.

When to use: To build query strings from multiple inputs, merge outputs from different nodes, or prepare structured data.

Parameter	Type	Description
assignments	Array	List of variable → value assignments.

Structure of an assignment:

Subfield	Type	Description
name	string	Name of the output variable
type	concat | merge | array | custom	Operation type
value	string / Array	Value or template. For concat: string with variables. For merge: objects to merge. For array: list of values.

Available outputs:

Variable	Description
{{variableassigner_N.variableName}}	Value assigned to the defined variable

Available operations:

Type	Use
concat	Concatenates strings and variables into a single text
merge	Merges JSON objects
array	Creates an array from a list of values
custom	Freeform transformation expression

Example — Building a composed query:

assignments:
  - name: fullQuery
    type: concat
    value: "Claim {{sys.inputs.claimType}} on {{sys.inputs.claimDate}}: {{sys.inputs.description}}"

---

VariableAggregator

Function: Collects the first non-empty value from multiple variable sources. Useful for handling fallbacks when a node may not produce output.

When to use: When multiple branches of the flow can produce a result and you want to pass the first available one to the next node.

Parameter	Type	Description
sources	Array	List of variables to check in order. The first non-empty one is used.
outputName	string	Name of the aggregated output variable.

Available outputs:

Variable	Description
{{variableaggregator_N.outputName}}	First non-empty value among the sources

Example — Fallback between two LLMs:

sources:
  - "{{llm_writer.content}}"
  - "{{llm_planner.content}}"
outputName: finalResponse

---

DataOperations

Function: Applies transformations on arrays and texts: filter, map, sort, slice, extract, join, split, deduplicate.

When to use: To process lists of results (e.g. filter clinical trials by phase, extract only titles, deduplicate by ID).

Parameter	Type	Description
input	string	Input variable to process (typically a JSON array).
operation	string	Type of operation to apply (see table).
params	object	Operation-specific parameters.

Available operations:

Operation	Description	Key parameters
filter	Filters elements that satisfy a condition	field, operator, value
map	Transforms each element by extracting a field	field
sort	Sorts by a field	field, direction (asc/desc)
slice	Takes a portion of the array	start, end
extract	Extracts a field from each object	field
join	Joins array elements into a string	separator
split	Splits a string into an array	separator
deduplicate	Removes duplicates	field (key field for dedup)

Available outputs:

Variable	Description
{{dataoperations_N.result}}	Result of the operation
{{dataoperations_N.count}}	Number of resulting elements

Example — Filtering clinical trials by phase:

input: "{{retrieval_1.results}}"
operation: filter
params:
  field: metadata.phase
  operator: contains
  value: "Phase 3"

---

Loops

Components for iterating over lists of elements or repeating blocks until a condition is met.

---

Iteration

Function: Iterates over each element of an array, executing a sub-sequence of nodes for each one.

When to use: To process a list of elements one by one — for example analyzing each clinical trial found, or processing each document in a list.

Parameter	Type	Description
input	string	Array variable to iterate over.
iterationNodeIds	Array	List of node IDs to execute for each element.

Context variables available during iteration:

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

Available outputs:

Variable	Description
{{iteration_N.results}}	Array with the results of each iteration
{{iteration_N.count}}	Number of completed iterations

Example — Analyzing each clinical trial:

input: "{{dataoperations_1.result}}"
iterationNodeIds: [llm_trial_analysis]

Inside llm_trial_analysis, use {{iter.item.title}}, {{iter.item.phase}}, etc.

---

Loop

Function: Repeats a block of nodes while a condition is true or until the maximum number of iterations is reached. Useful for iterative refinement or in-depth searching.

When to use: For refinement processes where you do not know in advance how many iterations are needed — for example progressive searching until you find the answer or reach the desired confidence.

Parameter	Type	Description
condition	string	Boolean expression: the loop continues while it is true. Accepts variables.
maxIterations	number	Maximum iteration limit to avoid infinite loops. Default: 5. Max: 20.
loopNodeIds	Array	List of node IDs to execute at each iteration.

Context variables available during the loop:

Variable	Description
{{loop.iteration}}	Current iteration number (1-based)
{{loop.previousResult}}	Output of the previous iteration

Available outputs:

Variable	Description
{{loop_N.finalResult}}	Result of the last executed iteration
{{loop_N.iterations}}	Total number of iterations executed
{{loop_N.exitedEarly}}	true if the loop exited via ExitLoop

---

ExitLoop

Function: Immediately exits the current Loop, even if the Loop condition is still true. Positioned inside the Loop's node block.

When to use: To exit the loop when a specific condition is met before reaching maxIterations — for example when confidence is sufficient.

Parameter	Type	Description
condition	string	Exits the loop if this condition is true. If omitted, always exits when reached.

Example — Loop with early exit:

Loop (condition: "{{llm_eval.confidence}} < 0.8", maxIterations: 4)
  → Retrieval (refined query)
  → LLM (confidence evaluation)
  → ExitLoop (condition: "{{llm_eval.confidence}} >= 0.8")

---

Composition

---

Invoke

Function: Executes another Canvas as a sub-flow. Allows reusing existing flows as modular building blocks.

When to use: To decompose complex flows into reusable modules, or to call a specialized Canvas (e.g. a legal analyzer) from multiple different Canvases.

Parameter	Type	Description
canvasId	string	ID of the Canvas to invoke.
inputMapping	object	Map between variables of the current Canvas and inputs expected by the sub-Canvas.
timeout	number	Timeout in milliseconds for sub-Canvas completion. Default: 30000.

Available outputs:

Variable	Description
{{invoke_N.output}}	Complete output of the sub-Canvas
{{invoke_N.status}}	success | error | timeout

Example — Invoking a legal analyzer:

canvasId: "canvas_legal_analysis_abc123"
inputMapping:
  query: "{{sys.inputs.contractType}} {{sys.inputs.description}}"
  topicId: "legal"
timeout: 45000

---

Output Summary by Component

Component	Main Output Variable
Begin	{{sys.query}}, {{sys.inputs.field}}
LLM	{{llm_N.content}}
Retrieval	{{retrieval_N.formalized_content}}, {{retrieval_N.results}}
Categorize	{{categorize_N.category}}, {{categorize_N.confidence}}
Agent	{{agent_N.content}}
UserFillUp	{{userfillup_N.inputs.field}}
Switch	(no output, routing only)
Message	(no output, terminal node)
VariableAssigner	{{variableassigner_N.varName}}
VariableAggregator	{{variableaggregator_N.outputName}}
DataOperations	{{dataoperations_N.result}}
Iteration	{{iteration_N.results}}
Loop	{{loop_N.finalResult}}
ExitLoop	(no output, manages the loop)
Invoke	{{invoke_N.output}}

Automatic node names

The Canvas automatically assigns names to nodes (llm_1, retrieval_2, etc.) based on type and insertion order. You can see the assigned name in the node header in the workspace. The name is used as the namespace in variables.

---

Queria v3.1.2 -- Canvas Agent Builder