Prueba de entorno aislado para la API de agentes: Ejecutor de CSV, verificaciones de artefactos y manejo de fallos

Este experimento parte de una pregunta concreta: ¿puede una sesión de la API de Agents aceptar un archivo, trabajar en él dentro de un entorno aislado y devolver un resultado que pueda verificarse? Un pequeño ejecutor en Python responde a esta pregunta. La entrada es un archivo CSV con transacciones que incluyen cuatro ventas, un reembolso y una fila inválida. El agente genera un resumen en formato JSON, y la aplicación calcula por sí misma la respuesta esperada para poder compararlas. Todas las opiniones aquí expresadas son personales y provienen de pruebas realizadas con una cuenta personal de OpenAI en el plan Pro, junto con la documentación disponible en ese momento.

El 10 de septiembre de 2026, la API Agents de OpenAI entró en su versión beta pública, presentando un mecanismo gestionado llamado Codex que impulsa el ciclo de modelo y herramientas. La aplicación que realiza la llamada proporciona la tarea y decide dónde se ejecutan las instrucciones. A continuación se explica cómo se construye el ejecutor. Las cinco pruebas registradas provienen de una versión anterior de este. El ejecutor revisado añade reproducibilidad y permite guardar evidencias, y hasta ahora solo se ha probado de forma offline.

01 Cómo se integra la API Agents

Hay cuatro componentes que deben mantenerse separados. El agente lleva consigo el modelo, las instrucciones y las herramientas. El entorno proporciona recursos de cómputo opcionales. La sesión mantiene unido todo el trabajo a lo largo del tiempo. Los eventos e ítems informan sobre lo que está sucediendo en ese momento y sobre lo que se ha almacenado. Una vuelta corresponde a un único recorrido por ese ciclo.

La configuración alojada en este experimento es la siguiente: el ejecutor de Python abre la sesión y obtiene los resultados, mientras que OpenAI gestiona el entorno de ejecución y la caja de arena.

La primera pregunta de diseño es dónde debe residir el bucle del agente. Con la API de Agents, OpenAI aloja el entorno de ejecución y mantiene las sesiones de forma persistente. El SDK de Agents ejecuta el bucle en su propia aplicación, por lo que usted elige el almacenamiento y las integraciones. La API de Responses ofrece acceso directo al modelo y deja el flujo de trabajo circundante en sus manos.

Responses también puede ejecutar comandos de shell alojados, por lo que un cálculo en CSV por sí solo no necesita la API de Agents. El ejecutor utiliza la API para gestionar todo el proceso, desde la sesión hasta el resultado final. Cada prueba crea una sesión nueva y ejecuta una tarea; no prueba la persistencia en múltiples turnos ni subagentes.

02 ¿Por qué una caja de arena alojada?

El trabajo solo necesita un lugar donde guardar el archivo CSV y el archivo de Python que genera el agente. No requiere red privada ni imagen personalizada, por lo que el ejecutor elige openai_hosted con la red de sandbox desactivada. Las alternativas suelen cambiar quién es el propietario del espacio de trabajo y cómo se devuelven los archivos.

El valor none significa que no existe un sistema de archivos de entorno ni ejecución integrada de Bash, aunque las funciones de la aplicación y los servidores MCP remotos aún pueden ejecutar código en otro lugar. Con self_hosted, OpenAI sigue ejecutando el entorno, pero usted gestiona el entorno de ejecución.

El manejo de las salidas corresponde a esta opción. Los archivos en un entorno autoalojado no se publican a través de la API Artifacts de OpenAI, incluso cuando el agente los escribe en /workspace/outputs. Su aplicación debe recuperarlos y conservarlos por sí misma.

Configuraciones alojadas relevantes aquí

La guía alojada también aborda las variables de entorno, habilidades, complementos y directorios de capacidades. En este caso, los archivos iniciales y el acceso deshabilitado a la red de sandbox son suficientes. Las conexiones remotas MCP parten del servicio de OpenAI, por lo que los ajustes de salida de sandbox no deben considerarse como política para cada conexión de herramienta.

03 Dentro del ejecutor CSV

