Skip to main content
La herramienta de ejecución de código permite al asistente ejecutar comandos bash y crear, ver y editar archivos dentro de un contenedor aislado (sandbox), directamente dentro de una solicitud a /messages. Úsala para analizar datos subidos, hacer cálculos, transformar documentos o generar archivos como gráficos, hojas de cálculo e informes. Sigue el mismo modelo que la herramienta de ejecución de código de Anthropic: el servidor ejecuta todos los comandos, así que nunca tienes que ejecutar código ni enviar bloques tool_result por tu cuenta.

Requisitos previos

  • Un token de API. Ver Backoffice Developer Console.
  • Un proveedor de ejecución de código configurado, incluido por defecto en los despliegues estándar de Zylon 1.58. Para las solicitudes de la API del Workspace, también debe estar habilitada la funcionalidad del Workspace. Consulta Ejecución de código para la configuración y el comportamiento al desactivarla.

Requisitos

  • Especificación de la herramienta: { "name": "code_execution", "type": "code_execution_v1" }
  • También se acepta la especificación compatible con Anthropic: { "name": "code_execution", "type": "code_execution_20250825" }
  • No requiere tool_context
  • Opcional: un ID de container para reutilizar un sandbox entre solicitudes

Inicio rápido

Para comprobar la solicitud sin ejecutarla, envía el mismo cuerpo a POST /api/gpt/v1/messages/validate.

Cómo funciona la ejecución de código

Cuando añades la herramienta de ejecución de código a una solicitud:
  1. El asistente decide si ejecutar código ayudaría a responder la pregunta.
  2. La herramienta se expande en dos subherramientas que el asistente puede combinar libremente:
    • bash_code_execution: ejecuta comandos de shell.
    • text_editor_code_execution: ve, crea y edita archivos.
  3. Cada operación se ejecuta en el servidor dentro de un contenedor aislado, y los resultados se devuelven al asistente dentro de la misma solicitud.
  4. La respuesta contiene cada llamada a herramienta (server_tool_use) y su resultado, seguidos de la respuesta final del asistente.
  5. La respuesta también contiene un objeto container de nivel superior. Pasa su id en solicitudes posteriores para seguir trabajando en el mismo sandbox.
En solicitudes dudosas, pídelo explícitamente (por ejemplo, “ejecuta código para verificarlo”) para que el asistente use el sandbox en lugar de responder de memoria.

Subherramientas

bash_code_execution Cada llamada se ejecuta en una shell nueva. Los archivos persisten entre llamadas; las variables de entorno y cd, no. text_editor_code_execution Las rutas relativas se resuelven respecto al espacio de trabajo (/home/agent/workspace/).

Contenedores

Un contenedor es un sandbox aislado con su propio sistema de archivos. El contenedor se identifica con un ID de tipo cadena que eliges tú o que asigna el servidor.

Seleccionar un contenedor

Establece el campo container de nivel superior con el ID que quieras usar. Si el contenedor todavía no existe, se crea; si existe, la solicitud lo reutiliza junto con todos sus archivos.
Si omites container, el sandbox se asocia al usuario autenticado, de modo que todas las solicitudes de ese usuario sin container comparten el mismo sandbox. Usa un ID de container explícito y único por conversación o tarea para mantener el trabajo aislado.

Leer el contenedor desde la respuesta

Cuando se ejecuta código, la respuesta incluye el contenedor que se ha usado:
En streaming, el objeto container llega en el evento final message_delta como delta.container.

Reutilizar un contenedor

Pasa el mismo ID de container en las solicitudes de seguimiento para conservar los archivos creados anteriormente:
expires_at es un valor móvil que se renueva con cada solicitud. Cuando un contenedor está inactivo, su sandbox se apaga para liberar recursos, pero sus archivos se conservan. La siguiente solicitud con el mismo ID arranca un sandbox nuevo con los mismos archivos. Los paquetes instalados, los procesos en ejecución y el estado de la shell no se conservan. Para empezar desde cero, usa un ID de container nuevo o elimina los archivos.

Estructura del sistema de archivos

Si tu aplicación espera un archivo generado, pide al asistente que lo guarde en /mnt/user-data/outputs/ (por ejemplo, “guarda el gráfico como /mnt/user-data/outputs/chart.png”).

Entorno de ejecución

El sandbox incluye Python 3 con las librerías de datos más habituales: pandas, numpy, scipy, scikit-learn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab, img2pdf, sympy, mpmath, tqdm, python-dateutil, pytz y joblib. Entre las herramientas de línea de comandos se incluyen unzip, unrar, 7zip, bc, rg, fd y sqlite3.

Red y seguridad

  • Sin acceso a internet. El sandbox no puede acceder a internet, por lo que no se pueden instalar paquetes en tiempo de ejecución. Solo están disponibles las librerías preinstaladas.
  • Acceso a la API de Zylon. El sandbox puede acceder a la API de Zylon, con estas variables de entorno ya definidas: ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_MODEL. El código que se ejecuta en el sandbox, como un script que use el SDK de Anthropic, puede llamar al modelo con los permisos del usuario que envió la solicitud.
  • Aislamiento. Cada contenedor se ejecuta en su propio sandbox, aislado del host y del resto de contenedores.
