Python Code

El componente Python Code actúa como un “laboratorio de programación” dentro de tu flujo de trabajo en Nappai. Su propósito principal es darte la libertad de escribir código Python personalizado para realizar tareas complejas que los componentes estándar no pueden cubrir por sí mismos.

Es ideal si necesitas limpiar datos, realizar cálculos matemáticos complejos, interactuar con APIs externas o manipular estructuras de datos avanzadas. Piensa en él como una caja de herramientas donde tú controlas la lógica exacta que se ejecuta con tus datos.

¿Cómo funciona?

Cuando agregas este componente a tu flujo, estarás creando un entorno de ejecución seguro y aislado (similar a una pequeña computadora virtual). Este entorno recibe los datos que le envías, ejecuta el código Python que hayas escrito y devuelve el resultado para que puedas continuar con el siguiente paso de tu automatización.

Internamente, el componente gestiona la seguridad y el aislamiento para asegurar que tu código se ejecute sin afectar al resto del sistema. Todo lo que proceses aquí está diseñado para ser rápido y eficiente, utilizando el poder de Python para resolver problemas lógicos específicos.

Conexión y Credenciales

Este componente no requiere credenciales externas específicas para funcionar de manera básica, ya que opera sobre los datos y lógica que tú le proporcionas directamente. Sin embargo, si tu código necesita acceder a servicios externos (como una base de datos o una API de terceros), asegúrate de tener configuradas las credenciales necesarias en el panel de Nappai y de pasarlas mediante la variable de entorno env.

Entradas

Para que el componente funcione, debes configurar correctamente sus campos de entrada. Estos son los elementos clave que interactuarán con tu código:

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente:

Input Data: Los datos que deseas procesar. Puede ser un solo elemento, una lista de elementos o una URL.
- Visible en: Operaciones estándar de código
Python Code: Este es el campo principal donde escribes tu lógica.
- Visible en: Operaciones estándar de código
Packages: Aquí puedes instalar librerías de Python adicionales (como pandas, requests, etc.) necesarias para tu script.
- Visible en: Operaciones estándar de código
Python Version: Permite seleccionar la versión de Python que se utilizará en el entorno de ejecución.
- Visible en: Operaciones estándar de código
Tools: Si necesitas conectar herramientas externas (como herramientas de IA o APIs) para usarlas desde tu código Python.
- Visible en: Operaciones avanzadas/herramientas
Model: El modelo de lenguaje específico que deseas invocar desde tu código.
- Visible en: Operaciones de modelos
Tool Name: El nombre de la herramienta específica a la que quieres conectar.
- Visible en: Operaciones de herramientas
Tool Description: Una descripción breve de lo que hace la herramienta conectada.
- Visible en: Operaciones de herramientas
Tool Input Schema: Define la estructura de los datos que la herramienta espera recibir.
- Visible en: Operaciones de herramientas
Enable Tools Input: Una opción para activar la capacidad de recibir y llamar a herramientas externas desde tu código.
- Visible en: Operaciones avanzadas
Enable Models Input: Una opción para activar la capacidad de llamar a modelos de IA desde tu código.
- Visible en: Operaciones avanzadas
Allow update agent state: Permite que el código Python actualice el estado interno de un agente si es parte de una conversación.
- Visible en: Operaciones de agentes

INSTRUCCIÓN CLAVE PARA EL USUARIO: El campo Python Code es el corazón del componente. Dentro de este campo, tienes acceso a variables predefinidas:

data: Contiene lo que ingresaste en Input Data.
env: Un diccionario con variables de entorno (como claves API) si están configuradas.
tools: Un diccionario para llamar a herramientas conectadas.
models: Un diccionario para llamar a modelos de IA.

IMPORTANTE: Para que el componente devuelva un resultado útil al siguiente paso de tu flujo, DEBES usar la palabra clave return en tu código. Si no lo haces, la salida será vacía.

Salidas

El componente produce principalmente dos tipos de resultados que puedes conectar a otros nodos:

Processed Data: Es el resultado principal. Contiene exactamente lo que devolvió tu código Python usando return. Puede ser un texto, un número, una lista, un diccionario, etc.
Tool: (En modos avanzados) Devuelve la definición de una herramienta creada dinámicamente.

Ejemplo de Respuesta JSON

Si tu código Python devuelve un diccionario con información de usuario procesada, el resultado que verás al conectar este componente a otro podría verse así: json { “name”: “Juan Pérez”, “status”: “Activo”, “score”: 85, “tags”: [“vip”, “nuevo”] }

En este caso, en el siguiente componente de tu flujo, podrías mapear el campo name para usarlo directamente, o iterar sobre tags.

Conectividad

Este componente es altamente flexible y puede conectarse a la gran mayoría de nodos posteriores en Nappai.

Conexión con Procesadores de Datos: Es común conectarlo a componentes de búsqueda, filtrado o análisis de datos, ya que Python permite limpiar y transformar datos de formas muy precisas.
Conexión con APIs: Si tu código Python obtiene datos de una API externa, puedes conectar la salida directamente a un nodo de “Webhook” o “Guardar en Base de Datos”.
Conexión con Modelos de IA: Si usas el componente para enviar texto a un modelo de IA, la salida (la respuesta del modelo) se conecta fácilmente a nodos de respuesta o a componentes de análisis de texto.

Ejemplo de Uso

Imagina que tienes una lista de correos electrónicos en formato desordenado y quieres limpiarla y convertirla a minúsculas.

Input Data: Envías una lista de correos: ["ADMIN@Example.COM", "user@example.com", " Support@EXAMPLE.COM "].
Python Code: Escribes el siguiente script: python import re

Limpia los espacios y convierte a minúsculas

cleaned_emails = [] for email in data: # Elimina espacios en blanco clean_email = email.strip().lower() # Verifica que tenga formato básico de email if ”@” in clean_email: cleaned_emails.append(clean_email)

Devuelve la lista limpia

return cleaned_emails

Resultado: El componente devuelve ["admin@example.com", "user@example.com", "support@example.com"].
Siguiente Paso: Puedes conectar esta salida a un componente que envíe correos masivos, sabiendo que la lista está limpia y lista para usar.

Consejos y Mejores Prácticas

Usa return siempre: Recuerda que si no escribes return <tu_variable>, el componente no enviará nada a la siguiente etapa.
Manejo de Errores: Es buena práctica usar bloques try/except en tu código para capturar errores y devolver un mensaje claro en lugar de romper el flujo.
Imports: Si necesitas librerías como pandas o requests, asegúrate de escribirlas en el campo Packages antes de usarlas en el código.
Seguridad: No intentes acceder a archivos del sistema ni realizar operaciones peligrosas; el entorno de ejecución (Docker) está aislado para tu seguridad.

Consideraciones de Seguridad

El componente se ejecuta en un entorno aislado (sandbox) para proteger la integridad de tu sistema. Sin embargo, ten en cuenta que:

No puedes acceder a credenciales que no estén explícitamente pasadas a través de la variable env.
El tiempo de ejecución tiene límites para evitar bloqueos del sistema en caso de bucles infinitos.
Asegúrate de no incluir claves API sensibles directamente en el código Python; úsalas siempre a través de env.