El código se encuentra en openai-agents-api/sandbox_check.py, y el ejemplo completo está en el directorio openai-agents-api del repositorio techforum-repo ai-agents-experimentation en GitHub. El ejecutor genera cantidades en centavos enteros y guarda su semilla. Cada archivo CSV incluye intencionalmente casos complicados: símbolos monetarios, separadores de miles, espacios en blanco no deseados, un reembolso negativo y una entrada N/A.

La entrada seed-42

amount,note
 $981.96 ,sale
" $1,838.10 ",sale
 $42.78 ,sale
-$100.12,refund
N/A,voided
 $155.92 ,sale

El generador local obtiene la referencia que se muestra a continuación directamente de esas cantidades enteras. Es el resultado esperado para este dispositivo y no una respuesta reciente de un agente en vivo.

{
  "total_cents": 291864,
  "valid_rows": 5,
  "invalid_rows": 1
}

Las instrucciones enviadas

Al agente se le entrega el archivo CSV junto con una tarea por escrito, y la respuesta esperada nunca sale de la aplicación. Resumen de la tarea: crear /workspace/outputs/calculate.py y ejecutarlo con Python; cargar /workspace/data.csv; eliminar los espacios en blanco, los signos de dólar y los separadores de miles de cada monto; ignorar los valores que no son numéricos pero conservar los reembolsos negativos; realizar los cálculos con Decimal o centavos enteros, nunca con flotantes binarios; generar /workspace/outputs/summary.json con exactamente tres campos enteros denominados total_cents, valid_rows y invalid_rows; contar cada fila de datos una sola vez y excluir el encabezado; y conservar calculate.py como archivo de salida.

La función run_trial() abre una sesión mediante client.beta.agents.sessions.create(), pasando gpt-6-astra junto con esas instrucciones como agente, y carga /workspace/data.csv mediante codificación base64 integrada. El entorno es openai_hosted con network.access establecido en disabled. Se trata del mismo camino de API que utilizó el experimento original.

Qué se verifica y se guarda

1. Se monitorea el turno correcto. Después de obtener la sesión, el ejecutor verifica el turno raíz. Una sesión fallida, una acción requerida, un turno fallido, una cancelación o un agotamiento del presupuesto de verificación generan cada uno un resultado distinto.
2. Se obtienen ambos archivos solicitados. Tanto summary.json como calculate.py se comparan por su ruta y por el ID del turno, lo que impide que un archivo ausente o desactualizado sea aceptado.
3. Valide el resumen. Deben coincidir exactamente tres campos enteros con la referencia local: el total en centavos, el conteo de filas válidas y el conteo de filas inválidas. El analizador rechaza valores adicionales, faltantes, duplicados, booleanos, flotantes y no finitos.
4. Guarde las pruebas. Para cada prueba, el ejecutor almacena la entrada, la respuesta esperada, la solicitud, la sesión más reciente, los registros de turnos, los elementos guardados, los metadatos del artefacto, los archivos recuperados y un archivo de resultados que las máquinas puedan analizar.

La guía de artefactos explica cómo se relacionan los archivos con los turnos, mientras que la guía de observabilidad aborda el examen de la actividad de los comandos. La verificación automática confirma que existen archivos y que la salida estructurada es exacta. El script y los elementos guardados aún merecen ser revisados antes de que alguien afirme cómo se realizó el cálculo. El código descargado nunca se ejecuta en la máquina de la aplicación.

04 Lo que muestran las cinco pruebas registradas

La ejecución original registró sus resultados el 15 de septiembre de 2026, y cada prueba utilizó un CSV recién aleatorizado. Se conservaron las cifras de esa ejecución. Se trata de observaciones del lado del cliente realizadas después de la respuesta de creación, y los tiempos excluyen tanto la creación de la sesión como la descarga del archivo.

Cada uno de los cinco totales reportados por el agente coincidió con las cifras de referencia. Esa verificación utilizó aritmética de punto flotante con una tolerancia inferior a un centésimo. Los registros de tiempo indican cuándo la consulta inicial detectó un cambio y una sesión establecida, por lo que no miden ni el tiempo exacto de ejecución del servidor ni la latencia de extremo a extremo. Cinco pruebas exitosas describen lo que ocurrió en una sola ejecución pequeña y no dicen nada sobre una tasa general de fiabilidad.

