- API de Agentes, SDK de Agentes y API de Respuestas
- ¿Qué es un Arnés de Agente?
- Por qué un agente aún necesita un Sandbox
- Novita Sandbox en esta arquitectura
- Ciclo de vida, persistencia y trabajo de larga duración
- Conectar Novita a la ruta autoalojada
- Seguridad y credenciales
- Costos y límites
- Dónde encaja esta arquitectura
- FAQ
- Artículos Recomendados
La API de Agentes de OpenAI te permite iniciar un agente en la nube persistente mediante una única llamada de creación de sesión, mientras que OpenAI ejecuta el arnés del agente en la nube. Novita Sandbox no reemplaza la API de Agentes ni su arnés gestionado por OpenAI. Te proporciona un tiempo de ejecución aislado y con estado para la ruta de ejecución autoalojada documentada por OpenAI: tu aplicación conecta el sandbox a la sesión, el agente ejecuta comandos y edita archivos dentro de ese tiempo de ejecución, y tu aplicación es dueña del ciclo de vida del sandbox. Esta división es importante cuando deseas un flujo de trabajo de agente alojado por OpenAI, pero necesitas un entorno separado y reutilizable para código, archivos, navegadores, uso de ordenador y trabajo de larga duración.
Esta guía explica los conceptos principales de la API, cómo se dividen las responsabilidades entre el arnés y el entorno, cómo conectar un Novita Sandbox a la ruta autoalojada y qué verificar antes de pasar de un prototipo a producción. Si solo necesitas la página del producto, Novita Sandbox es el mejor punto de partida.
API de Agentes, SDK de Agentes y API de Respuestas
La comparación de tiempos de ejecución de agentes de OpenAI separa tres modelos de integración:
| Quieres | Usa | Qué gestiona el estado |
|---|---|---|
| Ejecutar una tarea de larga duración a través de un arnés Codex gestionado por OpenAI | API de Agentes | Configuración de sesión guardada, turnos e ítems |
| Mantener el bucle del agente en tu aplicación | SDK de Agentes | Estado de tu aplicación, sesiones del SDK o conversaciones de Respuestas |
| Llamar a los modelos directamente y orquestar todo tú mismo | API de Respuestas | Historial de tu aplicación o conversaciones de Respuestas |
La API de Agentes es la opción de más alto nivel. OpenAI la describe como acceso al arnés Codex a través de una API gestionada por OpenAI. Maneja sesiones, orquestación, compactación de contexto y recuperación. El SDK de Agentes se ejecuta dentro de tu aplicación y te da más control sobre el despliegue, almacenamiento, aprobaciones e integración en tiempo de ejecución. La API de Respuestas es la más cercana a la capa del modelo. Esta división es útil porque “Agente” puede significar tanto una configuración reutilizable de modelo/herramienta como un agente en ejecución persistente; la documentación de la API usa esos términos de manera diferente en cada tiempo de ejecución.
¿Qué es un Arnés de Agente?
Un arnés de agente es el servicio en la nube que rodea un turno de agente. Envía instrucciones y contexto al modelo, invoca herramientas, rastrea el progreso, maneja la interrupción y reanudación, y organiza el trabajo en un flujo inspeccionable. En la API de Agentes, ese arnés es el arnés Codex gestionado.
El arnés gestionado soporta:
- Ejecutar comandos y código cuando hay un entorno adjunto.
- Aplicar habilidades e instrucciones relevantes.
- Conectarse a datos externos a través de herramientas o MCP.
- Dirigir al agente mientras trabaja.
- Resumir trabajo anterior para gestionar la ventana de contexto.
- Dividir el trabajo en subtareas y delegar a subagentes.
- Reanudar una sesión donde se quedó.
Eso no significa que tu aplicación desaparezca. Tu aplicación aún crea la sesión, envía la entrada, recibe eventos, maneja aprobaciones o llamadas a funciones, y decide cómo almacenar IDs y artefactos. El arnés reduce el trabajo de orquestación; no elimina la política del producto.
Por qué un agente aún necesita un Sandbox
Algunos agentes responden preguntas o llaman a APIs remotas sin tocar un sistema de archivos. Otros necesitan crear archivos, instalar dependencias, ejecutar scripts, inspeccionar un navegador, controlar un escritorio o mantener una tarea de múltiples pasos viva mientras el usuario está ausente. Un sandbox proporciona a esas acciones un entorno de ejecución reemplazable en lugar de dejar que toquen tu servidor de producto o máquina local.
La API de Agentes trata el entorno como opcional. La documentación de arquitectura de OpenAI soporta tres opciones de ejecución:
none— el arnés no tiene shell ni sistema de archivos. Las herramientas de función devuelven resultados al arnés.openai_hosted— OpenAI aprovisiona y gestiona el sandbox.self_hosted— tu aplicación inicia y conecta el entorno, para que puedas usar tu propio cómputo, red privada o software personalizado.
Aquí es donde el límite entre los dos sistemas es más claro. La API de Agentes y OpenAI pueden alojar el arnés, pero un entorno autoalojado permite que tu equipo seleccione la plataforma de ejecución. Esa elección afecta el aislamiento, la forma del sistema de archivos, las redes, los SDKs, el comportamiento de pausa/reanudación, la facturación y cuánta infraestructura mantienes.
Novita Sandbox en esta arquitectura
Novita Sandbox es un entorno de ejecución gestionado para agentes de IA. La visión general oficial describe tiempos de ejecución aislados y con estado para ejecutar código, instalar dependencias, acceder a archivos, usar navegadores y preservar el estado entre sesiones sin gestión de infraestructura. En una pila directa solo de Novita, tu aplicación crea el sandbox, el modelo o framework de agente elige las llamadas a herramientas, el sandbox las ejecuta, y tu aplicación mantiene la política, aprobaciones y almacenamiento fuera del tiempo de ejecución.
Con la API de Agentes, el encuadre preciso recomendado es complementario en lugar de nativo: las guías actuales de sandbox autoalojado de OpenAI enumeran a Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI y Vercel como proveedores documentados. Novita Sandbox no está actualmente en esa lista de proveedores. Por lo tanto, la ruta práctica es usar Novita como tu entorno de ejecución gestionado por la aplicación y conectarlo a una sesión de la API de Agentes a través del contrato de entorno autoalojado de OpenAI. Eso preserva la separación útil—OpenAI ejecuta el arnés persistente, Novita Sandbox proporciona el tiempo de ejecución—sin reclamar una integración oficial de proveedor que los documentos actuales no soportan.
Novita Sandbox se basa en cinco conceptos:
| Concepto | Qué proporciona al agente |
|---|---|
| Sandbox | Un tiempo de ejecución aislado con su propio sistema de archivos y espacio de procesos |
| Plantilla | Una imagen de inicio reproducible, dependencias, configuración y preparación |
| Instantánea | Un estado de sandbox guardado que se puede reutilizar para evitar preparaciones repetidas |
| Secreto | Valores cifrados y limitados al equipo que evitan codificar credenciales |
| Región | La ubicación de los endpoints actuales US v1/v2 |
El tiempo de ejecución soporta cargas de trabajo de agente de codificación, agente de navegador, análisis de datos, investigación y RL. La visión general de Novita Sandbox es la fuente para las regiones actuales y el comportamiento del ciclo de vida.
Ciclo de vida, persistencia y trabajo de larga duración
Novita Sandbox tiene tres estados de ciclo de vida: en ejecución, pausado y terminado. Un sandbox en ejecución puede ejecutar comandos y servir conexiones. Un sandbox pausado preserva el sistema de archivos y el estado en memoria, incluidos procesos en ejecución y variables, mientras que la facturación de CPU y RAM se detiene. Las conexiones de red se interrumpen hasta que se reanuda. Un sandbox terminado se elimina y no se puede restaurar.
Dos controles de tiempo de espera impulsan las transiciones: un tiempo de espera de sandbox cuenta hacia atrás desde la creación, y un tiempo de espera de inactividad se activa cuando ningún cliente ha estado conectado durante la duración configurada. En cualquiera de los eventos, puedes elegir pausar en lugar de terminar y, opcionalmente, habilitar la reanudación automática. Esto es útil para una tarea de edición de código que espera revisión, una sesión de navegador que se pausa entre pasos o un cuaderno de análisis de datos que se reanuda más tarde con dependencias y variables intactas.
Las instantáneas son diferentes de la pausa. Pausar retiene el estado actual del sandbox para esa instancia. Una instantánea captura el estado como un entorno reutilizable, por lo que un nuevo sandbox puede comenzar con dependencias instaladas, configuración y archivos ya presentes. En producción, usa plantillas para imágenes base repetibles, instantáneas para estados de trabajo reutilizables y secretos para credenciales en lugar de incorporarlos en una plantilla o instantánea.
Conectar Novita a la ruta autoalojada
La guía de sandbox autoalojado de OpenAI define la forma de la conexión. Tu aplicación crea una sesión con environment.type: "self_hosted", recibe el ID del entorno y la URL remota, inicia un ejecutor dentro de tu tiempo de ejecución y luego informa la sesión como conectada. El comando ejecutor oficial es:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
El flujo de eventos de la sesión reporta agent.session.environment.pending, connected o failed. Debes dejar el ejecutor funcionando mientras el agente trabaja y coordinar el cierre antes de detener el cómputo.
El siguiente boceto muestra el lado de Novita de ese flujo utilizando el SDK oficial de Novita. Crea un sandbox, prepara la autenticación sin poner un secreto en el código fuente y te da el lugar para iniciar el ejecutor de OpenAI. La forma exacta de inyectar la clave del ejecutor y esperar el flujo de eventos depende de tu aplicación y la versión del SDK de OpenAI.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Crea la sesión de la API de Agentes con environment.type=self_hosted, "
"luego inicia codex exec-server aquí."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
Antes de usar esta ruta en producción, verifica los objetos actuales del SDK de OpenAI, el nombre de la clave de entorno, el comportamiento de la URL remota y los requisitos del ciclo de vida con la guía de sandbox autoalojado de OpenAI. No asumas que la API de sesión gestionará el sandbox por ti; con self_hosted, esa responsabilidad es explícitamente tuya.
Para el flujo de trabajo más simple sin la API de Agentes, la guía de agente Codex de Novita muestra cómo ejecutar la CLI de Codex directamente en la plantilla codex, transmitir su salida y terminar el sandbox cuando haya terminado.
Seguridad y credenciales
Trata el arnés, el sandbox y el servidor de aplicaciones como dominios de confianza separados.
- Mantén las claves de API de OpenAI, las claves de API de Novita, los tokens de Git y las credenciales de bases de datos fuera de los mensajes y archivos fuente.
- Usa los Secretos de Novita Sandbox para valores sensibles limitados al equipo utilizados dentro del sandbox.
- Usa las bóvedas de OpenAI para credenciales que, según la guía de OpenAI, deben estar fuera del sandbox.
- Prefiere el acceso seguro al sandbox. Los documentos de Novita indican que el acceso seguro se habilita automáticamente para los sandboxes creados con la versión 2.0.0 o superior del SDK; las plantillas personalizadas antiguas pueden necesitar una reconstrucción.
- Establece una política de red explícita y solo amplíala cuando una tarea lo necesite.
- Revisa el código y los artefactos generados antes de que reciban permisos más amplios o lleguen a sistemas de producción.
Estos controles funcionan juntos. Un sandbox reduce el radio de explosión del código generado, pero no autoriza al agente, valida la intención ni decide qué artefactos pueden salir del tiempo de ejecución.
Costos y límites
OpenAI factura el uso del modelo de la API de Agentes a las tarifas de API del modelo seleccionado y las herramientas de OpenAI a sus tarifas estándar. Para un entorno alojado por OpenAI, se aplica la tarifa del contenedor. Para una ruta autoalojada, los recursos de ejecución son el costo de tu proveedor.
La facturación de Novita Sandbox es por segundo para CPU y RAM mientras un sandbox está en ejecución. Pausar detiene los cargos de CPU y RAM. Los datos pausados se retienen como almacenamiento persistente; cada cuenta incluye 60 GB de almacenamiento persistente gratuito, y el almacenamiento adicional se factura por hora. Cada sandbox en ejecución incluye 20 GB de almacenamiento efímero. Los créditos y precios oficiales de Sandbox cambian, así que confirma los valores actuales en la página de precios de Novita Sandbox.
Los límites de cuota de Novita también importan para cargas de trabajo paralelas. Al momento de escribir esto, las cuentas gratuitas tienen por defecto 5 sandboxes concurrentes y las cuentas de pago 100; la vCPU máxima por sandbox y la memoria difieren según el nivel. Los límites empresariales se pueden ajustar. Consulta la guía de límites de cuota y Sandbox.get_quota() en lugar de confiar en ejemplos de páginas de marketing.
Dónde encaja esta arquitectura
Un tiempo de ejecución autoalojado de Novita es una buena opción cuando:
- El agente debe ejecutar código, modificar archivos, instalar dependencias, ejecutar pruebas, navegar por la web o interactuar con un escritorio.
- La aplicación necesita sesiones con estado a través de demoras humanas, reintentos o revisiones de múltiples pasos.
- Deseas una ejecución aislada separada de tu servidor de producto.
- Tu carga de trabajo se beneficia de plantillas, instantáneas, pausa/reanudación o entornos reproducibles.
No es la opción adecuada cuando:
- La tarea solo necesita llamadas a funciones remotas y ningún sistema de archivos o shell.
- Necesitas un entorno gestionado por OpenAI y no quieres ser dueño del ciclo de vida del entorno.
- Requieres un proveedor listado en las guías directas de proveedores de sandbox actuales de OpenAI.
- Tu modelo de cumplimiento requiere controles de aislamiento gestionados por el proveedor que Novita no ha documentado para tu despliegue.
La evaluación más segura es una pequeña prueba de concepto con tu repositorio real, comandos, política de red, manejo de secretos y rutas de fallo. Luego mide el inicio, pausa/reanudación, finalización de tareas y el costo total de una ejecución representativa.
FAQ
¿Se integra Novita Sandbox de forma nativa con la API de Agentes de OpenAI?
No según las guías actuales de proveedores de entornos de OpenAI. La arquitectura precisa es usar la ruta de entorno autoalojado de la API de Agentes, iniciar Novita Sandbox como tu tiempo de ejecución gestionado por la aplicación y ejecutar el ejecutor documentado dentro de él. Verifica las guías actuales antes del lanzamiento porque las integraciones de proveedores pueden cambiar.
¿Aún necesito Novita si OpenAI ofrece un sandbox alojado?
Depende de tus requisitos. El sandbox alojado de OpenAI es la ruta de bajo esfuerzo operativo. Novita Sandbox es útil cuando deseas una opción de tiempo de ejecución separada para imágenes personalizadas, plantillas, instantáneas, flujos de trabajo de navegador o uso de ordenador, pausa/reanudación con estado o control a nivel de proveedor sobre los recursos.
¿Puede el agente mantener procesos y archivos a través de una pausa?
Sí. La documentación de pausa/reanudación de Novita dice que el sistema de archivos y el estado en memoria, incluidos procesos en ejecución y variables, se preservan. Las conexiones de red se interrumpen hasta que el sandbox se reanuda.
¿Es esto lo mismo que el SDK de Agentes de OpenAI?
No. El SDK de Agentes se ejecuta en tu aplicación y te da más control sobre el bucle del agente. La API de Agentes utiliza el arnés Codex gestionado de OpenAI. Novita Sandbox puede alojar la ejecución para cualquiera de los patrones, pero el comportamiento de la sesión y la orquestación difieren.
¿Por dónde debería empezar?
Prueba el inicio rápido de la API de Agentes de OpenAI para entender las sesiones y eventos del arnés. Luego crea un Novita Sandbox y decide si su tiempo de ejecución, ciclo de vida, seguridad y modelo de costos coinciden con tus necesidades de producción.
