DigitalOcean

OpenAI Cookbook에서 애플리케이션 관리 방식과 웹훅 관리 방식의 예제를 확인하세요.

작동 방식

DigitalOcean의 Managed Agents Runtime Services(M.A.R.S.)는 codex-agentapi 이미지로 Firecracker microVM을 시작합니다. 이 이미지에는 Codex가 포함되어 있습니다. 이미지가 실행기를 시작하면 실행기는 Agents API로 아웃바운드 연결을 설정합니다.

OpenAI 이벤트에 따라 샌드박스를 시작하거나 재개하려면 웹훅 관리 방식 프로비저닝을 선택하세요. 애플리케이션에서 샌드박스를 직접 제어하려면 애플리케이션 관리 방식 프로비저닝을 선택하세요. 대화형으로 빠르게 시작하려면 DigitalOcean CLI 플로우를 이용할 수도 있습니다. 연결 및 복구 방식은 샌드박스 수명 주기를 참고하세요.

시작하기 전에

샌드박스 기능이 활성화되어 있고 codex-agentapi에 액세스할 수 있는 DigitalOcean 계정과 Agents API에 액세스할 수 있는 OpenAI 프로젝트가 필요합니다.

웹훅 컨트롤러나 Python 애플리케이션을 사용하려면 DIGITALOCEAN_TOKEN을 설정하고 PyDo SDK 0.41.0 이상을 비동기 지원 옵션(pydo[aio])으로 설치하세요. Agents API 요청에는 OpenAI SDK를 사용하세요. CLI는 CLI 플로우를 사용할 때만 설치하면 됩니다.

웹훅 관리 방식

1. 여러 세션에서 재사용할 수 있도록 에이전트를 생성해 저장하고 해당 ID를 OPENAI_AGENT_ID로 저장하세요. 이 ID와 세션 조회용 OPENAI_API_KEY, DIGITALOCEAN_TOKEN, OPENAI_EXECUTOR_API_KEY를 설정해 DigitalOcean App Platform에 HTTPS 웹훅 컨트롤러를 배포하세요.
2. 컨트롤러의 /webhook 엔드포인트를 OpenAI 프로젝트에 등록하세요. agent.session.action_required와 agent.session.failed 이벤트를 활성화한 다음, 서명용 비밀 키를 OPENAI_WEBHOOK_SECRET으로 저장하고 컨트롤러를 다시 배포하세요.
3. 세션 실행 절차를 따르세요. 이때 동일한 OPENAI_AGENT_ID를 사용하고 작업 디렉터리는 /workspace로 설정하세요. 이벤트 스트림을 열고 입력을 전송하세요. OpenAI가 environment_connection을 요청하면 컨트롤러는 서명을 검증하고 현재 세션을 조회해 해당 세션의 에이전트 ID와 필요한 작업을 확인합니다. 그런 다음 DigitalOcean에서 mars-{session_id}를 조회합니다. 일시 중지된 샌드박스가 있으면 재개하고, 재개할 샌드박스도 활성 샌드박스도 없으면 새로 생성합니다.
4. agent.session.failed 이벤트를 받으면 세션을 다시 조회하고, 현재 세션 상태가 여전히 failed인 경우에만 해당 샌드박스를 삭제하세요.

이미지는 실행기를 세션 환경에 연결합니다. 애플리케이션은 Agents API를 통해 입력을 전송하고 결과를 스트리밍하며, 컨트롤러는 프로비저닝과 재연결을 담당합니다. 이벤트가 중복으로 또는 동시에 전달될 수 있으므로 같은 세션의 프로비저닝 작업은 순차적으로 처리하세요. 컨트롤러 요구 사항은 웹훅 관리 방식의 수명 주기 가이드를 참고하세요.

DigitalOcean CLI로 사용해 보기

CLI는 세션과 샌드박스를 모두 생성하며, 터미널에서 에이전트와 상호 작용할 수 있게 해 줍니다. CLI가 웹훅 컨트롤러 없이 샌드박스를 직접 프로비저닝합니다.

