Componentes del Canvas

El Canvas dispone de 15 componentes divididos en seis categorías funcionales. Cada componente tiene parámetros de configuración, produce outputs identificables con variables y sirve a un propósito preciso en el flujo.

Flujo Base

Los componentes de flujo base gestionan el punto de entrada, las ramificaciones lógicas y la salida final hacia el usuario.

---

Begin

Función: Punto de entrada obligatorio de todo Canvas. Define cómo se inicia el flujo y qué datos iniciales están disponibles.

Cuando usarlo: Es el primer nodo de todo Canvas. Cada flujo debe tener exactamente un nodo Begin.

Parámetro	Tipo	Descripción
mode	task | conversational	task: inicio con formulario estructurado. conversational: integración de chat, recibe {{sys.query}} automáticamente.
inputFields	Array	Solo para mode task. Define los campos del formulario de entrada.

Estructura de un campo inputFields:

Subcampo	Tipo	Descripción
name	string	Identificador del campo, usable como {{sys.inputs.name}}
label	string	Etiqueta visible en el formulario
type	string | text | select | date | number	Tipo del campo
options	Array	Solo para select: lista de opciones disponibles
required	boolean	Si el campo es obligatorio antes del inicio
placeholder	string	Texto sugerido en el campo

Outputs disponibles:

Variable	Descripción
{{sys.query}}	Texto del mensaje del usuario (mode conversational)
{{sys.inputs.nombreCampo}}	Valor de un campo del formulario (mode task)
{{sys.user_id}}	ID del usuario actual
{{sys.company_id}}	ID de la empresa actual
{{sys.conversation_id}}	ID de la conversación actual
{{sys.timestamp}}	Timestamp de inicio del flujo (ISO 8601)

Ejemplo — Formulario de seguros:

mode: task
inputFields:
  - name: tipoSiniestro
    label: Tipo de Siniestro
    type: select
    options: [Auto, Vida, Hogar, RC, Otro]
    required: true
  - name: fechaSiniestro
    label: Fecha del Siniestro
    type: date
    required: true
  - name: descripcion
    label: Descripción del Evento
    type: text
    required: true
    placeholder: Describe el suceso en detalle
  - name: numeroPoliza
    label: Número de Póliza
    type: string
    required: true

---

Message

Función: Nodo de salida que presenta el resultado final al usuario. Es el nodo terminal del flujo o de una rama.

Cuando usarlo: Al final de cada rama del flujo para mostrar una respuesta. Un flujo puede tener varios nodos Message (uno por cada rama del Switch).

Parámetro	Tipo	Descripción
content	string	Contenido a mostrar. Acepta variables como {{llm_1.content}}. Puede ser texto estático.
format	markdown | plain	Formato de renderizado del texto. Usa markdown para respuestas LLM.
showCitations	boolean	Si mostrar los badges de fuentes y las citas [N]. Por defecto: true.

Outputs disponibles: El nodo Message no produce outputs de variable (es un nodo terminal).

Ejemplo — Respuesta estática para tema fuera de ámbito:

content: |
  Lo siento, esta pregunta no está dentro del ámbito
  del asistente actual. Para solicitudes de este tipo,
  te pedimos que contactes directamente con el equipo competente.
format: markdown
showCitations: false

Ejemplo — Respuesta dinámica desde LLM:

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

---

Switch

Función: Nodo de enrutamiento que evalúa condiciones lógicas y dirige la ejecución hacia ramas distintas.

Cuando usarlo: Cuando el flujo debe comportarse de forma diferente según una categoría, una palabra clave en la respuesta o el valor de un campo.

Parámetro	Tipo	Descripción
conditions	Array	Lista de condiciones evaluadas en orden. Se sigue la primera que sea verdadera.
elseGoto	string	ID del nodo al que ir si ninguna condición es verdadera.

Estructura de una condición:

Subcampo	Tipo	Descripción
variable	string	Variable a evaluar (ej. {{categorize_1.category}})
operator	string	Operador de comparación (ver tabla)
value	string	Valor con el que comparar
goto	string	ID del nodo de destino si la condición es verdadera

