Preparar sandboxes con anticipación

La preparación anticipada de entornos te permite crear un sandbox alojado por OpenAI, instalar paquetes, cargar archivos y ejecutar comandos de configuración antes de crear una sesión de agente. Cuando llegue una tarea, vincula el entorno preparado a una sesión e inicia el agente.

Prepara el entorno con anticipación cuando sea fundamental que la latencia sea baja. Por ejemplo, una aplicación de informes puede preparar sus dependencias de Python mientras el usuario elige un conjunto de datos, o un flujo de trabajo de programación puede preparar su espacio de trabajo mientras el usuario redacta una solicitud. Si la configuración empieza antes, el usuario puede pasar menos tiempo esperando a que termine.

Cómo funciona

Un entorno es el espacio de trabajo donde el agente ejecuta herramientas. Una sesión contiene la configuración del agente y la conversación. Puedes preparar el espacio de trabajo por separado y vincularlo cuando necesites una sesión.

El flujo de trabajo consta de tres pasos:

Crea un entorno. Proporciona los paquetes, los archivos y los comandos de configuración que requiere la tarea.
Espera a que el entorno esté listo. Consulta el entorno hasta que su estado sea ready o usa un webhook.
Inicia una sesión. Pasa el ID del entorno al crear la sesión.

También puedes vincular un entorno mientras se configura. El agente podrá acceder al espacio de trabajo una vez que termine la configuración.

Precios

Preparar un sandbox con anticipación es gratis, incluido el uso del contenedor antes de vincularlo a una sesión. Los sandboxes preparados con anticipación caducan después de 5 minutos si no los vinculas a una sesión.

Una vez que vinculas un sandbox preparado con anticipación a una sesión, se aplican las tarifas estándar de uso de contenedores.

Preparar un espacio de trabajo para generar informes

En este ejemplo se instala pandas y se carga un pequeño archivo CSV antes de iniciar un agente. Luego, el agente usa el espacio de trabajo preparado para calcular el total.

Para seguir esta guía, usa una de estas versiones del SDK o una posterior: 3.28.0 para Python, 7.32.0 para Node.js, 4.80.0 para Java o 0.103.0 para Ruby.

1. Crea el entorno

Envía la configuración del espacio de trabajo a POST /v1/agents/environments:

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: "inline",
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg==",
      },
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace",
      },
    ],
  },
});
const environmentId = environment.id;
console.log(environmentId);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "packages": {"python": ["pandas==2.2.3"]},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
        "setup_commands": [
            {
                "command": 'python -c "import pandas; print(pandas.__version__)"',
                "cwd": "/workspace",
            }
        ],
    }
)
environment_id = environment.id
print(environment_id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import com.openai.client.okhttp.OpenAIOkHttpClient;

import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.SetupCommandParam;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .packages(
                            EnvironmentCreateParams.Environment.Packages.builder()
                                .addPython("pandas==2.2.3")
                                .build())
                        .addFile(
                            HostedEnvironmentFileParam.Inline.builder()
                                .path("/workspace/amounts.csv")
                                .data("YW1vdW50CjEwCjIwCjMwCg==")
                                .build())
                        .addSetupCommand(
                            SetupCommandParam.builder()
                                .command(
                                    "python -c \"import pandas; print(pandas.__version__)\"")
                                .cwd("/workspace")
                                .build())
                        .build())
                .build());
String environmentId = environment.id();
System.out.println(environmentId);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: :inline,
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg=="
      }
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace"
      }
    ]
  }
)
environment_id = environment.id
puts environment_id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": {
      "type": "openai_hosted",
      "packages": {
        "python": ["pandas==2.2.3"]
      },
      "files": [
        {
          "type": "inline",
          "path": "/workspace/amounts.csv",
          "data": "YW1vdW50CjEwCjIwCjMwCg=="
        }
      ],
      "setup_commands": [
        {
          "command": "python -c \"import pandas; print(pandas.__version__)\"",
          "cwd": "/workspace"
        }
      ]
    }
  }'

Los ejemplos del SDK guardan el id de la respuesta para usarlo en los pasos siguientes. Si usas cURL, guárdalo en una variable de shell:

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

Asigna a environment.type el valor openai_hosted al crear un entorno independiente.

2. Comprueba si el entorno está listo

Consulta el entorno con el ID que guardaste en el paso 1:

Python

const current = await client.beta.agents.environments.retrieve(environmentId);
console.log(current.status);

current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

current, err := client.Beta.Agents.Environments.Get(context.Background(), environmentID)
if err != nil {
	panic(err)
}
fmt.Println(current.Status)

var current = client.beta().agents().environments().retrieve(environmentId);
System.out.println(current.status());

current = client.beta.agents.environments.retrieve(environment_id)
puts current.status

