샌드박스 미리 준비하기

에이전트 세션을 만들기 전에 OpenAI가 호스팅하는 샌드박스를 만들고 패키지 설치, 파일 로드, 설정 명령어 실행을 미리 마칠 수 있습니다. 작업 요청이 들어오면 준비한 환경을 세션에 연결하고 에이전트를 시작하세요.

응답 지연을 줄이는 것이 핵심 요구 사항이라면 환경을 미리 준비하세요. 예를 들어 보고서 앱은 사용자가 데이터 세트를 선택하는 동안 Python 종속성을 준비할 수 있습니다. 코딩 워크플로우에서는 사용자가 요청을 작성하는 동안 워크스페이스를 준비할 수 있습니다. 설정을 일찍 시작하면 사용자가 기다리는 시간을 줄일 수 있습니다.

작동 방식

환경은 에이전트가 도구를 실행하는 워크스페이스입니다. 세션에는 에이전트 설정과 대화가 저장됩니다. 워크스페이스를 세션과 별도로 미리 준비해 두었다가 세션이 필요할 때 연결할 수 있습니다.

워크플로우는 세 단계로 진행됩니다.

환경을 만드세요. 작업에 필요한 패키지, 파일, 설정 명령어를 지정하세요.
환경이 준비될 때까지 기다리세요. 상태가 ready로 바뀔 때까지 환경을 조회하거나 웹훅을 사용하세요.
세션을 시작하세요. 세션을 만들 때 환경 ID를 전달하세요.

설정이 진행 중일 때도 환경을 연결할 수 있습니다. 에이전트는 설정이 끝난 뒤에 워크스페이스에 접근할 수 있습니다.

요금

샌드박스를 미리 준비하는 데는 요금이 부과되지 않습니다. 세션에 연결하기 전까지는 컨테이너 사용도 무료입니다. 미리 준비한 샌드박스를 세션에 연결하지 않으면 5분 후에 만료됩니다.

미리 준비한 샌드박스를 세션에 연결한 뒤에는 표준 컨테이너 요금이 적용됩니다.

보고서 작성용 워크스페이스 준비하기

이 예제에서는 에이전트를 시작하기 전에 pandas를 설치하고 작은 CSV 파일을 로드합니다. 에이전트는 준비된 워크스페이스에서 합계를 계산합니다.

이 가이드에 필요한 최소 SDK 버전은 Python SDK 3.28.0, Node.js SDK 7.32.0, Java SDK 4.80.0, Ruby SDK 0.103.0입니다.

1. 환경 만들기

워크스페이스 설정을 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"
        }
      ]
    }
  }'

SDK 예제에서는 다음 단계에서 사용할 수 있도록 응답으로 받은 id를 저장합니다. cURL을 사용한다면 셸 변수에 저장하세요.

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

독립형 환경을 만들 때는 environment.type을 openai_hosted로 설정하세요.

2. 준비 상태 확인하기

1단계에서 저장한 ID로 환경을 조회하세요.

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"

설정이 진행 중이면 상태는 pending입니다. 상태가 ready로 바뀌면 워크스페이스가 준비된 것이므로 세션에 연결할 수 있습니다.

환경이 준비되었다고 해서 에이전트가 연결된 것은 아닙니다. 세션을 만들기 전에도 환경은 ready 상태가 될 수 있습니다.

폴링을 피하려면 프로젝트의 웹훅 엔드포인트에서 다음 이벤트를 구독하세요.

agent.environment.ready
agent.environment.failed

설정이 끝나기 전에 환경을 연결했다면 세션의 agent.session.environment.ready 또는 agent.session.environment.failed 이벤트로 설정 상태를 확인하세요. "stream": true로 세션을 만들 때 반환되는 응답 스트림을 사용하거나 GET /v1/agents/sessions/{session_id}/events로 이벤트 스트림을 여세요. 스트리밍에 관한 자세한 내용은 세션 이벤트를 참고하세요.

3. 환경 연결 및 작업 실행하기

저장한 환경 ID, 에이전트, 에이전트에 전달할 첫 입력을 지정해 세션을 만드세요.

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

자주 발생하는 오류

오류 메시지와 환경의 현재 상태를 확인한 뒤 적절한 복구 방법을 선택하세요.

새로 만든 공유 환경에는 최대 128개의 세션을 연결할 수 있습니다. 여러 세션에서 같은 환경을 재사용할 수 있으며, 이 세션들은 워크스페이스를 공유합니다. 이전에 만든 환경에는 세션 하나만 연결할 수 있는 기존 수명 주기가 적용될 수 있습니다.

오류 또는 증상	해결 방법
만료된 환경을 연결하려고 합니다.	새 환경을 만들고 새 ID를 사용하세요. 사용하지 않은 환경은 5분 후에 만료됩니다. 만료된 ID로 다시 시도해도 워크스페이스는 복구되지 않습니다.
`404`: 환경을 찾을 수 없습니다.	환경 ID를 확인하고 환경 생성 요청에 사용한 조직, 프로젝트, 인증 주체를 그대로 사용하세요. 환경이 만료되었거나 더 이상 사용할 수 없다면 새 환경을 만드세요.
`409`: 공유 환경에 연결된 세션 수가 한도에 도달했습니다.	공유 환경에는 최대 128개의 세션을 연결할 수 있습니다. 기존 세션을 재사용하거나 추가 세션을 위한 환경을 새로 만드세요.