Qué cambia con el ejecutor actualizado

El ejecutor revisado repite el mismo pequeño experimento con una definición más estricta de éxito. Se comparan con precisión los centavos enteros y el número de filas, se almacena cada entrada inicial, y se conservan el script generado y el historial de la sesión. El cronometraje comienza antes de la creación de la sesión, siendo el tiempo de descarga y verificación medido por separado. Ocho pruebas sin conexión cubren estas verificaciones, y las cifras anteriores siguen correspondiendo a la ejecución en tiempo real anterior.

05 Manejo de fallos

El bucle de consulta utiliza tiempos de espera HTTP explícitos, desactiva las reintentos automáticos y verifica el presupuesto de intentos restante entre solicitudes. Ese presupuesto no es un temporizador estricto para detener el proceso. Una prueba registra su resultado antes de intentar la limpieza, y una respuesta correcta junto con una limpieza fallida sigue generando un código de salida distinto de cero.

Una sesión puede tener cuatro estados: idle, in_progress, requires_action y failed. La tarea CSV no configura herramientas de función de aplicación, por lo que si alguna vez se requiere una acción, el ejecutor guarda ese estado y lo reporta para su inspección en lugar de esperar eternamente.

Las transmisiones en vivo no reproducen los eventos que se perdieron. Para reconstruir la vista de la aplicación, se debe reconectar y almacenar en búfer los eventos entrantes mientras se recuperan los elementos de la sesión guardados, y luego sincronizarlos por ID de elemento. Esto restaura la visualización del trabajo guardado, aunque no garantiza que una orden interrumpida se haya ejecutado con éxito.

Un incidente relevante merece ser mencionado. Las notas de investigación anteriores describían sesiones inactivas sin turnos visibles, y el informe de incidentes de OpenAI del 14 de septiembre de 2026 indica retrasos o bloqueos en el inicio de los turnos a partir de las 13:30 hora del Pacífico ese día, siendo posteriormente marcados como resueltos. Los síntomas coinciden, pero sin pruebas a nivel de solicitud no se puede demostrar la causa de cada fallo local. Compare el estado del servicio con las sesiones guardadas y los errores de turnos. El programa registra las sesiones fallidas, los turnos fallidos, los artefactos faltantes, los resúmenes inválidos y los resultados incorrectos como resultados separados, y ya no considera un turno no observado como prueba de que haya reaparecido el incidente anterior.

Una vez guardados los resultados disponibles, si el ejecutor tiene trabajo pendiente solicita la cancelación e intenta eliminar la sesión, con un máximo de tres intentos cuando hay conflictos en la eliminación. Cualquier error de limpieza queda registrado en result.json. Si la creación de la sesión falla antes de que se devuelva un ID, no es posible realizar la limpieza por ID y el ejecutor registra esa incertidumbre.

Un espacio de trabajo alojado puede expirar después de una hora sin actividad ni mensajes de mantenimiento, mientras que los entornos conectados reciben mensajes de mantenimiento entre turnos. Los artefactos publicados sobreviven a la expiración del entorno, pero los resultados requeridos deben guardarse antes de eliminar la sesión.

06 Cuándo utilizar su propio recurso de cómputo

Una línea discontinua en el diagrama de arquitectura más amplio se aplica únicamente a los servidores autohospedados, mientras que el experimento en formato CSV permanece en servidores alojados por OpenAI. La opción de autohospedaje resulta ventajosa cuando la tarea requiere una imagen específica, acceso a una red privada o máquinas ya incluidas en su flota. Dentro de ese entorno se ejecuta codex exec-server, al cual se le proporciona la URL remota y el ID del entorno, junto con una clave restringida específica para ese entorno; la clave de aplicación general debe permanecer fuera de él.

A partir de ahí, la aplicación es responsable de gestionar el aprovisionamiento, el almacenamiento, la reconexión y el desmantelamiento de los recursos. Eliminar una sesión de OpenAI no detiene el funcionamiento de los servidores del proveedor, y reutilizar un ID de entorno no vuelve a cargar los archivos en una máquina de reemplazo.

