Variables y Referencias

Las variables son el mecanismo con el que los nodos del Canvas intercambian datos. Cada valor producido por un componente — texto generado, resultados de búsqueda, categorías, entradas del usuario — es accesible en los nodos siguientes mediante una referencia de variable.

Sintaxis

La sintaxis para referirse a una variable es:

{{namespace.path}}

• Dobles llaves: delimitan la referencia.
• namespace: identifica la fuente del valor (el nodo que lo produjo, o un namespace de sistema).
• path: el nombre de la clave de output, eventualmente con notación de punto para objetos anidados.

Ejemplos:

{{sys.query}}                        → texto de la pregunta del usuario
{{llm_1.content}}                    → respuesta del primer nodo LLM
{{retrieval_1.formalized_content}}   → texto recuperado por el Retrieval
{{categorize_1.category}}            → categoría asignada por el Categorize
{{sys.inputs.tipoSiniestro}}         → valor del campo "tipoSiniestro" del formulario Begin

Las variables se interpretan en cualquier parte del Canvas: en prompts, condiciones Switch, parámetros de configuración y mensajes UserFillUp.

Preservación del Tipo

Las variables preservan el tipo del valor original:

Tipo	Ejemplo	Notas
String	{{llm_1.content}}	Texto simple o Markdown
Number	{{retrieval_1.count}}	Número entero
Float	{{categorize_1.confidence}}	Número decimal
Boolean	{{loop_1.exitedEarly}}	true / false
Array	{{retrieval_1.results}}	Array JSON
Object	{{iter.item}}	Objeto JSON

Cuando una variable de tipo Array u Object se inserta en un texto (por ejemplo en un prompt), se serializa automáticamente en JSON. Para acceder a propiedades específicas usa la notación de punto:

{{retrieval_1.results.0.content}}       → primer elemento del array, campo "content"
{{iter.item.metadata.phase}}            → campo "phase" dentro de "metadata" del elemento actual

Namespace de Sistema (sys)

El namespace sys contiene variables globales disponibles en cualquier nodo del flujo, independientemente del orden de ejecución.

Variable	Tipo	Descripción
{{sys.query}}	string	Texto del mensaje del usuario (mode conversational)
{{sys.user_id}}	string	ID del usuario autenticado
{{sys.company_id}}	string	ID de la empresa del tenant actual
{{sys.conversation_id}}	string	ID de la conversación actual
{{sys.timestamp}}	string	Timestamp ISO 8601 de inicio del flujo (ej. 2026-03-29T14:30:00.000Z)
{{sys.inputs.nombreCampo}}	any	Valor de un campo del formulario Begin (mode task)

sys.query vs sys.inputs

En mode conversational, el texto del usuario siempre está en {{sys.query}}. En mode task, los datos del formulario están en {{sys.inputs.nombreCampo}}, mientras que {{sys.query}} puede estar vacío o contener un texto de inicio genérico.

Namespace de Componentes

Cada nodo del Canvas expone sus propios outputs en el namespace identificado por su ID de nodo. El ID es visible en el encabezado del nodo en el workspace (ej. llm_1, retrieval_2, categorize_1).

Output Nodo LLM

{{llm_N.content}}                   → texto generado
{{llm_N.usage.promptTokens}}        → tokens en el prompt
{{llm_N.usage.completionTokens}}    → tokens en la respuesta
{{llm_N.usage.totalTokens}}         → tokens totales

Output Nodo Retrieval

{{retrieval_N.formalized_content}}  → texto formateado listo para prompt LLM
{{retrieval_N.results}}             → array JSON de los resultados completos
{{retrieval_N.count}}               → número de resultados

La estructura de cada objeto en retrieval_N.results:

{
  "content": "Texto del fragmento...",
  "score": 0.87,
  "sourceType": "document",
  "documentTitle": "Poliza RCA 2025.pdf",
  "sectionTitle": "Artículo 5 - Exclusiones",
  "metadata": {
    "documentId": "...",
    "chunkIndex": 3,
    "pageNumber": 12
  }
}

Output Nodo Categorize

{{categorize_N.category}}           → nombre de la categoría asignada
{{categorize_N.confidence}}         → confianza 0.0-1.0
{{categorize_N.reasoning}}          → breve explicación de la elección

Output Nodo Agent

{{agent_N.content}}                 → respuesta final elaborada
{{agent_N.steps}}                   → array de los pasos ReAct
{{agent_N.toolCalls}}               → número de llamadas a herramientas ejecutadas

Output Nodo UserFillUp

{{userfillup_N.inputs.nombreCampo}} → valor del campo completado

Output Nodo VariableAssigner

{{variableassigner_N.nombreVar}}    → valor de la variable asignada

Output Nodo VariableAggregator

{{variableaggregator_N.outputName}} → primer valor no vacío entre las fuentes

Output Nodo DataOperations

{{dataoperations_N.result}}         → resultado de la operación
{{dataoperations_N.count}}          → número de elementos resultantes

