DigitalOcean

Consulta los ejemplos de aprovisionamiento gestionado por la aplicación y gestionado mediante webhooks en el OpenAI Cookbook.

Cómo funciona

Managed Agents Runtime Services (M.A.R.S.) de DigitalOcean inicia una microVM de Firecracker con la imagen codex-agentapi. La imagen incluye Codex e inicia el ejecutor, que establece una conexión saliente con la API de agentes.

Elige el aprovisionamiento gestionado mediante webhooks para iniciar o reanudar sandboxes en respuesta a eventos de OpenAI, o el aprovisionamiento gestionado por la aplicación para controlarlos desde tu aplicación. Para empezar con una prueba interactiva, puedes seguir los pasos para usar la CLI de DigitalOcean. Consulta el ciclo de vida del sandbox para saber cómo funcionan la conexión y la recuperación.

Antes de comenzar

Necesitas una cuenta de DigitalOcean con los sandboxes habilitados y acceso a codex-agentapi, además de un proyecto de OpenAI con acceso a la API de agentes.

Para los controladores de webhooks o las aplicaciones en Python, configura DIGITALOCEAN_TOKEN e instala la versión 0.41.0 o posterior del SDK de PyDo con soporte para operaciones asíncronas (pydo[aio]). Usa el SDK de OpenAI para enviar solicitudes a la API de agentes. Solo necesitas instalar la CLI si vas a seguir los pasos que la utilizan.

Aprovisionamiento gestionado mediante webhooks

1. Crea un agente almacenado y guarda su ID como OPENAI_AGENT_ID. Despliega un controlador de webhooks HTTPS en DigitalOcean App Platform con ese ID, OPENAI_API_KEY para consultar las sesiones, DIGITALOCEAN_TOKEN y OPENAI_EXECUTOR_API_KEY.
2. Registra su punto de acceso /webhook en tu proyecto de OpenAI. Habilita agent.session.action_required y agent.session.failed, guarda el secreto de firma como OPENAI_WEBHOOK_SECRET y vuelve a desplegar el controlador.
3. Sigue los pasos para ejecutar una sesión con el mismo OPENAI_AGENT_ID y con /workspace como directorio de trabajo. Abre el flujo de eventos y envía los datos de entrada. Cuando OpenAI solicita una environment_connection, el controlador verifica la firma, obtiene la sesión actual y comprueba el ID del agente y las acciones requeridas. Busca mars-{session_id} en DigitalOcean y reanuda un sandbox en pausa o crea uno si no hay ninguno activo.
4. Al recibir agent.session.failed, vuelve a consultar la sesión y elimina su sandbox solo si el estado de la sesión sigue siendo failed.

La imagen conecta el ejecutor al entorno de la sesión. Tu aplicación envía los datos de entrada y recibe los resultados en tiempo real a través de la API de agentes. El controlador se encarga del aprovisionamiento y la reconexión. Ejecuta en serie las operaciones de aprovisionamiento de cada sesión para gestionar las entregas de eventos duplicadas o simultáneas. Consulta los requisitos del controlador en la guía del ciclo de vida de los sandboxes gestionados mediante webhooks.

Pruébalo con la CLI de DigitalOcean

La CLI crea ambos recursos y te permite interactuar con el agente desde tu terminal. Aprovisiona el sandbox directamente, sin un controlador de webhooks.

Instala doctl en su versión 1.170.0 o posterior, que incluye harness-runtime. Luego autentícate:

doctl auth init

Guarda este archivo de manifiesto como environment.yaml:

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-6.1-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

El bloque config contiene la solicitud de creación de sesión que se envía a OpenAI. La CLI autentica esa solicitud con OPENAI_API_KEY, sustituye ${ENV_ID} por el valor que recibe en la respuesta y pasa al sandbox únicamente la clave de entorno. Evita incluir los archivos de manifiesto con los valores ya sustituidos en los registros o en el control de versiones. Agrega a egress los destinos que necesiten tus herramientas.

Crea la sesión y el sandbox:

doctl harness-runtime create --spec environment.yaml

De forma predeterminada, el comando espera hasta 300 segundos a que los recursos estén listos. Guarda el ID de sesión de OpenAI y el ID de sesión de DigitalOcean que aparecen en los detalles de la sesión. Luego conéctate:

doctl harness-runtime launch openai-codex-session

Pídele al agente que escriba hello en /workspace/hello.txt y luego lea el contenido del archivo. Presiona Ctrl+D para desconectarte sin eliminar la sesión y ejecuta el mismo comando launch para volver a conectarte. Cuando termines, sigue los pasos para eliminar los recursos.

Aprovisionamiento gestionado por la aplicación

Usa esta opción cuando tu aplicación se encargue de crear las sesiones y aprovisionar los sandboxes. Primero, crea la sesión de OpenAI:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

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

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

Guarda session.id y el ID del entorno como se indica en Conectar un sandbox. Guarda este archivo de manifiesto, que solo contiene la configuración del sandbox, como sandbox.yaml. La configuración del agente ya se envió a OpenAI.

12345678agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

1. Crea una instancia de pydo.aio.Client con DIGITALOCEAN_TOKEN y llama a client.agents.create_session. Asigna el ID de sesión de OpenAI a params.openai_session_id. En body.manifest, incluye el contenido de sandbox.yaml y, en body.variables, un diccionario que asocie ENV_ID y OPENAI_EXECUTOR_API_KEY con sus respectivos valores. Guarda el session_id que devuelve DigitalOcean.
2. Abre el flujo de eventos y envía los datos de entrada para pedirle al agente que escriba en /workspace/hello.txt y lea el archivo. La entrada queda en espera hasta que se conecta el ejecutor. Confirma que se haya recibido el evento de conexión y que se haya completado un turno. Revisa la salida del agente para detectar fallas de las herramientas.
3. Recupera el archivo con workspace_download usando la ruta relativa hello.txt. Conserva ambos recursos para los turnos posteriores o elimínalos.

Define tiempos máximos de espera para la configuración y la ejecución, y gestiona las fallas de conexión en tu aplicación. No asocies un controlador de webhooks de aprovisionamiento a las sesiones que tu aplicación o la CLI gestionen directamente.

Eliminación de recursos

Guarda los archivos que necesites. Luego elimina la sesión de OpenAI y destruye el sandbox de DigitalOcean. Al eliminar una sesión no se envía ningún webhook, así que realiza ambas operaciones e informa de cualquier falla durante la eliminación.

Si usas PyDo, llama a client.agents.destroy_session con el ID de sesión de DigitalOcean. Si usas la CLI, pasa ese ID o el nombre del sandbox:

doctl harness-runtime remove openai-codex-session

Antes de eliminar un controlador de webhooks, elimina el registro del webhook en OpenAI.

Referencias

• Consulta la configuración de sandboxes de DigitalOcean
• Consulta el SDK de Python de DigitalOcean
• Consulta las versiones de la CLI de DigitalOcean