El autoalojamiento tampoco hace que todo el servicio sea local. La API de Agents actual mantiene el estado de la sesión, admite la residencia de datos en EE. UU. y no soporta la política de cero retención de datos.

Los costos deben considerarse en la toma de decisiones. Los tokens del modelo y la computación alojada se facturan por separado; los precios de los contenedores dependen de la memoria y de los intervalos de facturación, por lo que es necesario registrar el uso real y no estimar la factura de una prueba basándose únicamente en los segundos transcurridos.

07 Ejecutar el experimento

Ejecutarlo cuesta dinero real, ya que requiere un uso de API con facturación separada en forma de créditos o un acuerdo de facturación de API activo, y la suscripción Pro no cubre esas llamadas. El ejecutor utiliza GPT-6 Astra (gpt-6-astra), por lo que muchas pruebas o ejecuciones prolongadas pueden agotar rápidamente los créditos, y el tiempo en el entorno sandbox alojado genera costos adicionales de procesamiento. Realice primero una prueba, consulte el panel de control de uso y lea la página de precios de Astra antes de ejecutar más operaciones.

Dentro del repositorio, cree un entorno virtual e instale el SDK correspondiente. Se necesita una clave API de la aplicación, con permisos para leer y escribir sesiones así como para ejecutar inferencias de modelos. Cada prueba consume tokens de API en tiempo real y recursos de procesamiento alojados.

cd openai-agents-api
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export OPENAI_API_KEY="your-key"
python sandbox_check.py --seed 42       # Start with one trial
# python sandbox_check.py 5 --seed 42   # Optional: five trials

La primera orden ejecuta un único ensayo con semilla 42, mientras que la orden opcional de cinco ensayos ejecuta las semillas del 42 al 46. Los resultados se guardan en un nuevo directorio runs/, con una carpeta por ensayo. El valor fijo del SDK es openai==3.13.0, y el archivo README describe los archivos de salida y las opciones de la orden.

trial-001/
  data.csv           # Exact input
  expected.json      # Local reference
  request.json       # Submitted configuration
  session.json       # Latest retrieved session
  turns.json         # Turn status, timestamps, usage
  items.json         # Saved messages and tool calls
  artifacts.json     # Published file metadata
  summary.json       # Downloaded result
  calculate.py       # Downloaded agent script
  result.json        # Checks, timing, errors, cleanup

Las ejecuciones fallidas conservan los archivos que se obtuvieron antes del fallo. Un código de salida cero requiere verificaciones precisas de la salida y la eliminación confirmada de la sesión en cada intento. Para probar el ejecutor localmente sin realizar llamadas a la API:

python -m unittest discover -s . -p test_sandbox_check.py -v

Sin necesidad de conectarse a la red, el conjunto de pruebas verifica los cálculos de referencia, las salidas de modelos mal formados, los artefactos obsoletos o ausentes, las sesiones y turnos que fallan, las acciones requeridas, los errores en las solicitudes, el manejo de plazos y la limpieza defectuosa. El ejecutor revisado aún no ha sido validado contra el servicio en producción.

El valor duradero del proyecto es una forma reproducible de analizar cómo la API de Agents pasa de un archivo a un artefacto. Un turno completado es una señal, mientras que una salida descargada y verificada de forma independiente constituye la verdadera prueba de aceptación. La documentación fue revisada el 15 de septiembre de 2026; los valores de prueba provienen del experimento original sin nuevas mediciones en tiempo real, y las guías enlazadas describen la versión beta actual, la cual puede cambiar.

Leer más

• Construyendo tu primer agente LangChain con LangGraph en 2026 — Crea un agente LangChain paso a paso con LangGraph, herramientas, memoria y seguimiento, evita cuatro errores comunes y descubre cómo lo utilizó un servicio de soporte de un bootcamp.
• Notas prácticas: Qwen 3.8 finalmente está disponible, codificación agenaria de nivel Opus con local — Guía detallada de las Notas prácticas: Qwen 3.8 finalmente está disponible, codificación agenaria de nivel Opus con local: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.