Operadores disponibles:

Operador	Significado
equals	Igual a (sin distinción de mayúsculas)
not_equals	Distinto de
contains	Contiene la cadena
not_contains	No contiene la cadena
starts_with	Empieza por
ends_with	Termina en
greater_than	Mayor que (numérico)
less_than	Menor que (numérico)
is_empty	El valor está vacío o es null
is_not_empty	El valor no está vacío

Outputs disponibles: El nodo Switch no produce outputs de variable, solo gestiona el enrutamiento.

Ejemplo — Enrutamiento por categoría:

conditions:
  - variable: "{{categorize_1.category}}"
    operator: equals
    value: "Tecnico"
    goto: llm_tecnico
  - variable: "{{categorize_1.category}}"
    operator: equals
    value: "Comercial"
    goto: llm_comercial
elseGoto: message_generico

---

Inteligencia Artificial

Componentes que involucran modelos de lenguaje y recuperación de información.

---

LLM

Función: Llama a un modelo de lenguaje con un prompt configurable y produce texto como output. Es el componente principal para generar respuestas, análisis, clasificaciones y transformaciones de texto.

Cuando usarlo: Para generar respuestas al usuario, analizar contenidos recuperados, sintetizar información o clasificar texto en modo freeform.

Parámetro	Tipo	Descripción
model	writer | planner	writer: Qwen3-80B, respuestas elaboradas y razonamiento profundo. planner: Qwen3-30B, clasificaciones rápidas y tareas simples.
systemPrompt	string	Instrucciones de contexto para el modelo (persona, reglas, formato de output). Acepta variables.
userPrompt	string	El texto efectivo de la solicitud al modelo. Acepta variables.
temperature	number	Creatividad de la respuesta. 0.1-0.3 para respuestas factuales, 0.7-0.9 para texto creativo. Por defecto: 0.3.
maxTokens	number	Longitud máxima de la respuesta en tokens. Por defecto: 2048. Máximo: 8192.
jsonMode	boolean	Si es true, el modelo produce un objeto JSON válido. Útil para extraer datos estructurados. Por defecto: false.

Outputs disponibles:

Variable	Descripción
{{llm_N.content}}	Texto completo generado por el modelo
{{llm_N.usage.promptTokens}}	Tokens usados en el prompt
{{llm_N.usage.completionTokens}}	Tokens usados en la respuesta

Ejemplo — Análisis con JSON Mode:

model: planner
systemPrompt: |
  Eres un clasificador. Responde SOLO con JSON válido,
  sin texto adicional.
userPrompt: |
  Clasifica este texto como POSITIVO, NEGATIVO o NEUTRO.
  Texto: {{sys.query}}

  Responde con: {"sentiment": "POSITIVO|NEGATIVO|NEUTRO", "confidence": 0.0-1.0}
temperature: 0.1
jsonMode: true

Ejemplo — Análisis documental:

model: writer
systemPrompt: |
  Eres un perito de seguros senior. Analiza la documentación
  proporcionada y ofrece una evaluación técnica detallada.
  Cita siempre las fuentes con [N]. Responde en español.
userPrompt: |
  Tipo de siniestro: {{sys.inputs.tipoSiniestro}}
  Fecha: {{sys.inputs.fechaSiniestro}}

  Documentos de póliza y normativa aplicable:
  {{retrieval_1.formalized_content}}

  Descripción del evento:
  {{sys.inputs.descripcion}}

  Proporciona: 1) Evaluación de cobertura 2) Normativa aplicable 3) Documentación adicional requerida
temperature: 0.2
maxTokens: 4096

---

Retrieval

Función: Ejecuta una búsqueda híbrida (semántica + texto completo) en los documentos empresariales, en la Knowledge Base y en las fuentes externas habilitadas. Devuelve los fragmentos más relevantes para la consulta.

Cuando usarlo: Cada vez que el flujo necesite contexto documental. Es el nodo que conecta las preguntas del usuario con el patrimonio informativo de la organización.

