JS Code

El componente JS Code permite a los usuarios ejecutar código JavaScript dentro del dashboard de Nappai. Con él puedes transformar datos que recibes, llamar a APIs externas, registrar información de depuración y, si lo deseas, convertir el flujo en un tool que otros componentes o agentes de IA puedan invocar.

¿Cómo funciona?

Cuando colocas el componente en tu flujo, Nappai pasa los datos de entrada a la variable $data. El bloque de código que escribas en el campo JavaScript Code se ejecuta en un entorno sandbox limitado:

1. Procesamiento local – Puedes leer y modificar $data y devolver cualquier valor con return.
2. Acceso a argumentos de herramientas – Si el componente se usa como tool, la variable $args contiene los parámetros que el agente envía.
3. Conexión a otros componentes – Cuando no se usa como tool, puedes leer los resultados de componentes anteriores a través de $components.
4. Llamadas HTTP – Con $fetch(url, options) puedes hacer peticiones síncronas a cualquier API. Se permiten hasta 10 llamadas por ejecución y el resultado se devuelve como un objeto JSON con metadatos (estado, encabezados, texto, datos, etc.).
5. Registro – $log(...args) escribe en el registro de la ejecución (máximo 50 llamadas por ejecución).

El código se ejecuta con un límite de 10 segundos y los datos devueltos están restringidos a 1 000 elementos en listas y 150 KB en texto.

Entradas

Input Data

Datos que quieres procesar. Puede ser un solo objeto o una lista. También puedes usar $fetch dentro del código para obtener datos de una URL.

JavaScript Code

Bloque de código JavaScript que opera sobre $data, $args y $components. Usa return para devolver el resultado final. Ejemplo: javascript // Devuelve el número de elementos en la lista return $data.length;

Tool Input Schema

Define la estructura y tipos de datos que el tool aceptará. Se añade a $args. Ejemplo: json { “type”: “object”, “properties”: { “productId”: { “type”: “string” } }, “required”: [“productId”] }

Tool Description

Texto que describe la función del tool. Ejemplo: javascript Execute Javascript Code using args and return the processed data.

Tool Name

Nombre que aparecerá cuando el tool sea invocado por un agente. Ejemplo: GetProductInfo.

Salidas

• Processed Data – Resultado de la ejecución del código JavaScript. Se puede usar como entrada de otro componente.
• Tool – Si se configuró, devuelve un objeto tool que otros componentes o agentes pueden llamar.

Ejemplo de Uso

Escenario 1: Filtrar productos

1. Input Data: Una lista de productos obtenida con un componente HTTP Request.

2. JavaScript Code: javascript // Filtra productos con precio > 100 return $data.filter(p => p.price > 100);

3. Salida: Processed Data contiene solo los productos caros, que luego puedes pasar a un componente de visualización.

Escenario 2: Crear un tool para obtener información de un producto

1. Tool Input Schema: json { “type”: “object”, “properties”: { “productId”: { “type”: “string” } }, “required”: [“productId”] }

2. Tool Description: javascript Fetch product details by ID and return the data.

3. Tool Name: GetProductDetails

4. JavaScript Code:

const id = $args.productId;
const response = $fetch(`https://dummyjson.com/products/${id}`);
if (!response.ok) {
  $log("Error fetching product", response.statusText);
  return null;
}
return response.data;

5. Salida: Tool que puede ser llamado por un agente de IA para obtener los datos del producto solicitado.

Componentes Relacionados

• HTTP Request – Para obtener datos de APIs externas antes de procesarlos con JS.
• Data Mapper – Para transformar la salida de JS a un formato que otros componentes requieran.
• Data Output – Para mostrar el resultado final en el dashboard.

Consejos y Mejores Prácticas

• Mantén el código ligero: Evita bucles extensos o cálculos costosos; recuerda el límite de 10 segundos.
• Limita las llamadas HTTP: Solo 10 por ejecución; usa $fetch solo cuando sea necesario.
• Registra solo lo esencial: $log ayuda a depurar, pero exceder 50 llamadas puede ralentizar la ejecución.
• Valida los datos de entrada: Usa Tool Input Schema para asegurar que $args tenga la forma esperada.
• Evita código malicioso: No ejecutes código que provenga de fuentes no confiables.

Consideraciones de Seguridad

• El entorno de ejecución es sandboxed, pero siempre verifica los datos que recibes antes de procesarlos.
• $fetch solo permite URLs HTTP/HTTPS; no se pueden ejecutar comandos del sistema ni acceder a archivos locales.
• Los resultados devueltos están limitados a 150 KB de texto y 1 000 elementos en listas, lo que ayuda a prevenir ataques de denegación de servicio por sobrecarga de datos.

---