Tu operador puede permitir el acceso a servicios internos adicionales. Ver Ejecución de código.

Trabajar con archivos

Usa la Files API para colocar archivos en un contenedor antes de una solicitud, y para listar, descargar y eliminar los archivos que haya generado. Todas las llamadas a la Files API reciben un parámetro de consulta scope_id: es el ID del contenedor.

Subir archivos

Sube un archivo a la carpeta de subidas del contenedor. Estará disponible para el asistente en /mnt/user-data/uploads/{filename}:
Respuesta:
El id es el ID de archivo que usan el resto de endpoints. Es la ruta del sandbox codificada en base64url (en este caso, /mnt/user-data/uploads/sales.csv), sin relleno. Usa el parámetro de consulta path para elegir la clave, por ejemplo para organizar los archivos en carpetas. Las carpetas padre se crean automáticamente, y subir a una clave existente la sobrescribe:
Una clave que empieza por outputs/ coloca el archivo en /mnt/user-data/outputs/. Las claves deben ser relativas y no pueden contener .. ni terminar en /. También puedes colocar bytes en bruto en una clave, al estilo de S3:

Analizar archivos subidos

Después de subirlo, envía un mensaje con el mismo ID de contenedor y haz referencia al archivo por su ruta:

Listar archivos

Lista todos los archivos de un contenedor, tanto los subidos como los generados, ordenados por fecha de creación:
downloadable es true para los archivos de /mnt/user-data/outputs/ y false para los subidos. Parámetros de consulta opcionales:

Descargar archivos

Descarga un archivo con su ID:
Añade disposition=inline para abrir el archivo en el navegador en lugar de descargarlo. El ID de archivo es la ruta del sandbox codificada en base64url, así que también puedes construirlo tú mismo:

Eliminar archivos

Elimina un archivo, ya sea uno subido, una salida generada o un archivo del espacio de trabajo:
Elimina todos los archivos subidos bajo un prefijo. Termina el prefijo en / para no eliminar claves hermanas que comparten el mismo texto:

Ejemplo completo

Ejecución de código en la Workspace API

Cuando usas la Workspace API en lugar de llamar directamente a la API de ZylonGPT, Zylon gestiona el contenedor por ti:
  • El contenedor es el hilo del chat. Cada hilo tiene su propio sandbox, y el campo container toma el ID del hilo. Los archivos persisten durante toda la vida del hilo, y los hilos no pueden ver los archivos de otros hilos.
  • La ejecución de código se añade automáticamente cuando la solicitud usa Skills y la funcionalidad del Workspace está habilitada. También puedes solicitarla explícitamente mediante pgpt.tools. Si features.codeExecution.enabled es false, el Workspace elimina estas herramientas, incluidas las solicitadas explícitamente. Este flag no desactiva globalmente el proveedor de la API de ZylonGPT; consulta Cuando está desactivada.
  • Los archivos generados se convierten en artefactos. Cuando el asistente presenta un archivo, Zylon lo guarda como artefacto en el proyecto y lo devuelve en el stream como un bloque zylon-resource, para que los usuarios puedan previsualizarlo y descargarlo.
Usa los endpoints del hilo para gestionar los archivos del sandbox de un hilo:
Las descargas dependen de la configuración de tu organización: los archivos generados (outputs/) requieren que estén habilitadas las descargas de recursos generados, y los archivos subidos (uploads/) requieren que estén habilitadas las descargas de recursos subidos.

Formato de respuesta

Cada llamada a una subherramienta aparece como un bloque server_tool_use seguido de su bloque de resultado.

Comando bash

Un return_code distinto de cero no es un error: significa que el comando se ejecutó y falló, y el asistente puede leer stderr y volver a intentarlo.

Operaciones con archivos

Ver:
Crear:
Editar (str_replace e insert):

Errores

Cuando una herramienta no puede ejecutarse, su resultado contiene un bloque de error:
detail.explanation contiene el motivo subyacente. Es una extensión de Zylon y se omite en las respuestas compatibles con Anthropic.

Consejos

  • Usa un ID de container por conversación o tarea, y reutilízalo en todas las solicitudes de seguimiento y llamadas a la Files API.
  • Pide que los entregables se guarden en /mnt/user-data/outputs/ para poder listarlos y descargarlos.
  • Combina la ejecución de código con otras herramientas, como Web Fetch o Búsqueda semántica, para incorporar datos al análisis.
  • Elimina los archivos subidos y las salidas que ya no necesites: los archivos permanecen en el contenedor hasta que los borras.

Próximos pasos

  • Descubre cómo los mensajes devuelven bloques de herramientas: Mensajes
  • Gestiona turnos de larga duración: Motivos de parada