Tutorial de la API de Agents de OpenAI: crea un agente que escribe y ejecuta código en la nube

La mayoría de apps basadas en LLM siguen un patrón sencillo: envías un prompt, recibes una respuesta y usas esa respuesta en tu aplicación.

Eso funciona bien para tareas simples, pero se complica cuando el modelo necesita escribir código, ejecutarlo, comprobar el resultado, trabajar con archivos, corregir errores y seguir iterando hasta completar la tarea.

Aquí es donde la API de Agents de OpenAI resulta realmente útil.

En lugar de construir cada paso tú mismo, puedes darle al agente la tarea, los archivos que necesita y un entorno de trabajo, y dejar que se encargue del resto.

En este tutorial, mantendré el ejemplo simple. Crearemos un pequeño dataset ficticio de ventas de una cafetería y se lo daremos al agente. El agente escribirá y ejecutará el análisis, verificará los resultados y creará tres archivos de salida por nosotros.

Cuando veas todo funcionando entre bambalinas, empezarás a darte cuenta de cuánto del flujo de trabajo de código habitual se está automatizando por ti. 

Si eres nuevo en agentes de IA, te recomiendo echar un vistazo a nuestro itinerario de aprendizaje AI Agents Fundamentals. 

¿Qué es la API de Agents de OpenAI?

La API de Agents de OpenAI te permite darle a un agente una tarea, los archivos que necesita y el entorno en el que debe trabajar, y dejar que se encargue del resto.

En lugar de crear manualmente un sandbox, iniciar una sesión, subir archivos, ejecutar código, comprobar errores y gestionar cada paso tú mismo, puedes enviar una única solicitud a la API con la tarea, la configuración, el entorno y los archivos de entrada.

A partir de ahí, la API de Agents asume gran parte del trabajo.

Por debajo, OpenAI gestiona el sistema de Codex, incluida la orquestación, el contexto, el uso de herramientas, la ejecución y las sesiones de larga duración. Puedes imaginarlo casi como si tuvieras OpenAI Codex ejecutándose en la nube para tu aplicación. 

No necesitas preocuparte tanto por preparar el cómputo, gestionar el entorno de trabajo, llevar el control de la sesión o construir tú mismo todo el bucle del agente.

Esto es especialmente útil para tareas más complejas y de larga duración en las que el agente debe hacer realmente el trabajo, no solo devolver una respuesta.

Para este tutorial, usaremos un sandbox alojado por OpenAI:

Enviamos una única solicitud con el archivo CSV, la tarea y la configuración del agente. 

La API de Agents crea y gestiona por nosotros la sesión y el sandbox.

Dentro del sandbox, el agente puede revisar el archivo, decidir cómo enfocar el análisis, generar código en Python, ejecutarlo, comprobar los resultados y corregir cosas si algo falla.

Cuando todo termina, las salidas se guardan como artefactos de sesión. 

Pueden ser gráficos, datasets depurados, informes u otros archivos que cree el agente. Luego podemos recuperarlos y permitir que el usuario los descargue y los revise.

La idea principal es sencilla: enviamos la tarea una vez y el agente se encarga del trabajo real a partir de ahí.

OpenAI Responses API vs Agents SDK vs Agents API: ¿cuál deberías usar?

La principal diferencia entre estas tres opciones es cuánto del flujo de trabajo quieres gestionar tú.

Usa la Responses API cuando necesites que el modelo complete una tarea concreta, como resumir, extraer, clasificar, responder preguntas, producir salidas estructuradas o hacer unas pocas llamadas a herramientas.

Usa el Agents SDK cuando estés construyendo tú mismo una aplicación con agentes y quieras más control sobre agentes, herramientas, handoffs, guardrails y flujos multiagente.

Usa la Agents API cuando la tarea sea más compleja y necesite su propio entorno de trabajo. Es útil cuando el agente debe manejar archivos, ejecutar código, inspeccionar resultados, corregir errores y avanzar a lo largo de varios pasos.

Guía paso a paso: construye un agente de análisis de datos con OpenAI

Para este tutorial, usamos la Agents API porque el agente necesita trabajar con un archivo, razonar sobre el análisis, ejecutar código, inspeccionar los resultados y guardar los artefactos finales para el usuario.

Vamos allá

1. Configura tu entorno de Python para la Agents API

Para este tutorial usaremos un Jupyter Notebook para probar la Agents API paso a paso y entender cómo funciona cada parte. 

Empezaremos instalando el paquete de OpenAI e importando las librerías que necesitaremos para el resto del tutorial.

Primero, instala o actualiza el paquete de OpenAI para Python:

%pip install -q --upgrade openai

Luego importa las librerías que usaremos:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Ahora crea el cliente de OpenAI:

client = OpenAI()

Asegúrate de que tu OPENAI_API_KEY ya esté configurada en tu entorno. El cliente de OpenAI la detectará automáticamente.

2. Genera datos de ejemplo para el agente de IA

Crearemos un pequeño dataset ficticio de ventas para tener algo sencillo que darle al agente.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Esto crea 50 pedidos ficticios de cafetería con distintos productos, ubicaciones, fechas y descuentos. Usamos una semilla aleatoria fija para que se genere el mismo dataset cada vez que ejecutamos el notebook.

