Guía del sandbox nativo y Manifest del OpenAI Agents SDK

OpenAI lanzó la importante actualización del Agents SDK el 15 de abril de 2026, y la pista estaba en la línea de instalación del post de lanzamiento: pip install "openai-agents>=0.14.0" (OpenAI). Esa línea de versión importa. No era una nueva plantilla de prompt ni otro wrapper de function calling. Era OpenAI llevando el trabajo con archivos, el trabajo de shell, los parches, el ciclo de vida del sandbox y la descripción del workspace a primitivas de nivel SDK.

Para desarrolladores que crean agentes de programación, agentes de documentos, agentes de limpieza de datos o bots de mantenimiento de repositorios, el cambio de diseño es simple: dejar de hacer que cada equipo reconstruya el mismo arnés frágil alrededor de Docker, directorios temporales, esquemas de herramientas, staging de archivos y lógica de reintentos. El SDK ahora te da un arnés nativo para modelos, ejecución nativa en sandbox, herramientas de sistema de archivos, MCP, AGENTS.md, acceso a shell, apply_patch y una abstracción Manifest para describir workspaces portables.

El cambio: de llamadas a herramientas a un workspace real

El Agents SDK original ya era útil para la orquestación: agentes, herramientas, handoffs, guardrails, tracing. La actualización de abril añade la forma de runtime que faltaba para los agentes que necesitan trabajar con archivos a lo largo del tiempo.

OpenAI describe el SDK actualizado como una ayuda para que los desarrolladores creen agentes capaces de inspeccionar archivos, ejecutar comandos, editar código y trabajar en tareas de largo horizonte dentro de entornos sandbox controlados (OpenAI). La frase “workspace controlado” es la clave. Un agente serio que trabaja con archivos necesita más que una lista de herramientas. Necesita un directorio raíz, entradas montadas, ubicaciones de salida, una shell, permisos, snapshots y una forma de reanudar cuando el contenedor muere.

Antes de esta actualización, una configuración típica de producción se veía así:

• crear un workspace temporal
• copiar archivos dentro
• exponer herramientas de lectura, escritura, shell y parcheo
• validar rutas manualmente
• iniciar un sandbox o contenedor
• recopilar artefactos
• hacer snapshot del estado si el trabajo se alarga
• traducir todo eso a instrucciones orientadas al modelo

Ese código de pegamento es donde muchos proyectos de agentes se vuelven discretamente caóticos. El nuevo SDK convierte gran parte de eso en configuración de primera clase.

El post de lanzamiento de OpenAI enumeró soporte integrado para Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel como proveedores de sandbox, junto con una vía para “traer tu propio sandbox” (OpenAI). Eso son siete proveedores alojados en el lanzamiento, además de rutas de desarrollo local.

Manifest es la capa de portabilidad

La abstracción Manifest es la parte más práctica del lanzamiento. Describe qué debe contener el workspace del sandbox antes de que el modelo empiece a trabajar.

En la documentación de Python, los Sandbox Agents están marcados como beta, requieren Python 3.10 o superior, y se presentan como una forma de dar al modelo un workspace persistente donde puede buscar en conjuntos de documentos, editar archivos, ejecutar comandos, generar artefactos y reanudar desde un estado de sandbox guardado (documentación de OpenAI Agents SDK para Python).

Una forma compacta en Python se ve así:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

Lo importante no es la sintaxis. Es el contrato. Manifest puede describir archivos locales, directorios, repositorios Git, archivos sintéticos, variables de entorno, usuarios, grupos, directorios de salida y montajes de almacenamiento remoto. La documentación de JavaScript dice que las rutas de las entradas de Manifest son relativas al workspace, no pueden ser absolutas y no pueden escapar del workspace con .., que es exactamente el tipo de restricción aburrida que quieres que imponga el runtime en lugar de recordarla en cada prompt (documentación de OpenAI Agents SDK para JS).

Capacidades: shell, sistema de archivos, skills, memoria, compactación

Un SandboxAgent no es solo un agente normal con una carpeta temporal. Lleva capacidades específicas de sandbox.

La documentación de conceptos de JS enumera capacidades integradas como shell(), filesystem(), skills(), memory() y compaction() (documentación de OpenAI Agents SDK para JS). Aquí los valores por defecto importan: la documentación indica que Capabilities.default() incluye sistema de archivos, shell y compactación. Eso significa que el bucle habitual de un agente de programación ya no es un montón de definiciones de herramientas hechas a medida.

La capacidad de sistema de archivos expone ediciones de archivos de estilo parche. La capacidad de shell expone la ejecución de comandos dentro de la sesión del sandbox. Skills permite revelar progresivamente instrucciones o procedimientos especializados. Memoria y compactación ayudan a que las ejecuciones más largas conserven estado útil sin meter todos los tokens previos en el siguiente turno.

Esto encaja con cómo funcionan realmente los buenos agentes de programación. Inspeccionan. Ejecutan un comando. Editan un archivo. Ejecutan un comando más pequeño. Inspeccionan el diff. Resumen qué cambió. Si tu arnés trata cada paso como una llamada de API no relacionada, el modelo gasta demasiada atención reconstruyendo su mundo. Una sesión de sandbox le da al modelo un lugar donde apoyarse.