curl \
  "https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Mientras se configura el entorno, su estado es pending. Cuando cambia a ready, el espacio de trabajo está preparado y puedes vincularlo a una sesión.

Que el entorno esté listo no significa que haya un agente conectado. El entorno puede estar en estado ready incluso antes de que exista una sesión.

Para evitar las consultas periódicas, suscribe un punto de acceso de webhook del proyecto a estos eventos:

agent.environment.ready
agent.environment.failed

Si vinculas el entorno antes de que termine la configuración, monitorea los eventos agent.session.environment.ready o agent.session.environment.failed de la sesión para conocer el estado de la configuración. Usa el flujo de respuesta que recibes al crear la sesión con "stream": true o abre GET /v1/agents/sessions/{session_id}/events. Consulta Eventos de sesión para obtener más información sobre la transmisión de eventos.

3. Vincula el entorno y ejecuta una tarea

Crea una sesión con el ID del entorno que guardaste, un agente y su primera entrada:

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14const stream = await client.beta.agents.sessions.create({
  agent: { model: "gpt-6-astra" },
  environment: { type: "openai_hosted", environment_id: environmentId },
  input:
    "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  stream: true,
});
try {
  for await (const event of stream) {
    console.log(event);
  }
} finally {
  stream.controller.abort();
}

1
2
3
4
5
6
7
8
9stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "openai_hosted", "environment_id": environment_id},
    input="Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
    stream=True,
)
with stream:
    for event in stream:
        print(event.model_dump_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import com.openai.models.beta.agents.EnvironmentParam;

import com.openai.models.beta.agents.sessions.SessionCreateParams;

var params =
    SessionCreateParams.builder()
        .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
        .environment(
            EnvironmentParam.OpenAIHosted.builder().environmentId(environmentId).build())
        .input(
            "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.")
        .build();
try (var stream = client.beta().agents().sessions().createStreaming(params)) {
  stream.stream().forEach(System.out::println);
}

1
2
3
4
5
6
7
8
9
10
11
12
13stream = client.beta.agents.sessions.create_streaming(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: :openai_hosted,
    environment_id: environment_id
  },
  input: "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total."
)
begin
  stream.each { |event| puts event.to_json }
ensure
  stream.close
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "agent": {
    "model": "gpt-6-astra"
  },
  "environment": {
    "type": "openai_hosted",
    "environment_id": "$ENVIRONMENT_ID"
  },
  "input": "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  "stream": true
}
EOF

Errores comunes

Usa el mensaje de error y el estado actual del entorno para decidir cómo resolver el problema.

Un entorno compartido recién creado admite hasta 128 sesiones vinculadas. Puedes reutilizarlo en varias sesiones, que compartirán el espacio de trabajo. Es posible que los entornos más antiguos aún tengan un ciclo de vida limitado a una sola sesión.

Error o síntoma	Cómo resolverlo
Intento de vincular un entorno caducado.	Crea un entorno y usa su nuevo ID. Los entornos sin usar caducan después de 5 minutos. Volver a intentarlo con el ID de un entorno caducado no restaurará su espacio de trabajo.
`404`: no se encontró el entorno.	Verifica el ID del entorno y usa la misma organización, el mismo proyecto y la misma identidad que usaste en la solicitud de creación. Si el entorno caducó o ya no está disponible, crea uno nuevo.
`409`: el entorno compartido alcanzó su límite de sesiones.	Un entorno compartido admite hasta 128 sesiones vinculadas. Reutiliza una sesión existente o crea otro entorno si necesitas más sesiones.

Usar una plantilla de entorno guardada

Si varias tareas necesitan los mismos paquetes y la misma configuración, guarda la configuración del entorno como plantilla y proporciona el ID de la plantilla cada vez que crees un entorno con anticipación:

Python

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID",
  },
});
console.log(environment.id);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID",
    }
)
print(environment.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .environmentTemplateId("envtmpl_REPLACE_WITH_TEMPLATE_ID")
                        .build())
                .build());
System.out.println(environment.id());

1
2
3
4
5
6
7
8
9
10require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
)
puts environment.id

1
2
3
4
5
6
7
8
9
10curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
}'

Preparar un sandbox con anticipación para el uso de la computadora

Para las tareas que se realizan en el navegador, prepara el navegador administrado y la pantalla virtual antes de que comience la sesión. Incluye desktop.enabled al crear el entorno:

Python

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    desktop: { enabled: true },
  },
});
console.log(environment.id);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .desktop(
                            EnvironmentCreateParams.Environment.Desktop.builder()
                                .enabled(true)
                                .build())
                        .build())
                .build());
System.out.println(environment.id());

1
2
3
4
5
6
7
8
9
10require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    desktop: { enabled: true }
  }
)
puts environment.id