먼저 doctl 1.170.0 이상을 설치하세요. 이 버전에는 harness-runtime이 포함되어 있습니다. 설치 후 다음 명령어로 인증하세요.

doctl auth init

다음 매니페스트를 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}

매니페스트의 config 블록은 OpenAI에 보낼 세션 생성 요청입니다. CLI는 OPENAI_API_KEY로 요청을 인증하고 응답에서 받은 값으로 ${ENV_ID}를 채운 다음, 샌드박스에는 환경 키만 전달합니다. 실제 값이 채워진 매니페스트는 로그에 남기거나 버전 관리에 포함하지 마세요. 도구가 접속해야 하는 대상은 egress에 추가하세요.

세션과 샌드박스를 생성하세요.

doctl harness-runtime create --spec environment.yaml

이 명령어는 기본적으로 준비가 완료될 때까지 최대 300초 동안 기다립니다. 세션 상세 정보에 표시된 OpenAI 세션 ID와 DigitalOcean 세션 ID를 저장한 다음, 아래 명령어로 세션에 접속하세요.

doctl harness-runtime launch openai-codex-session

에이전트에게 hello를 /workspace/hello.txt에 쓴 다음 파일 내용을 다시 읽어 달라고 요청하세요. Ctrl+D 키를 누르면 세션을 삭제하지 않고 연결을 종료할 수 있습니다. 다시 접속하려면 같은 launch 명령어를 실행하세요. 작업을 마치면 리소스 정리 절차를 따르세요.

애플리케이션 관리 방식

애플리케이션에서 세션 생성과 샌드박스 프로비저닝을 직접 관리할 때는 이 방식을 사용하세요. 먼저 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

세션을 생성한 후 session.id와 환경 ID를 샌드박스 연결에 설명된 대로 저장하세요. 에이전트 설정은 이미 OpenAI에 전송했으므로 다음 샌드박스 전용 매니페스트를 sandbox.yaml로 저장하세요.

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. pydo.aio.Client 인스턴스를 DIGITALOCEAN_TOKEN으로 생성하고 client.agents.create_session을 호출하세요. params.openai_session_id에는 OpenAI 세션 ID를, body.manifest에는 sandbox.yaml의 내용을 설정하세요. body.variables에는 ENV_ID와 OPENAI_EXECUTOR_API_KEY를 각각의 값에 매핑한 객체를 지정하세요. 반환된 DigitalOcean session_id를 저장하세요.
2. 이벤트 스트림을 열고 입력을 전송해 에이전트에게 /workspace/hello.txt에 내용을 쓴 다음 다시 읽어 달라고 요청하세요. 실행기가 연결될 때까지 입력은 대기 상태로 유지됩니다. 연결 이벤트가 발생하고 턴이 완료되었는지 확인한 다음, 에이전트 출력에서 도구 실행 실패가 있는지 확인하세요.
3. 파일을 다운로드하려면 workspace_download에 상대 경로 hello.txt를 지정하세요. 이후 턴에서도 사용할 수 있도록 두 리소스를 유지하거나 리소스를 정리하세요.

애플리케이션에서 설정 및 실행에 각각 제한 시간을 지정하고 연결 실패를 처리하세요. 애플리케이션이나 CLI가 직접 관리하는 세션에는 프로비저닝용 웹훅 핸들러를 연결하지 마세요.

리소스 정리

필요한 파일을 저장한 다음 OpenAI 세션을 삭제하고 DigitalOcean 샌드박스를 삭제하세요. 세션을 삭제해도 웹훅 이벤트가 발생하지 않으므로 두 작업을 모두 수행하고 정리에 실패하면 이를 보고하세요.

PyDo를 사용하는 경우 client.agents.destroy_session에 DigitalOcean 세션 ID를 전달해 호출하세요. CLI에서는 해당 ID 또는 샌드박스 이름을 전달하세요.

doctl harness-runtime remove openai-codex-session

웹훅 컨트롤러를 삭제하기 전에 OpenAI에서 웹훅 등록을 해제하세요.

참고 자료

• DigitalOcean 샌드박스 설정 문서 보기
• DigitalOcean Python SDK 문서 보기
• DigitalOcean CLI 릴리스 정보 보기