Variabili e Riferimenti

Le variabili sono il meccanismo con cui i nodi del Canvas si scambiano dati. Ogni valore prodotto da un componente — testo generato, risultati di ricerca, categorie, input utente — e accessibile nei nodi successivi attraverso un riferimento variabile.

Sintassi

La sintassi per riferirsi a una variabile e:

{{namespace.path}}

• Doppie graffe: delimitano il riferimento.
• namespace: identifica la sorgente del valore (il nodo che lo ha prodotto, o un namespace di sistema).
• path: il nome della chiave di output, eventualmente con notazione a punti per oggetti annidati.

Esempi:

{{sys.query}}                        → testo della domanda utente
{{llm_1.content}}                    → risposta del primo nodo LLM
{{retrieval_1.formalized_content}}   → testo recuperato dal Retrieval
{{categorize_1.category}}            → categoria assegnata dal Categorize
{{sys.inputs.tipoSinistro}}          → valore del campo "tipoSinistro" dal form Begin

Le variabili sono interpretate ovunque nel Canvas: nei prompt, nelle condizioni Switch, nei parametri di configurazione, nei messaggi UserFillUp.

Preservazione del Tipo

Le variabili preservano il tipo del valore originale:

Tipo	Esempio	Note
String	{{llm_1.content}}	Testo semplice o Markdown
Number	{{retrieval_1.count}}	Numero intero
Float	{{categorize_1.confidence}}	Numero decimale
Boolean	{{loop_1.exitedEarly}}	true / false
Array	{{retrieval_1.results}}	Array JSON
Object	{{iter.item}}	Oggetto JSON

Quando una variabile di tipo Array o Object viene inserita in un testo (ad esempio in un prompt), viene serializzata automaticamente in JSON. Per accedere a proprieta specifiche usa la notazione a punti:

{{retrieval_1.results.0.content}}       → primo elemento dell'array, campo "content"
{{iter.item.metadata.phase}}            → campo "phase" dentro "metadata" dell'elemento corrente

Namespace di Sistema (sys)

Il namespace sys contiene variabili globali disponibili in qualsiasi nodo del flusso, indipendentemente dall'ordine di esecuzione.

Variabile	Tipo	Descrizione
{{sys.query}}	string	Testo del messaggio utente (mode conversational)
{{sys.user_id}}	string	ID utente autenticato
{{sys.company_id}}	string	ID azienda del tenant corrente
{{sys.conversation_id}}	string	ID conversazione corrente
{{sys.timestamp}}	string	Timestamp ISO 8601 di avvio del flusso (es. 2026-03-29T14:30:00.000Z)
{{sys.inputs.nomeField}}	any	Valore di un campo del form Begin (mode task)

sys.query vs sys.inputs

In mode conversational, il testo dell'utente e sempre in {{sys.query}}. In mode task, i dati del form sono in {{sys.inputs.nomeCampo}}, mentre {{sys.query}} potrebbe essere vuoto o contenere un testo di avvio generico.

Namespace Componenti

Ogni nodo del Canvas espone i propri output nel namespace identificato dal suo ID nodo. L'ID e visibile nell'header del nodo nel workspace (es. llm_1, retrieval_2, categorize_1).

Output Nodo LLM

{{llm_N.content}}                   → testo generato
{{llm_N.usage.promptTokens}}        → token nel prompt
{{llm_N.usage.completionTokens}}    → token nella risposta
{{llm_N.usage.totalTokens}}         → token totali

Output Nodo Retrieval

{{retrieval_N.formalized_content}}  → testo formattato pronto per prompt LLM
{{retrieval_N.results}}             → array JSON dei risultati completi
{{retrieval_N.count}}               → numero di risultati

La struttura di ogni oggetto in retrieval_N.results:

{
  "content": "Testo del passaggio...",
  "score": 0.87,
  "sourceType": "document",
  "documentTitle": "Polizza RCA 2025.pdf",
  "sectionTitle": "Articolo 5 - Esclusioni",
  "metadata": {
    "documentId": "...",
    "chunkIndex": 3,
    "pageNumber": 12
  }
}

Output Nodo Categorize

{{categorize_N.category}}           → nome categoria assegnata
{{categorize_N.confidence}}         → confidenza 0.0-1.0
{{categorize_N.reasoning}}          → breve spiegazione della scelta

Output Nodo Agent

{{agent_N.content}}                 → risposta finale elaborata
{{agent_N.steps}}                   → array dei passi ReAct
{{agent_N.toolCalls}}               → numero di tool call eseguite

Output Nodo UserFillUp

{{userfillup_N.inputs.nomeCampo}}   → valore del campo compilato

Output Nodo VariableAssigner

{{variableassigner_N.nomeVar}}      → valore della variabile assegnata

Output Nodo VariableAggregator

{{variableaggregator_N.outputName}} → primo valore non vuoto tra le sorgenti

Output Nodo DataOperations

{{dataoperations_N.result}}         → risultato dell'operazione
{{dataoperations_N.count}}          → numero di elementi risultanti

Output Nodo Iteration

{{iteration_N.results}}             → array con l'output di ogni iterazione
{{iteration_N.count}}               → numero di iterazioni completate