1
2
3
4
5
6
7
8
9
10
11
12curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "desktop": {
      "enabled": true
    }
  }
}'

Al crear una sesión, vincula el entorno con el ID que guardaste y proporciona al agente la herramienta computer_use. La sesión usa la configuración de escritorio guardada en el entorno. Consulta Uso de la computadora para obtener más información sobre la configuración de la herramienta y la aprobación de orígenes en el navegador.

Listar tus entornos

Usa GET /v1/agents/environments para encontrar los entornos activos que creaste con tu identidad en la organización y el proyecto actuales:

Python

1
2
3
4
5const environments = await client.beta.agents.environments.list({
  limit: 20,
  order: "desc",
});
console.log(environments.data);

1
2
3environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

1
2
3
4
5
6
7
8
9
10
11
12
13import com.openai.models.beta.agents.environments.EnvironmentListParams;

var environments =
    client
        .beta()
        .agents()
        .environments()
        .list(
            EnvironmentListParams.builder()
                .limit(20L)
                .order(EnvironmentListParams.Order.DESC)
                .build());
System.out.println(environments.items());

1
2
3
4
5environments = client.beta.agents.environments.list(
  limit: 20,
  order: :desc
)
(environments.data || []).each { |item| puts item.to_json }

1
2
3
4curl \
  "https://api.openai.com/v1/agents/environments?limit=20&order=desc" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

La lista incluye entornos tanto antes como después de vincularlos a una sesión, con los estados pending, ready, connected, disconnected o suspended. Excluye los entornos que fallaron, caducaron, se eliminaron o finalizaron. Es posible que un entorno de la lista ya esté vinculado a una o más sesiones.

De forma predeterminada, los resultados más recientes aparecen primero. Si has_more es verdadero, asigna a after el valor de last_id de la respuesta anterior para obtener la página siguiente. limit admite valores del 1 al 100 y su valor predeterminado es 20. order admite asc o desc.

Duración y reutilización

Varias sesiones pueden compartir un entorno. Pasa el mismo environment_id al crear cada sesión. Las sesiones comparten el espacio de trabajo en ejecución, incluidos los archivos, los procesos, los paquetes instalados y la configuración del entorno. Cada sesión conserva su propio historial de conversación. Los cambios en el espacio de trabajo son visibles para las demás sesiones vinculadas, así que crea entornos distintos cuando las tareas necesiten espacios de trabajo separados. Un entorno compartido admite hasta 128 sesiones vinculadas. Esto se aplica a los entornos independientes de nueva creación. Los entornos más antiguos conservan su ciclo de vida original.
Los entornos sin usar caducan. Si un entorno sigue sin vincularse a ninguna sesión, caduca después de 5 minutos. Prepáralo poco antes de la hora prevista para el inicio de la tarea.
Usa la misma identidad con la que creaste el entorno. Para consultar, listar o vincular el entorno, debes usar la misma organización, el mismo proyecto y la misma identidad autenticada que usaste para crearlo. Distintas claves de API de esa identidad pueden acceder a los mismos entornos, incluso después de rotar las claves.
Los entornos compartidos caducan por inactividad. Al vincular la primera sesión, comienza un plazo de inactividad de 20 minutos. La actividad en cualquier sesión vinculada o a través de la API de archivos del entorno extiende ese plazo. Mientras haya trabajo pendiente o turnos activos, el entorno no caduca por inactividad. Si eliminas una sesión, esta se desvincula del entorno y se conserva el espacio de trabajo compartido. Incluso después de eliminar la última sesión, puedes vincular el entorno a otra sesión hasta que venza el plazo de inactividad. La API no ofrece un punto de acceso para eliminar un entorno de forma independiente.

Reintentar la creación de forma segura

Al crear un entorno, puedes enviar un encabezado Idempotency-Key. Si se agota el tiempo de espera de la solicitud o se pierde la respuesta, vuelve a intentarlo con la misma clave y el mismo cuerpo de la solicitud para evitar crear otro entorno.

Mientras el entorno original siga disponible, un reintento que se complete devolverá su ID y su estado actual. Si la clave aún se conserva, el reintento puede devolver 409 si la creación sigue en curso, si se desconoce el resultado, si el entorno ya no está disponible o si los parámetros son distintos. Estos conflictos no crean un entorno de reemplazo. Las claves se conservan durante 24 horas. Una vez transcurrido ese plazo, es posible que se cree un entorno nuevo al usar la misma clave. Usa una clave nueva cuando quieras crear un entorno nuevo de manera intencional.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las funciones de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Ampliar funciones y automatizar

Entornos

Codex Cloud

Desarrollar con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Ciberseguridad

Primeros pasos

Configuración de funciones

Identidad y acceso