Parámetro	Tipo	Descripción
query	string	Texto de búsqueda. Usa {{sys.query}} o una variable procesada. Acepta texto estático combinado con variables.
topK	number	Número máximo de fragmentos a recuperar. Rango: 5-50. Por defecto: 10.
scoreThreshold	number	Umbral mínimo de relevancia (0.0-1.0). Los fragmentos por debajo del umbral se excluyen. Por defecto: 0.5.
useReranking	boolean	Si aplicar el reranker BGE para reordenar los resultados. Recomendado para mayor calidad. Por defecto: true.
companyDocs	boolean	Busca en los documentos empresariales cargados. Por defecto: true.
knowledgeBase	boolean	Busca en la Knowledge Base curada. Por defecto: true.
legalSources	boolean	Busca en Normattiva (fuentes normativas italianas y europeas). Por defecto: false.
foodSources	boolean	Busca en Open Food Facts (productos alimentarios). Por defecto: false.
chemSources	boolean	Busca en ECHA/REACH (sustancias químicas, SDS). Por defecto: false.
pharmaSources	boolean	Busca en FDA/ClinicalTrials/PubMed (fármacos, ensayos, publicaciones). Por defecto: false.
aeSources	boolean	Busca en Agenzia delle Entrate (normativa fiscal italiana). Por defecto: false.
topicIds	Array	Lista de IDs de topic para limitar la búsqueda a categorías específicas. Opcional.

Outputs disponibles:

Variable	Descripción
{{retrieval_N.formalized_content}}	Texto formateado de los fragmentos encontrados, listo para un prompt LLM. Incluye títulos y referencias.
{{retrieval_N.results}}	Array JSON de los resultados completos con score, metadata y fuente.
{{retrieval_N.count}}	Número de fragmentos recuperados.

Ejemplo — Búsqueda multi-fuente legal:

query: "{{sys.inputs.tipoSiniestro}} póliza de seguros cobertura {{sys.inputs.descripcion}}"
topK: 20
useReranking: true
companyDocs: true
knowledgeBase: true
legalSources: true

---

Categorize

Función: Clasifica el texto de entrada en una de las categorías predefinidas usando un modelo LLM rápido. Dirige automáticamente la ejecución hacia la rama correspondiente.

Cuando usarlo: Para enrutamiento inteligente basado en el contenido de la pregunta, sin condiciones rígidas. Más robusto que Switch para categorizaciones semánticas.

Parámetro	Tipo	Descripción
input	string	Texto a clasificar. Normalmente {{sys.query}}.
categories	Array	Lista de categorías con etiqueta, descripción y nodo de destino.
minConfidence	number	Confianza mínima requerida. Si la clasificación cae por debajo de este umbral, se usa la categoría other. Por defecto: 0.6.

Estructura de una categoría:

Subcampo	Tipo	Descripción
name	string	Nombre de la categoría (usado como valor del output)
description	string	Descripción para ayudar al modelo a clasificar correctamente
goto	string	ID del nodo de destino para esta categoría

Outputs disponibles:

Variable	Descripción
{{categorize_N.category}}	Nombre de la categoría asignada
{{categorize_N.confidence}}	Confianza de la clasificación (0.0-1.0)
{{categorize_N.reasoning}}	Breve explicación de la clasificación

Ejemplo — Enrutamiento por tipo de pregunta:

input: "{{sys.query}}"
minConfidence: 0.65
categories:
  - name: Tecnico
    description: Preguntas sobre productos, especificaciones técnicas, manuales, instalaciones, averías
    goto: llm_tecnico
  - name: Comercial
    description: Preguntas sobre precios, ofertas, contratos, promociones, disponibilidad
    goto: llm_comercial
  - name: Normativo
    description: Preguntas sobre leyes, reglamentos, certificaciones, obligaciones legales
    goto: retrieval_normativo
  - name: Otro
    description: Preguntas no pertinentes al ámbito empresarial
    goto: message_fuera_ambito

---

Agent

