Python Code Structured Tool

Python Code Structured Tool es un componente que permite a los usuarios crear herramientas personalizadas dentro del dashboard de Nappai. Con él, puedes introducir tu propio código Python, darle un nombre y una descripción, y decidir si quieres que el resultado de la función se devuelva directamente o se envuelva en un objeto de herramienta. El componente se encarga de compilar el código y exponer la herramienta para que otras partes del flujo de trabajo la invoquen.

¿Cómo funciona?

El componente recibe el código de una clase dataclass que define la lógica de la herramienta. Cuando se ejecuta, Nappai compila ese código en tiempo real y crea una instancia de la herramienta. La herramienta resultante puede ser utilizada por otros nodos del flujo de trabajo, como un nodo de LLM que necesita ejecutar una función específica. Si el usuario marca la opción Return Directly, el valor devuelto por la función se pasa directamente al siguiente nodo; de lo contrario, se envuelve en un objeto de herramienta que incluye metadatos como nombre y descripción.

Entradas

Campos de Entrada

• Tool Code: Escribe el código de la clase dataclass que implementa la lógica de la herramienta.
• Tool Name: Especifica el nombre que tendrá la herramienta dentro del flujo de trabajo.
• Description: Proporciona una breve descripción de lo que hace la herramienta.
• Return Directly: Indica si la salida de la función debe devolverse directamente al siguiente nodo.
• Tool Function: Selecciona la función que se ejecutará cuando la herramienta sea llamada.
• Parent document vectorstore: Referencia al vectorstore de documentos padre que la herramienta puede usar para consultas.
• Classes: Lista de clases adicionales que la herramienta necesita (puede ser una cadena JSON o texto plano).
• Functions: Lista de funciones auxiliares que la herramienta puede invocar (puede ser una cadena JSON o texto plano).

Salidas

• Tool: Devuelve el objeto de herramienta construido. Este objeto puede ser conectado a otros nodos que requieran una herramienta personalizada.
• Text: Devuelve la respuesta de texto generada por la herramienta, útil cuando la herramienta produce una salida textual directamente.

Ejemplo de Uso

Supongamos que quieres crear una herramienta que sume dos números:

1. Tool Code

   from dataclasses import dataclass
   
   @dataclass
   class SumTool:
       a: int
       b: int
   
       def run(self) -> int:
           return self.a + self.b

2. Tool Name: SumNumbers

3. Description: Suma dos números enteros y devuelve el resultado.

4. Return Directly: True

5. Tool Function: run

6. Parent document vectorstore: (dejar vacío si no se necesita)

7. Classes: (dejar vacío)

8. Functions: (dejar vacío)

Con esta configuración, cuando el flujo de trabajo invoque la herramienta SumNumbers, el resultado será el valor entero de la suma, listo para ser usado por el siguiente nodo.

Componentes Relacionados

• CustomPythonCodeStructuredTool – La clase base que maneja la compilación y ejecución del código Python.
• Output – Nodo que permite mostrar la salida de la herramienta en el dashboard.

Consejos y Mejores Prácticas

• Prueba tu código localmente antes de introducirlo en el flujo de trabajo para evitar errores de compilación.
• Limita las importaciones a módulos estándar o a aquellos que estén explícitamente permitidos por Nappai.
• Evita código que modifique el sistema (por ejemplo, os.system, subprocess, etc.) a menos que sea absolutamente necesario y esté sandboxed.
• Usa nombres descriptivos para la herramienta y la función para facilitar su identificación en flujos complejos.
• Documenta la herramienta con una descripción clara; esto ayuda a otros usuarios a entender su propósito sin revisar el código.

Consideraciones de Seguridad

Ejecutar código Python arbitrario puede representar un riesgo de seguridad. Nappai ejecuta el código en un entorno aislado, pero es recomendable:

• Revisar el código antes de cargarlo.
• Evitar dependencias externas que no estén aprobadas.
• Monitorizar el uso de la herramienta para detectar comportamientos inesperados.

Con estos cuidados, podrás aprovechar al máximo el poder de las herramientas personalizadas sin comprometer la integridad de tu sistema.