저장한 환경 템플릿 사용하기

여러 작업에 같은 패키지와 설정이 필요하다면 환경 설정을 템플릿으로 저장한 뒤, 환경을 미리 준비할 때마다 해당 템플릿 ID를 지정하세요.

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"
  }
}'

컴퓨터 사용을 위한 샌드박스 미리 준비하기

브라우저 작업을 수행하려면 세션이 시작되기 전에 관리형 브라우저와 가상 디스플레이를 준비하세요. 환경을 만들 때 desktop.enabled를 포함하세요.

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
    }
  }
}'

세션을 만들 때 저장한 환경 ID로 환경을 연결하고 에이전트에 computer_use 도구를 제공하세요. 세션은 환경에 저장된 데스크톱 설정을 사용합니다. 도구 설정과 브라우저 출처별 승인에 관한 내용은 컴퓨터 사용을 참고하세요.

환경 목록 조회하기

현재 조직과 프로젝트에서 자신의 인증 주체로 만든 활성 환경을 찾으려면 GET /v1/agents/environments를 호출하세요.

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"

목록에는 세션 연결 전후의 환경이 모두 포함됩니다. 표시되는 상태는 pending, ready, connected, disconnected, suspended입니다. 실패하거나 만료된 환경, 삭제되거나 종료된 환경은 제외됩니다. 목록에 있는 환경이 이미 하나 이상의 세션에 연결되어 있을 수 있습니다.

결과는 기본적으로 최신순으로 정렬됩니다. has_more가 true이면 after에 이전 응답의 last_id를 지정해 다음 페이지를 가져오세요. limit에는 1~100을 지정할 수 있으며 기본값은 20입니다. order에는 asc 또는 desc를 지정할 수 있습니다.

환경 수명과 재사용

여러 세션이 하나의 환경을 공유할 수 있습니다. 각 세션을 만들 때 동일한 environment_id를 전달하세요. 이 세션들은 실행 중인 워크스페이스를 공유하므로 파일, 프로세스, 설치된 패키지, 환경 설정도 공유합니다. 대화 기록은 세션별로 유지됩니다. 워크스페이스의 변경 사항은 연결된 다른 세션에서도 보이므로 작업마다 별도의 워크스페이스가 필요하다면 환경을 따로 만드세요. 공유 환경에는 최대 128개의 세션을 연결할 수 있습니다. 이 동작은 새로 만든 독립형 환경에 적용되며 이전에 만든 환경은 원래의 수명 주기를 유지합니다.
사용하지 않은 환경은 만료됩니다. 환경을 세션에 연결하지 않은 채로 두면 5분 후에 만료됩니다. 작업을 시작할 시간이 가까워지면 환경을 미리 준비하세요.
환경을 만들 때 사용한 인증 주체를 계속 사용하세요. 환경 조회, 목록 조회, 세션 연결에는 환경을 만들 때와 동일한 조직, 프로젝트, 인증 주체가 필요합니다. 같은 인증 주체의 API 키라면 서로 다른 키로도 같은 환경에 접근할 수 있습니다. 키를 교체한 뒤에도 마찬가지입니다.
공유 환경은 일정 시간 활동이 없으면 만료됩니다. 첫 번째 세션을 연결하면 20분의 유휴 시간 제한이 적용됩니다. 연결된 세션 중 하나에서 활동이 발생하거나 환경 파일 API를 사용하면 만료 시점이 연장됩니다. 대기 중인 작업이나 진행 중인 턴이 있으면 유휴 상태로 인한 만료는 발생하지 않습니다. 세션을 삭제하면 환경에서 해당 세션만 제거되고 공유 워크스페이스는 유지됩니다. 마지막 세션을 삭제한 뒤에도 유휴 시간 제한에 도달하기 전까지는 환경에 다시 세션을 연결할 수 있습니다. API에는 환경을 별도로 삭제하는 엔드포인트가 없습니다.

환경 생성 요청을 안전하게 재시도하기

환경을 만들 때 Idempotency-Key 헤더를 보낼 수 있습니다. 요청 시간이 초과되거나 응답을 받지 못했다면 환경이 추가로 생성되지 않도록 동일한 키와 동일한 요청 본문으로 재시도하세요.

원래 환경을 여전히 사용할 수 있고 재시도 요청이 정상적으로 완료되면 응답에는 해당 환경의 ID와 현재 상태가 포함됩니다. 보관된 키로 재시도할 때 환경 생성이 아직 진행 중이거나 생성 결과가 불확실하거나 환경을 더 이상 사용할 수 없거나 요청 매개변수가 다르면 409가 반환될 수 있습니다. 이런 충돌이 발생해도 대체 환경은 생성되지 않습니다. 키는 24시간 동안 보관됩니다. 그 이후에는 같은 키로 요청해도 새 환경이 생성될 수 있습니다. 새 환경을 만들려는 경우에는 새 키를 사용하세요.

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스