Función: Ejecuta un ciclo ReAct (Reasoning + Acting) autónomo. El modelo decide qué herramienta usar, la llama, evalúa el resultado y decide si se necesitan más pasos o si la respuesta está completa.

Cuando usarlo: Para tareas que requieren razonamiento multi-paso no determinable a priori. El Agent es más flexible que una secuencia fija pero más lento. Usa el modelo writer para la máxima calidad.

Parámetro	Tipo	Descripción
systemPrompt	string	Descripción del rol e instrucciones para el agente.
userPrompt	string	La tarea a ejecutar. Acepta variables.
tools	Array	Lista de herramientas disponibles (ver tabla).
maxRounds	number	Número máximo de iteraciones ReAct. Por defecto: 5. Máximo: 10.
model	writer | planner	Modelo a usar. writer para tareas complejas.

Herramientas disponibles:

Tool ID	Descripción
retrieval	Búsqueda en documentos empresariales y KB
legal_search	Búsqueda en Legal Sources (Normattiva)
pharma_search	Búsqueda en Pharma Sources (FDA/PubMed)
food_search	Búsqueda en Food Sources (Open Food Facts)
chem_search	Búsqueda en Chem Sources (ECHA/REACH)
graph_query	Consulta del grafo Neo4j (entidades y relaciones)

Outputs disponibles:

Variable	Descripción
{{agent_N.content}}	Respuesta final elaborada por el agente
{{agent_N.steps}}	Array JSON de los pasos ReAct ejecutados
{{agent_N.toolCalls}}	Número total de llamadas a herramientas realizadas

Ejemplo:

systemPrompt: |
  Eres un investigador experto en normativa alimentaria europea.
  Usa las herramientas disponibles para responder con precisión,
  citando siempre las fuentes normativas.
userPrompt: "{{sys.query}}"
tools: [retrieval, food_search, legal_search]
maxRounds: 6
model: writer

---

Interacción con el Usuario

---

UserFillUp

Función: Suspende la ejecución del flujo y muestra un formulario al usuario para recopilar información adicional. Cuando el usuario envía el formulario, la ejecución se reanuda desde el punto siguiente.

Cuando usarlo: Cuando el flujo necesita documentos, datos o aclaraciones que no estaban disponibles al inicio. Típico en flujos de gestión de siniestros, auditorías o due diligence.

Parámetro	Tipo	Descripción
message	string	Mensaje mostrado al usuario antes del formulario. Explica qué es necesario y por qué. Acepta variables.
fields	Array	Campos del formulario (misma estructura que Begin inputFields, con la adición de type: file).
tips	string	Sugerencias opcionales mostradas bajo el formulario (ej. "Acepta PDF, JPG, PNG hasta 10MB").

Tipo de campo adicional para UserFillUp:

Tipo	Descripción
file	Carga de archivo. Admite PDF, DOCX, imágenes. El archivo se vectoriza y queda disponible como documento temporal.

Outputs disponibles:

Variable	Descripción
{{userfillup_N.inputs.nombreCampo}}	Valor del campo completado por el usuario
{{userfillup_N.inputs.nombreArchivo}}	Referencia al archivo cargado (si type: file)

Ejemplo:

message: |
  La documentación inicial no es suficiente para confirmar
  la cobertura. Te pedimos que proporciones los siguientes documentos:
fields:
  - name: fotoDano
    label: Foto del daño
    type: file
    required: true
  - name: peritaje
    label: Peritaje técnico (si está disponible)
    type: file
    required: false
  - name: notas
    label: Notas adicionales
    type: text
    required: false
    placeholder: Información adicional sobre el suceso
tips: "Formatos aceptados: PDF, JPG, PNG, DOCX. Tamaño máximo: 20MB por archivo."

---

Manipulación de Datos

Componentes para transformar, combinar y filtrar datos dentro del flujo.

---

VariableAssigner

Función: Crea o transforma variables combinando valores existentes. Útil para construir textos compuestos, unir arrays o preparar datos para los nodos siguientes.

