/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
containerpara reutilizar un sandbox entre solicitudes
Inicio rápido
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:- El asistente decide si ejecutar código ayudaría a responder la pregunta.
- 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.
- 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.
- La respuesta contiene cada llamada a herramienta (
server_tool_use) y su resultado, seguidos de la respuesta final del asistente. - La respuesta también contiene un objeto
containerde nivel superior. Pasa suiden solicitudes posteriores para seguir trabajando en el mismo sandbox.
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 campocontainer 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.
Leer el contenedor desde la respuesta
Cuando se ejecuta código, la respuesta incluye el contenedor que se ha usado:container llega en el evento final message_delta como delta.container.
Reutilizar un contenedor
Pasa el mismo ID decontainer 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
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 incluyenunzip, 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_TOKENyANTHROPIC_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.
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 consultascope_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}:
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:
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: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:/ 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
containertoma 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. Sifeatures.codeExecution.enabledesfalse, 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.
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 bloqueserver_tool_use seguido de su bloque de resultado.
Comando bash
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: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
containerpor 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