DigitalOcean

Consulta los ejemplos de administración desde la aplicación y 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 administrado mediante webhooks para iniciar o reanudar sandboxes a partir de eventos de OpenAI, o el aprovisionamiento administrado desde la aplicación para controlarlos desde tu aplicación. Para un inicio rápido interactivo, usa el flujo opcional con la CLI de DigitalOcean. Consulta Ciclo de vida del sandbox para conocer el comportamiento de conexión y recuperación.

Antes de comenzar

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

Para controladores de webhooks o aplicaciones de Python, configura DIGITALOCEAN_TOKEN e instala el SDK beta de PyDo con soporte para operaciones asíncronas (pydo[aio]). Usa el SDK de OpenAI para las solicitudes a la API de agentes. Solo necesitas instalar la CLI para el flujo que la utiliza.

Administración 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 este ID, OPENAI_API_KEY para las lecturas de 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, luego almacena el secreto de firma como OPENAI_WEBHOOK_SECRET y vuelve a desplegar el controlador.
3. Sigue los pasos de la sesión con el mismo OPENAI_AGENT_ID y con /workspace como directorio de trabajo. Abre el flujo de eventos y envía la entrada. Cuando OpenAI solicita una environment_connection, el controlador verifica la firma, recupera la sesión actual y comprueba su ID de agente y las acciones requeridas. Busca mars-{session_id} en DigitalOcean y reanuda un sandbox pausado o crea uno si no hay ninguno activo.
4. Al recibir agent.session.failed, recupera la sesión de nuevo y elimina su sandbox solo si el estado actual de la sesión sigue siendo failed.

La imagen conecta el ejecutor al entorno de la sesión. Tu aplicación envía la entrada y transmite los resultados a través de la API de agentes; el controlador se encarga del aprovisionamiento y la reconexión. Ejecuta el aprovisionamiento de forma secuencial para cada sesión a fin de manejar las entregas duplicadas y concurrentes. Consulta la guía del ciclo de vida administrado mediante webhooks para conocer los requisitos del controlador.

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 la versión beta de doctl que incluye harness-runtime y luego autentícate:

doctl auth init

Guarda este archivo de manifiesto como agents.yaml:

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-5.6-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 es la solicitud de creación de sesión de OpenAI. La CLI autentica esa solicitud con OPENAI_API_KEY, completa ${ENV_ID} a partir de la respuesta y pasa únicamente la clave de entorno al sandbox. Mantén los archivos de manifiesto resueltos fuera de los registros y del control de versiones. Agrega a egress todos los destinos que necesiten tus herramientas.

Crea la sesión y el sandbox:

doctl harness-runtime create --spec agents.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 y luego conéctate:

doctl harness-runtime launch openai-codex-session

Pídele al agente que escriba hello en /workspace/hello.txt y que lea lo que escribió. Presiona Ctrl+D para desconectarte sin eliminar la sesión y ejecuta el mismo comando launch para volver a conectarte. Sigue los pasos de Limpieza cuando termines.

Administración desde la aplicación

Usa esta opción cuando tu aplicación se encargue de la creación de sesiones y del aprovisionamiento de 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 describe en Conectar un sandbox. Guarda este archivo de manifiesto exclusivo 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 un pydo.aio.Client con DIGITALOCEAN_TOKEN y llama a client.agents.create_session. Asigna a params.openai_session_id el ID de sesión de OpenAI, a body.manifest el contenido de sandbox.yaml y a body.variables un mapeo de ENV_ID y OPENAI_EXECUTOR_API_KEY a sus respectivos valores. Guarda el session_id de DigitalOcean que se devuelve.
2. Abre el flujo de eventos y envía la entrada, pidiéndole al agente que escriba y lea /workspace/hello.txt. La entrada espera a que se conecte el ejecutor. Confirma el evento de conexión y que se haya completado un turno, y 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 realiza la limpieza.

Establece tiempos de espera limitados para la configuración y la ejecución, y maneja las fallas de conexión en tu aplicación. No asocies un manejador de webhooks de aprovisionamiento a las sesiones que tu aplicación o CLI administra directamente.

Limpieza

Guarda los archivos que necesites, luego elimina la sesión de OpenAI y destruye el sandbox de DigitalOcean. La eliminación de la sesión no emite un webhook, así que realiza ambas operaciones e informa las fallas de limpieza.

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

doctl harness-runtime remove openai-codex-session

Elimina el registro del webhook de OpenAI antes de eliminar un controlador de webhooks.

Referencias

• Consulta la configuración del sandbox de DigitalOcean
• Consulta SDK de Python de DigitalOcean
• Consulta la versión beta de la CLI de DigitalOcean