3. Crea y codifica el archivo CSV para el sandbox del agente

A continuación, convertiremos los datos generados en un archivo CSV que podamos pasarle al agente.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Salida:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

También codificamos el CSV en Base64 porque enviaremos el archivo directamente con la solicitud del agente.

4. Define la tarea del agente y las salidas esperadas

Ahora describiremos qué queremos que el agente haga con el archivo CSV.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

Lo importante es que describimos el objetivo y las salidas esperadas, en lugar de escribir nosotros el código de análisis.

El agente puede decidir cómo hacer el trabajo, ejecutar el código y verificar los resultados antes de terminar.

5. Ejecuta el agente en el sandbox alojado por OpenAI

Ahora enviaremos todo a la API de Agents en una sola solicitud y dejaremos que el agente haga el trabajo real en la nube.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

Aquí es donde ocurre la mayor parte del trabajo.

Hacemos una solicitud que contiene la configuración del agente, el entorno alojado, el archivo CSV y la tarea. 

OpenAI crea la sesión gestionada y ejecuta el agente dentro del sandbox alojado. El agente puede inspeccionar el archivo, escribir analyze_sales.py, ejecutarlo, comprobar los resultados, corregir cualquier problema y crear los archivos finales de salida. 

El endpoint de creación de sesión admite tanto el entorno como la entrada inicial en la misma solicitud.

Hay tres partes principales en la solicitud:

• agent indica a OpenAI qué modelo usar y cómo debe comportarse el agente.
• environment proporciona al agente su espacio de trabajo alojado y coloca nuestro archivo CSV dentro.
• input le da al agente la tarea que definimos en la sección anterior.

También establecemos stream=True. 

Esto no cambia cómo se completa la tarea. Simplemente nos permite recibir eventos mientras el agente trabaja, en lugar de esperar a que termine todo el turno para ver algo.

En este ejemplo, escuchamos eventos agent.session.turn.output_text.delta y vamos actualizando el notebook con el texto más reciente.

El texto que vemos aparecer arriba es el agente informando de su progreso y de su respuesta final. 

La tarea real sigue ejecutándose en el entorno alojado hasta que recibimos el evento agent.session.turn.completed.

En mi ejecución, el agente creó y ejecutó analyze_sales.py, comprobó los archivos generados y verificó unas ventas netas totales de 600.55.

Lo importante es que el modelo no se limitó a decirnos qué código de Python ejecutar. El agente escribió el código, lo ejecutó, inspeccionó el resultado y verificó la salida por sí mismo.

6. Recupera y descarga los artefactos de archivos del agente

Ahora que el agente ha terminado, podemos descargar los archivos que creó durante ese turno.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Salida:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Aquí listamos los artefactos de la sesión, nos quedamos con los creados en el turno completado y los descargamos en nuestra carpeta local cloud_bean_results.

7. Elimina la sesión para ahorrar costes de cómputo del sandbox

Cuando hayamos terminado con los archivos, conviene eliminar la sesión para no mantener el entorno gestionado más tiempo del necesario.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Salida:

Session deleted: True

Esto elimina la sesión gestionada de la API. 

OpenAI indica que la limpieza física de los recursos subyacentes puede continuar de forma asíncrona después de que la petición de borrado devuelva respuesta.

Este paso es especialmente importante cuando usas un sandbox alojado por OpenAI. 

El sandbox es el entorno de cómputo donde el agente ejecuta código y trabaja con archivos, y los sandboxes alojados usan cómputo en contenedor que se factura por separado del uso del modelo. 

Así que, si mantienes sesiones y entornos activos más tiempo del necesario, puedes seguir acumulando costes de cómputo.

Reflexión final: ¿merece la pena el coste de la API de Agents de OpenAI?

Lo que más me llamó la atención de la API de Agents es todo lo que puede hacer con una simple llamada a la API.

Le dimos el archivo, la tarea, la configuración del modelo y el entorno alojado. 

A partir de ahí, se encargó del resto: creó el espacio de trabajo, inspeccionó los datos, escribió el código en Python, lo ejecutó, comprobó las salidas, corrigió lo necesario y produjo los artefactos finales.

Realmente se siente como tener Codex ejecutándose en la nube para tu aplicación. 

No tuve que preocuparme por configurar el cómputo, gestionar el bucle de ejecución, manejar archivos intermedios o seguir cada paso. Básicamente solo tuve que definir bien la tarea y revisar el resultado.

La ejecución tardó alrededor de dos minutos, pero durante ese tiempo el agente estuvo haciendo bastante trabajo entre bastidores.

Eso es lo que lo diferencia de una petición normal a una API. 

No estás esperando a que un modelo genere texto; estás esperando a que un agente complete realmente un trabajo.

En mis pruebas, tres ejecuciones de este ejemplo costaron en total unos 1,52 $, incluyendo el uso del modelo y del entorno alojado. 

Para una tarea tan pequeña, no es barato; en producción, sin duda probaría primero modelos más pequeños o económicos.

Pero para trabajos más complejos que implican programación, depuración, archivos, razonamiento y múltiples pasos dependientes, el coste adicional puede tener mucho más sentido.