- Qué aporta un intérprete de código a una aplicación de IA
- Arquitectura de referencia
- Flujo de implementación
- Manejar archivos, salidas y artefactos generados
- Establecer política de paquetes y red
- Aplicar límites, registros, limpieza y revisión
- Dónde encaja Novita Agent Sandbox
- Lista de verificación de evaluación
- Conclusión
- Preguntas frecuentes
- Artículos recomendados
Agrega un intérprete de código a una aplicación de IA redirigiendo la ejecución de código solicitada por el modelo a un sandbox aislado con archivos delimitados, una política de paquetes clara, límites de recursos y tiempo, salidas capturadas y una revisión del lado de la aplicación antes de que los resultados se muestren o persistan. El modelo puede decidir cuándo el código es útil, pero tu aplicación debe poseer el límite de ejecución: sube solo los archivos necesarios para la tarea, crea o reutiliza una sesión de sandbox de corta duración, ejecuta Python con límites estrictos, captura stdout, stderr, archivos generados y registros, devuelve un resultado estructurado al modelo y limpia la sesión cuando el flujo de trabajo haya terminado.
Qué aporta un intérprete de código a una aplicación de IA
Un intérprete de código convierte un modelo de lenguaje de un asistente solo de texto a una aplicación que utiliza herramientas y puede calcular, transformar archivos, inspeccionar datos, generar gráficos y producir artefactos revisables. En lugar de pedirle al modelo que razone sobre una hoja de cálculo a partir de un mensaje, la aplicación puede permitir que el modelo escriba Python, lo ejecute contra el archivo subido, inspeccione la salida y explique el resultado.
El patrón útil no es “dejar que el modelo ejecute cualquier cosa”. El patrón útil es la ejecución controlada. Tu aplicación acepta una tarea de usuario, permite que el modelo solicite una llamada a herramienta como run_python, y luego ejecuta esa solicitud dentro de un sandbox en lugar de en el proceso principal de la aplicación. El sandbox se convierte en el banco de trabajo para archivos temporales, instalaciones de paquetes, scripts, gráficos y registros.
Las funciones de intérprete de código son especialmente útiles para:
- análisis de CSV, Excel, JSON y registros
- generación de gráficos a partir de datos subidos
- conversión de formato y limpieza de datos
- tareas de matemáticas y simulación que necesitan cálculo exacto
- fragmentos de código que necesitan ser probados antes de que el modelo los explique
- flujos de trabajo de agente de múltiples pasos donde las salidas de un paso se convierten en entradas del siguiente
Son una mala opción para tareas que requieren credenciales de producción sin restricciones, acceso de larga duración a sistemas privados o ejecución silenciosa sin un rastro de auditoría visible para el usuario. Si el resultado puede afectar dinero, infraestructura, seguridad o control de acceso, agrega puertas de revisión antes de que cualquier efecto secundario salga del sandbox.
Arquitectura de referencia
Una arquitectura práctica de intérprete de código tiene cinco partes:
| Capa | Responsabilidad | Elección de diseño común |
|---|---|---|
| Interfaz de usuario | Subir archivos, mostrar progreso, mostrar artefactos, solicitar aprobación | Mantener los archivos subidos dentro del alcance de la conversación o proyecto actual |
| Servidor de aplicación | Autenticar usuarios, aplicar políticas, crear sesiones de sandbox, almacenar registros | Nunca exponer credenciales de sandbox en bruto al navegador |
| Orquestación del modelo | Decidir cuándo llamar a herramientas de código y resumir resultados | Usar llamadas a herramienta estructuradas en lugar de analizar texto libre |
| Entorno de ejecución del sandbox | Ejecutar Python, mantener archivos temporales, instalar paquetes permitidos | Ejecutar con controles de recursos, tiempo de espera y limpieza |
| Almacén de artefactos | Conservar salidas aprobadas como gráficos, CSV, informes y registros | Almacenar solo salidas que la aplicación o el usuario hayan aceptado |
El modelo no debe controlar directamente la infraestructura. Debe solicitar una llamada a herramienta. Tu aplicación decide si esa llamada a herramienta está permitida, qué archivos se adjuntan, cuánto tiempo puede ejecutarse, qué paquetes están disponibles y qué salidas se devuelven.
Esa separación mantiene al modelo útil sin convertirlo en el límite de seguridad.
Flujo de implementación
Un flujo de implementación sólido comienza antes de que se ejecute cualquier código.
1. Aceptar la tarea y los archivos del usuario
Cuando el usuario sube un archivo, almacénalo bajo un registro de archivo a nivel de aplicación con propietario, espacio de trabajo, tipo de contenido, tamaño y política de retención. No expongas inmediatamente todos los archivos en la cuenta del usuario al intérprete. El sandbox debe recibir solo los archivos necesarios para la tarea actual.
Por ejemplo, un usuario podría preguntar:
“Analiza este CSV, encuentra los principales impulsores de ingresos y devuelve un gráfico más una breve explicación.”
Tu aplicación puede adjuntar el CSV subido al siguiente turno del modelo como un archivo disponible, pero los bytes reales del archivo deben moverse al sandbox solo cuando se apruebe la ejecución del código.
2. Permitir que el modelo solicite una llamada a herramienta
Define una superficie de herramienta estrecha. Una primera versión típica solo necesita unas pocas herramientas:
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
Mantén el esquema explícito. El modelo debe declarar el código, los archivos de entrada, las salidas esperadas y una solicitud de tiempo de espera. La aplicación puede acortar el tiempo de espera, rechazar archivos desconocidos o bloquear comandos que entren en conflicto con la política.
3. Crear o reutilizar una sesión de sandbox
Para una respuesta de asistente única, crea una nueva sesión de sandbox, sube los archivos de entrada, ejecuta el código, recoge el resultado y finaliza la sesión. Para una experiencia de usuario tipo cuaderno, mantén la sesión activa durante la conversación actual para que celdas posteriores puedan reutilizar variables y archivos anteriores.
Las sesiones de corta duración son más fáciles de razonar. Las sesiones con estado son más ergonómicas para tareas de análisis. Elige deliberadamente y muestra al usuario cuándo existe el estado.
4. Ejecutar Python y capturar resultados
Ejecuta el código a través de la API de ejecución del sandbox o tu propio trabajador dentro del sandbox. Captura la salida de ejecución estructurada:
{
"status": "success",
"stdout": "Cargadas 12,448 filas\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
Devuelve este resultado estructurado al modelo. El modelo puede entonces explicar lo que sucedió, citar los archivos generados y preguntar si el usuario quiere otra iteración.
5. Devolver resultados al usuario
No obligues al usuario a leer registros en bruto a menos que algo haya fallado. Una buena interfaz muestra la respuesta, el gráfico o archivo generado, y una pequeña divulgación de que se ejecutó código. Proporciona un registro de ejecución expandible para revisión.
Para ejecuciones fallidas, muestra un error conciso y permite que el modelo revise el código. Evita volcar largos tracebacks en el chat principal a menos que el usuario esté depurando.
Manejar archivos, salidas y artefactos generados
El manejo de archivos es donde muchos proyectos de intérprete de código se vuelven desordenados. Trata las entradas y salidas como objetos separados.
Los archivos de entrada deben copiarse en el sandbox bajo rutas estables y saneadas. Evita conservar nombres de ruta proporcionados por el usuario que contengan espacios, caracteres de shell o directorios anidados. Mantén un mapeo del nombre mostrado a la ruta del sandbox en el estado de la aplicación.
Los archivos generados deben escanearse y clasificarse antes de convertirse en artefactos descargables. Una imagen de gráfico, un CSV limpio, un resumen JSON o un informe PDF pueden ser seguros para presentar directamente. Un script generado, un archivo ejecutable o un archivo comprimido deben requerir un manejo más estricto.
Para la generación de gráficos, pide al modelo que guarde explícitamente los archivos de imagen en lugar de depender solo de la visualización en línea. Para el análisis de datos, pide un archivo de resumen legible por máquina además de una explicación en lenguaje natural. Eso le da a tu aplicación algo estable para validar y almacenar.
Una política de artefactos útil se ve así:
| Tipo de artefacto | Manejo predeterminado |
|---|---|
Gráficos .png, .jpg, .webp, .svg |
Vista previa en la interfaz después de verificaciones de tamaño y tipo |
Salidas de datos .csv, .json, .xlsx |
Ofrecer como descargas y resumir cambios |
Informes .txt, .md, .pdf |
Vista previa o descarga según el tamaño |
.py, .sh, binarios, archivos comprimidos |
No ejecutar ni abrir automáticamente; requieren revisión explícita |
Si tu aplicación admite proyectos persistentes, almacena los artefactos aceptados fuera del sandbox. El sandbox debe seguir siendo desechable.
Establecer política de paquetes y red
La mayoría de los flujos de trabajo de intérprete de código necesitan paquetes como pandas, NumPy, matplotlib, seaborn, scikit-learn u openpyxl. La cuestión es si los paquetes están preinstalados, se instalan bajo demanda o se integran en plantillas de sandbox personalizadas.
Los paquetes preinstalados mantienen la ejecución predecible. Las instalaciones bajo demanda son flexibles pero pueden ralentizar las tareas e introducir desviaciones en las dependencias. Las plantillas personalizadas suelen ser el mejor camino de producción una vez que conoces tus cargas de trabajo comunes.
Establece una política de paquetes antes del lanzamiento:
- qué paquetes están siempre disponibles
- si el modelo puede solicitar instalaciones de paquetes
- si las instalaciones pueden alcanzar índices de paquetes públicos
- si se requieren versiones fijas
- cuánto tiempo pueden ejecutarse las instalaciones
- si se permiten paquetes compilados o nativos
La política de red es igualmente importante. Muchas tareas de datos no necesitan acceso a internet después de que los archivos se suben. Si un flujo de trabajo necesita APIs externas, enruta las credenciales a través de herramientas aprobadas por la aplicación en lugar de colocar secretos amplios en el sandbox. El modelo no debe recibir variables de entorno sin restricciones por defecto.
Aplicar límites, registros, limpieza y revisión
Un intérprete de código es una característica de producción, no un ejecutor de celdas de demostración. Pon límites a su alrededor desde el principio.
Los controles mínimos deben incluir:
- tiempo máximo de ejecución por celda o llamada a herramienta
- tamaño máximo de salida para stdout y stderr
- tamaño máximo de artefacto y número de archivos
- límites de CPU y memoria apropiados para la tarea
- extensiones de archivo permitidas para vista previa y descarga
- límites de concurrencia por usuario y por espacio de trabajo
- reglas de limpieza para sesiones y archivos temporales
Los registros deben responder tres preguntas: quién solicitó la ejecución, qué código se ejecutó y qué salidas se produjeron. Almacena suficiente para depurar y auditar el flujo de trabajo, pero evita retener datos privados subidos por más tiempo del que requiere tu política de producto.
La revisión humana o del usuario es el control final. Para análisis de bajo riesgo, la revisión puede significar que el usuario vea el gráfico antes de descargarlo. Para flujos de trabajo de agente que pueden actualizar tickets, escribir en bases de datos o llamar a APIs externas, la revisión debe ocurrir antes del efecto secundario, no después.
Dónde encaja Novita Agent Sandbox
Novita Agent Sandbox está diseñado para agentes de IA que necesitan entornos de ejecución aislados para ejecución de código, flujos de trabajo de navegador, tareas de tipo uso de computadora, evaluaciones, entornos de aprendizaje por refuerzo y flujos de trabajo de larga duración. Para una función de intérprete de código, esto significa que el sandbox puede servir como la capa de ejecución mientras tu aplicación sigue siendo responsable de la autenticación de usuario, orquestación del modelo, política de archivos, revisión y retención específica del producto.
La documentación de Novita sandbox incluye flujos de trabajo del sistema de archivos para leer, escribir, subir, descargar y observar archivos en un sandbox. Esas capacidades se corresponden directamente con las necesidades del intérprete de código: mover archivos de usuario al entorno de ejecución, permitir que el código genere gráficos o datos transformados, y luego traer las salidas seleccionadas de vuelta a la aplicación. Consulta la documentación del sistema de archivos de Novita sandbox para obtener una visión general de las operaciones de archivos actuales.
Si tu intérprete crece más allá de un simple ejecutor de Python, las plantillas de sandbox personalizadas pueden ayudar a estandarizar las dependencias y la configuración del entorno de ejecución. Esto es útil cuando cada sesión necesita la misma pila de análisis, herramientas de línea de comandos internas o bibliotecas específicas del proyecto. Comienza con un conjunto pequeño de paquetes permitidos, luego mueve la configuración repetida a plantillas una vez que la carga de trabajo se estabilice.
Mantén las decisiones de integración específicas de Novita separadas de la arquitectura general. Tu intérprete de código todavía necesita políticas a nivel de aplicación para la visibilidad de archivos, instalación de paquetes, acceso a la red, retención de registros y revisión. El sandbox proporciona el entorno de ejecución controlado; tu producto define cómo se utiliza ese entorno.
Lista de verificación de evaluación
Antes de lanzar, prueba la función con flujos de trabajo reales y mensajes adversariales.
| Pregunta | Qué verificar |
|---|---|
| ¿Pueden los usuarios subir los archivos correctos? | Verificaciones de tamaño, tipo, propietario y mensajes de error claros |
| ¿Puede el modelo solicitar ejecución limpiamente? | Llamadas a herramienta estructuradas con código, entradas, salidas esperadas y tiempo de espera |
| ¿Está el sandbox correctamente delimitado? | Solo están disponibles los archivos y variables de entorno aprobados |
| ¿Son los paquetes predecibles? | Los paquetes comunes funcionan, los paquetes denegados fallan claramente, las instalaciones tienen límites |
| ¿Son las salidas utilizables? | Los gráficos se renderizan, los archivos se descargan, los resúmenes coinciden con los artefactos generados |
| ¿Son recuperables los fallos? | Los tracebacks se capturan, el modelo puede revisar el código, los usuarios ven errores concisos |
| ¿Se aplican los límites? | Los bucles infinitos, salidas enormes, tareas con uso intensivo de memoria e instalaciones largas terminan |
| ¿Está integrada la revisión? | Los usuarios pueden inspeccionar el código, los registros y los artefactos antes de efectos secundarios importantes |
| ¿Es fiable la limpieza? | Los archivos y sesiones temporales se eliminan o expiran según lo programado |
La mejor primera versión suele ser estrecha: ejecución de Python, un conjunto pequeño de paquetes, subida de archivos, gráficos y archivos descargables, límites claros y un registro de ejecución. Agrega instalaciones de paquetes más amplias, sesiones persistentes, acceso a API externas y efectos secundarios de agente solo después de que el bucle básico sea observable y fiable.
Conclusión
Un intérprete de código funciona mejor cuando el modelo puede solicitar ejecución, pero tu aplicación controla el sandbox, los archivos, los límites y el paso de revisión. Comienza con una herramienta Python estrecha, mantén las entradas y salidas explícitas, y expande solo después de que el flujo sea estable.
Preguntas frecuentes
¿Cuál es la forma más segura de agregar un intérprete de código?
Usa un sandbox aislado, delimita los archivos de entrada, limita el tiempo de ejecución y la memoria, y devuelve salidas estructuradas en lugar de acceso de shell en bruto.
¿Debería el modelo controlar las instalaciones de paquetes?
Solo dentro de una política que tú definas. Muchas aplicaciones comienzan con un conjunto fijo de paquetes y agregan instalaciones más tarde si la carga de trabajo lo necesita.
¿Todas las tareas de intérprete de código necesitan acceso a la red?
No. Muchos flujos de trabajo de análisis funcionan completamente sin conexión una vez que los archivos del usuario se suben, lo que mantiene el modelo de ejecución más simple.
¿Qué debería ver el usuario después de la ejecución?
El resultado, los artefactos generados y un registro o resumen de error conciso, con la opción de inspeccionar el código o volver a ejecutar la tarea.