Output Nodo Loop

{{loop_N.finalResult}}              → risultato dell'ultima iterazione
{{loop_N.iterations}}               → numero di iterazioni eseguite
{{loop_N.exitedEarly}}              → true se uscito per ExitLoop

Output Nodo Invoke

{{invoke_N.output}}                 → output completo del sub-Canvas
{{invoke_N.status}}                 → "success" | "error" | "timeout"

Variabili di Contesto nei Cicli

Le variabili di contesto dei cicli sono disponibili solo all'interno dei nodi che fanno parte del ciclo stesso.

Contesto Iteration

Variabile	Tipo	Descrizione
{{iter.item}}	any	Elemento corrente dell'array in iterazione
{{iter.index}}	number	Indice corrente (base 0)
{{iter.total}}	number	Numero totale di elementi nell'array

Accesso a proprieta dell'elemento:

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

Contesto Loop

Variabile	Tipo	Descrizione
{{loop.iteration}}	number	Numero iterazione corrente (base 1)
{{loop.previousResult}}	any	Output dell'iterazione precedente (null alla prima)

Esempi Pratici

Passare il contesto documentale a un LLM

Il pattern piu comune: Retrieval → LLM.

# Configurazione User Prompt del nodo LLM
userPrompt: |
  Documenti rilevanti recuperati:
  {{retrieval_1.formalized_content}}

  Domanda dell'utente:
  {{sys.query}}

  Rispondi in modo dettagliato, citando le fonti con [N].

Usare l'output di Categorize in un prompt

Dopo un nodo Categorize, puoi usare la categoria nel prompt LLM per personalizzare la risposta.

# Nel prompt di un LLM successivo a Categorize
systemPrompt: |
  Sei un esperto di {{categorize_1.category}}.
  (La domanda e stata classificata come: {{categorize_1.category}}
  con confidenza {{categorize_1.confidence}})

userPrompt: |
  {{sys.query}}

Costruire una query arricchita da input del form

Con un form Begin che raccoglie tipo e descrizione:

# Query nel nodo Retrieval
query: "{{sys.inputs.tipoSinistro}} polizza copertura {{sys.inputs.descrizione}} data {{sys.inputs.dataSinistro}}"

Accesso a JSON annidato

Se retrieval_1.results e un array di oggetti, puoi accedere al primo elemento:

# Primo risultato della ricerca
"{{retrieval_1.results.0.documentTitle}}"
"{{retrieval_1.results.0.content}}"
"{{retrieval_1.results.0.score}}"

All'interno di un'Iteration, puoi accedere alle proprieta dell'elemento corrente:

# Dentro un Iteration che itera su retrieval_1.results
userPrompt: |
  Analizza questo passaggio del documento "{{iter.item.documentTitle}}":
  {{iter.item.content}}
  (Rilevanza: {{iter.item.score}})

Combinare output di piu nodi

Con VariableAssigner puoi costruire un testo composto da piu sorgenti:

assignments:
  - name: contestoCompleto
    type: concat
    value: |
      ## Informazioni Aziendali
      {{retrieval_docs.formalized_content}}

      ## Normativa Applicabile
      {{retrieval_legal.formalized_content}}

      ## Dati dal Form
      Tipo: {{sys.inputs.tipo}}
      Data: {{sys.inputs.data}}

Poi nel prompt LLM:

userPrompt: |
  {{variableassigner_1.contestoCompleto}}

  Domanda: {{sys.query}}

Condizione Switch basata su valore LLM

Puoi usare l'output di un LLM (con jsonMode) come condizione Switch:

# LLM con jsonMode: true produce {"verdict": "CONFERMATO", "confidence": 0.92}
# Nel Switch:
conditions:
  - variable: "{{llm_analisi.content}}"
    operator: contains
    value: '"verdict": "CONFERMATO"'
    goto: message_positivo
  - variable: "{{llm_analisi.content}}"
    operator: contains
    value: '"verdict": "NON_CONFERMATO"'
    goto: userfillup_documenti
elseGoto: message_generico

Risoluzione dei Valori

Il Canvas risolve le variabili solo quando il nodo che le ha prodotte ha gia completato l'esecuzione. Se tenti di usare una variabile di un nodo non ancora eseguito, il valore sara undefined.

Il motore garantisce automaticamente l'ordine corretto grazie alla struttura DAG: un nodo riceve il controllo solo dopo che tutti i suoi predecessori nel grafo hanno terminato.

Variabili non definite

Se una variabile viene usata in un prompt ma il suo valore e undefined (nodo non ancora eseguito o nodo che non ha prodotto output), il testo risultante conterra letteralmente {{nome.variabile}} non sostituita. Controlla il pannello di debug durante i test per verificare che tutte le variabili siano popolate correttamente.

Namespace env

Il namespace {{env.nomeVariabile}} e riservato per variabili d'ambiente definite a livello di Canvas (configurabili dalla sezione impostazioni del Canvas). Utile per chiavi, URL o parametri da non hard-codare nel flusso.

---

Queria v3.1.2 -- Canvas Agent Builder