Cuando usarlo: Para construir cadenas de consulta a partir de múltiples entradas, unir outputs de distintos nodos o preparar datos estructurados.

Parámetro	Tipo	Descripción
assignments	Array	Lista de asignaciones variable → valor.

Estructura de una asignación:

Subcampo	Tipo	Descripción
name	string	Nombre de la variable de output
type	concat | merge | array | custom	Tipo de operación
value	string / Array	Valor o plantilla. Para concat: cadena con variables. Para merge: objetos a unir. Para array: lista de valores.

Outputs disponibles:

Variable	Descripción
{{variableassigner_N.nombreVariable}}	Valor asignado a la variable definida

Operaciones disponibles:

Tipo	Uso
concat	Concatena cadenas y variables en un único texto
merge	Une objetos JSON
array	Crea un array a partir de una lista de valores
custom	Expresión de transformación freeform

Ejemplo — Construir consulta compuesta:

assignments:
  - name: consultaCompleta
    type: concat
    value: "Siniestro {{sys.inputs.tipoSiniestro}} del {{sys.inputs.fechaSiniestro}}: {{sys.inputs.descripcion}}"

---

VariableAggregator

Función: Recoge el primer valor no vacío entre varias fuentes de variable. Útil para gestionar fallbacks cuando un nodo puede no producir output.

Cuando usarlo: Cuando varias ramas del flujo pueden producir un resultado y quieres pasar el primero disponible al nodo siguiente.

Parámetro	Tipo	Descripción
sources	Array	Lista de variables a comprobar en orden. Se usa la primera no vacía.
outputName	string	Nombre de la variable de output agregada.

Outputs disponibles:

Variable	Descripción
{{variableaggregator_N.outputName}}	Primer valor no vacío entre las fuentes

Ejemplo — Fallback entre dos LLM:

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

---

DataOperations

Función: Aplica transformaciones sobre arrays y textos: filtro, mapa, ordenación, corte, extracción, unión, división, deduplicación.

Cuando usarlo: Para procesar listas de resultados (ej. filtrar ensayos clínicos por fase, extraer solo los títulos, deduplicar por ID).

Parámetro	Tipo	Descripción
input	string	Variable de entrada a procesar (típicamente un array JSON).
operation	string	Tipo de operación a aplicar (ver tabla).
params	object	Parámetros específicos de la operación.

Operaciones disponibles:

Operación	Descripción	Parámetros clave
filter	Filtra elementos que cumplen una condición	field, operator, value
map	Transforma cada elemento extrayendo un campo	field
sort	Ordena por un campo	field, direction (asc/desc)
slice	Toma una porción del array	start, end
extract	Extrae un campo de cada objeto	field
join	Une los elementos del array en una cadena	separator
split	Divide una cadena en array	separator
deduplicate	Elimina duplicados	field (campo clave para dedup)

Outputs disponibles:

Variable	Descripción
{{dataoperations_N.result}}	Resultado de la operación
{{dataoperations_N.count}}	Número de elementos resultantes

Ejemplo — Filtrar ensayos clínicos por fase:

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

---

Ciclos

Componentes para iterar sobre listas de elementos o repetir bloques hasta satisfacer una condición.

---

Iteration

Función: Itera sobre cada elemento de un array, ejecutando una subsecuencia de nodos para cada uno.

Cuando usarlo: Para procesar una lista de elementos uno a uno — por ejemplo analizar cada ensayo clínico encontrado, o procesar cada documento de una lista.

Parámetro	Tipo	Descripción
input	string	Variable array sobre la que iterar.
iterationNodeIds	Array	Lista de los IDs de los nodos a ejecutar para cada elemento.

Variables de contexto disponibles durante la iteración:

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

Outputs disponibles:

Variable	Descripción
{{iteration_N.results}}	Array con los resultados de cada iteración
{{iteration_N.count}}	Número de iteraciones completadas

Ejemplo — Analizar cada ensayo clínico:

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

Dentro de llm_analisis_ensayo, usa {{iter.item.title}}, {{iter.item.phase}}, etc.

