For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Inicio rápido de la API de agentes

Crea un agente que escriba y ejecute un script en un sandbox alojado por OpenAI.

Crea un asistente de programación que escriba tree.py, lo ejecute y muestre un árbol de directorios. OpenAI administra el agente, su conversación y el sandbox donde trabaja.

Requisitos previos

Crea una clave de API de aplicación en tu proyecto de OpenAI Platform. Otorga los permisos api.agents.read y api.agents.write para las operaciones de sesión, además de api.responses.write para la inferencia del modelo, y luego exporta la clave:

export OPENAI_API_KEY="your-api-key"

Mantén esta clave fuera del sandbox del agente. Consulta Sandboxes alojados por OpenAI para conocer la configuración y los límites del sandbox.

Las solicitudes requieren el encabezado OpenAI-Beta: agents=v1. Los SDK de OpenAI lo agregan automáticamente; inclúyelo explícitamente cuando uses cURL.

1. Ejecuta una tarea

Elige un lenguaje, instala el SDK de OpenAI y ejecuta el ejemplo. Los ejemplos del SDK usan el espacio de nombres beta.agents. La solicitud crea una sesión, envía una tarea y transmite el progreso.

Instala o actualiza el SDK de Python:

pip install --upgrade openai

Guarda el ejemplo como quickstart.py:

Crea y ejecuta tree.py
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

Ejecútalo desde tu terminal:

python quickstart.py

¿No necesitas un sandbox? Establece environment.type en none para agentes que respondan preguntas o llamen a herramientas externas sin ejecutar comandos ni trabajar con archivos locales. Más información.

2. Sigue el progreso

La terminal muestra los eventos a medida que se transmiten. Los ejemplos del SDK imprimen JSON; cURL muestra el flujo de eventos sin procesar. Si la ejecución se completa correctamente, el agente crea tree.py, lo ejecuta y muestra un árbol de directorios que contiene ese archivo. Los demás archivos y la salida dependen del sandbox.

Busca agent.session.turn.completed y luego revisa el resultado de ejecución que informa el agente. Que un turno se complete no garantiza que todas las herramientas hayan funcionado correctamente. Los eventos que terminan en turn.failed, turn.cancelled o session.failed indican un error o una cancelación; agent.session.idle por sí solo no indica que la ejecución haya sido exitosa. Si la transmisión se desconecta antes de tiempo, recupera la sesión y sus elementos guardados antes de volver a intentarlo.

3. Continúa la sesión

Guarda el session_id de los eventos. Úsalo para enviar un mensaje de seguimiento como “Add a maximum-depth option to tree.py, run it, and show me the output.” Abre el flujo de eventos antes de enviar la entrada de seguimiento para no perderte los primeros eventos.

4. Limpieza

Conserva la sesión para más tareas o elimínala cuando termines. Primero, guarda los archivos que necesites.

En el ejemplo, reemplaza el valor de muestra sess_123 por el ID de sesión que guardaste.

Elimina la sesión
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

Próximos pasos