AGENTS.md también encaja de forma natural en este modelo. El sitio abierto de AGENTS.md lo describe como un formato Markdown para guiar agentes de programación y dice que lo usan más de 60.000 proyectos de código abierto (AGENTS.md). Ese archivo debería contener comandos de build, instrucciones de test, reglas de estilo y advertencias específicas del repositorio. En el mundo del sandbox, AGENTS.md se convierte en contexto operativo local al workspace, no en un prompt gigante pegado en cada tarea.

Primero Python, TypeScript poniéndose al día

En el lanzamiento, esto fue primero para Python. TechCrunch informó el 15 de abril que el nuevo arnés y las capacidades de sandbox se lanzaban primero en Python, con soporte para TypeScript planeado para más adelante (TechCrunch). PyPI respalda la fecha: las versiones 0.14.0 y 0.14.1 de openai-agents se subieron el 15 de abril de 2026 (PyPI).

A 16 de junio de 2026, la foto práctica está más equilibrada. La documentación oficial de JS ahora incluye Sandbox Agents en beta, requiere Node.js 22 o superior, y muestra Manifest, SandboxAgent, UnixLocalSandboxClient, soporte para Docker y clientes de proveedores alojados a través de @openai/agents-extensions (quickstart de OpenAI Agents SDK para JS). La documentación de JS también señala que Deno y Bun pueden funcionar cuando la resolución de paquetes y las APIs de runtime son compatibles.

Área	Python	TypeScript / JavaScript
Estado de lanzamiento el 15 de abril	Primera vía soportada	Planeado para más adelante
Documentación actual de sandbox	Beta, Python 3.10+	Beta, Node.js 22+
Sandbox local	UnixLocalSandboxClient	UnixLocalSandboxClient
Sandbox Docker	openai-agents[docker]	DockerSandboxClient
Proveedores alojados	Soportados mediante integraciones del SDK	Rutas de proveedores de @openai/agents-extensions

Eso no significa que los dos ecosistemas sean idénticos. Python fue la superficie original de lanzamiento, y muchos ejemplos siguen llegando allí primero. TypeScript ahora tiene suficiente superficie oficial para prototipar agentes con sandbox reales, pero los detalles de proveedores alojados, comportamiento de PTY, montajes y soporte de ciclo de vida todavía requieren lectura cuidadosa según el backend.

Cómo estructuraría ahora un agente que trabaja con archivos

El error es tratar el sandbox como una caja mágica de seguridad. Es un límite de runtime, no una especificación de producto. Todavía tienes que diseñar el workspace.

Una estructura limpia se ve así:

• repo/: el working tree o repositorio montado
• task.md: la especificación de la tarea que el modelo debe leer primero
• inputs/: documentos, datasets, capturas de pantalla o logs de solo lectura
• output/: el único lugar al que deberían ir los artefactos finales generados
• AGENTS.md: instrucciones de build, test, estilo y seguridad
• usuario del sandbox: una identidad no root donde el backend lo soporte
• env de Manifest: configuración no secreta persistida por defecto, secretos marcados como efímeros

Manifest debería describir las entradas. Las instrucciones del agente deberían describir el flujo de trabajo. El prompt del usuario debería describir la tarea puntual. Mantén esas cosas separadas. La documentación de JS advierte explícitamente contra meter material de referencia largo en instructions cuando pertenece a Manifest (documentación de OpenAI Agents SDK para JS).

Para producción, elige el backend según el radio de impacto, no según el camino de la demo. Unix-local está bien para desarrollo. Docker es un mejor valor por defecto cuando necesitas repetibilidad. Los proveedores alojados tienen sentido cuando necesitas aislamiento limpio por ejecución, ejecución remota, escalado o comportamiento de snapshots específico del proveedor. La documentación de clientes de JS indica que el soporte de proveedores alojados varía y que los desarrolladores deberían revisar la documentación del proveedor para variables de entorno, puertos, PTY, snapshots y comportamiento de limpieza (clientes de OpenAI Agents SDK para JS).

Lectura del ecosistema

Esta actualización es importante porque estandariza la forma de los agentes que trabajan con archivos. La industria ya convergió en unas pocas primitivas: MCP para herramientas externas, AGENTS.md para instrucciones de repositorio, shell para inspección real, parches para ediciones revisables y sandboxes para contención. El Agents SDK de OpenAI ahora empaqueta esas piezas en un runtime que los desarrolladores realmente pueden componer.

El borde afilado siguen siendo los permisos. Un agente en sandbox con red amplia, montajes escribibles, credenciales de larga duración e instrucciones vagas todavía puede causar daño. Manifest ayuda porque hace visibles las entradas y concesiones del workspace. No elimina la necesidad de políticas de aprobación, higiene de secretos, fijación de dependencias y revisión de artefactos.

El mejor caso de uso hoy no es “el agente lo hace todo”. Es más estrecho y más valioso: darle al modelo un workspace acotado, un archivo de tarea claro, instrucciones locales al repositorio, herramientas de shell y parcheo, y una ruta explícita de verificación. Deja que trabaje como un ingeniero junior en un entorno desechable. Luego inspecciona el diff.

Esa es una abstracción mucho más saludable que montar a mano otro medio sandbox alrededor de un bucle de chat.

Los lectores que quieran probar estos modelos de primera mano pueden llamarlos mediante onehop con una API compatible con OpenAI cambiando un solo base_url. Es más barato que el proveedor original, y las cuentas nuevas reciben $10 de crédito gratis sin tarjeta: llama a Claude y otros modelos en onehop, o regístrate para obtener $10 de crédito gratis.