---

Loop

Función: Repite un bloque de nodos mientras una condición sea verdadera o se alcance el número máximo de iteraciones. Útil para refinamiento iterativo o búsqueda progresiva.

Cuando usarlo: Para procesos de refinamiento donde no conoces a priori cuántas iteraciones se necesitan — por ejemplo búsqueda progresiva hasta encontrar la respuesta o alcanzar la confianza deseada.

Parámetro	Tipo	Descripción
condition	string	Expresión booleana: el loop continúa mientras sea true. Acepta variables.
maxIterations	number	Límite máximo de iteraciones para evitar loops infinitos. Por defecto: 5. Máximo: 20.
loopNodeIds	Array	Lista de los IDs de los nodos a ejecutar en cada iteración.

Variables de contexto disponibles durante el loop:

Variable	Descripción
{{loop.iteration}}	Número de iteración actual (base 1)
{{loop.previousResult}}	Output de la iteración anterior

Outputs disponibles:

Variable	Descripción
{{loop_N.finalResult}}	Resultado de la última iteración ejecutada
{{loop_N.iterations}}	Número total de iteraciones ejecutadas
{{loop_N.exitedEarly}}	true si el loop salió por ExitLoop

---

ExitLoop

Función: Sale inmediatamente del Loop actual, aunque la condición del Loop todavía sea verdadera. Se posiciona dentro del bloque de nodos del Loop.

Cuando usarlo: Para salir del loop cuando una condición específica se cumple antes de alcanzar maxIterations — por ejemplo cuando la confianza es suficiente.

Parámetro	Tipo	Descripción
condition	string	Sale del loop si esta condición es true. Si se omite, sale siempre al ser alcanzado.

Ejemplo — Loop con salida anticipada:

Loop (condition: "{{llm_eval.confidence}} < 0.8", maxIterations: 4)
  → Retrieval (consulta refinada)
  → LLM (evaluación de confianza)
  → ExitLoop (condition: "{{llm_eval.confidence}} >= 0.8")

---

Composición

---

Invoke

Función: Ejecuta otro Canvas como subflujo. Permite reutilizar flujos existentes como bloques modulares.

Cuando usarlo: Para descomponer flujos complejos en módulos reutilizables, o para llamar a un Canvas especializado (ej. un analizador legal) desde varios Canvas distintos.

Parámetro	Tipo	Descripción
canvasId	string	ID del Canvas a invocar.
inputMapping	object	Mapa entre variables del Canvas actual y entradas esperadas por el sub-Canvas.
timeout	number	Timeout en milisegundos para la finalización del sub-Canvas. Por defecto: 30000.

Outputs disponibles:

Variable	Descripción
{{invoke_N.output}}	Output completo del sub-Canvas
{{invoke_N.status}}	success | error | timeout

Ejemplo — Invocar un analizador legal:

canvasId: "canvas_analisis_normativa_abc123"
inputMapping:
  query: "{{sys.inputs.tipoContrato}} {{sys.inputs.descripcion}}"
  topicId: "legal"
timeout: 45000

---

Resumen de Outputs por Componente

Componente	Variable de Output Principal
Begin	{{sys.query}}, {{sys.inputs.campo}}
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.campo}}
Switch	(sin output, solo enrutamiento)
Message	(sin output, nodo terminal)
VariableAssigner	{{variableassigner_N.nombreVar}}
VariableAggregator	{{variableaggregator_N.outputName}}
DataOperations	{{dataoperations_N.result}}
Iteration	{{iteration_N.results}}
Loop	{{loop_N.finalResult}}
ExitLoop	(sin output, gestiona el loop)
Invoke	{{invoke_N.output}}

Nombres automáticos de los nodos

El Canvas asigna nombres automáticos a los nodos (llm_1, retrieval_2, etc.) según el tipo y el orden de inserción. Puedes ver el nombre asignado en el encabezado del nodo en el workspace. El nombre se usa como namespace en las variables.

---

Queria v3.1.2 -- Canvas Agent Builder