Output Nodo Iteration

{{iteration_N.results}}             → array con el output de cada iteración
{{iteration_N.count}}               → número de iteraciones completadas

Output Nodo Loop

{{loop_N.finalResult}}              → resultado de la última iteración
{{loop_N.iterations}}               → número de iteraciones ejecutadas
{{loop_N.exitedEarly}}              → true si salió por ExitLoop

Output Nodo Invoke

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

Variables de Contexto en los Ciclos

Las variables de contexto de los ciclos están disponibles solo dentro de los nodos que forman parte del ciclo.

Contexto Iteration

Variable	Tipo	Descripción
{{iter.item}}	any	Elemento actual del array en iteración
{{iter.index}}	number	Índice actual (base 0)
{{iter.total}}	number	Número total de elementos en el array

Acceso a propiedades del elemento:

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

Contexto Loop

Variable	Tipo	Descripción
{{loop.iteration}}	number	Número de iteración actual (base 1)
{{loop.previousResult}}	any	Output de la iteración anterior (null en la primera)

Ejemplos Prácticos

Pasar el contexto documental a un LLM

El patrón más común: Retrieval → LLM.

# Configuración del User Prompt del nodo LLM
userPrompt: |
  Documentos relevantes recuperados:
  {{retrieval_1.formalized_content}}

  Pregunta del usuario:
  {{sys.query}}

  Responde de forma detallada, citando las fuentes con [N].

Usar el output de Categorize en un prompt

Después de un nodo Categorize, puedes usar la categoría en el prompt LLM para personalizar la respuesta.

# En el prompt de un LLM posterior a Categorize
systemPrompt: |
  Eres un experto en {{categorize_1.category}}.
  (La pregunta ha sido clasificada como: {{categorize_1.category}}
  con confianza {{categorize_1.confidence}})

userPrompt: |
  {{sys.query}}

Construir una consulta enriquecida desde entradas del formulario

Con un formulario Begin que recoge tipo y descripción:

# Consulta en el nodo Retrieval
query: "{{sys.inputs.tipoSiniestro}} poliza cobertura {{sys.inputs.descripcion}} fecha {{sys.inputs.fechaSiniestro}}"

Acceso a JSON anidado

Si retrieval_1.results es un array de objetos, puedes acceder al primer elemento:

# Primer resultado de la búsqueda
"{{retrieval_1.results.0.documentTitle}}"
"{{retrieval_1.results.0.content}}"
"{{retrieval_1.results.0.score}}"

Dentro de un Iteration, puedes acceder a las propiedades del elemento actual:

# Dentro de un Iteration que itera sobre retrieval_1.results
userPrompt: |
  Analiza este fragmento del documento "{{iter.item.documentTitle}}":
  {{iter.item.content}}
  (Relevancia: {{iter.item.score}})

Combinar outputs de varios nodos

Con VariableAssigner puedes construir un texto compuesto de varias fuentes:

assignments:
  - name: contextoCompleto
    type: concat
    value: |
      ## Información Empresarial
      {{retrieval_docs.formalized_content}}

      ## Normativa Aplicable
      {{retrieval_legal.formalized_content}}

      ## Datos del Formulario
      Tipo: {{sys.inputs.tipo}}
      Fecha: {{sys.inputs.fecha}}

Luego en el prompt LLM:

userPrompt: |
  {{variableassigner_1.contextoCompleto}}

  Pregunta: {{sys.query}}

Condición Switch basada en valor LLM

Puedes usar el output de un LLM (con jsonMode) como condición Switch:

# LLM con jsonMode: true produce {"verdict": "CONFIRMADO", "confidence": 0.92}
# En el Switch:
conditions:
  - variable: "{{llm_analisis.content}}"
    operator: contains
    value: '"verdict": "CONFIRMADO"'
    goto: message_positivo
  - variable: "{{llm_analisis.content}}"
    operator: contains
    value: '"verdict": "NO_CONFIRMADO"'
    goto: userfillup_documentos
elseGoto: message_generico

Resolución de los Valores

El Canvas resuelve las variables solo cuando el nodo que las produjo ha completado su ejecución. Si intentas usar una variable de un nodo aún no ejecutado, el valor será undefined.

El motor garantiza automáticamente el orden correcto gracias a la estructura DAG: un nodo recibe el control solo después de que todos sus predecesores en el grafo han terminado.

Variables no definidas

Si una variable se usa en un prompt pero su valor es undefined (nodo aún no ejecutado o nodo que no produjo output), el texto resultante contendrá literalmente {{nombre.variable}} sin sustituir. Revisa el panel de depuración durante las pruebas para verificar que todas las variables estén correctamente pobladas.

Namespace env

El namespace {{env.nombreVariable}} está reservado para variables de entorno definidas a nivel de Canvas (configurables desde la sección de ajustes del Canvas). Útil para claves, URLs o parámetros que no deban estar hardcodeados en el flujo.

---

Queria v3.1.2 -- Canvas Agent Builder