Sandboxes에서 OpenAI Agents API 실행하기

Use CoreWeave Sandboxes as the execution environment for an OpenAI-managed agent. Your application creates an Agents API session and a CoreWeave sandbox. A Codex executor inside that sandbox connects to OpenAI and runs the agent’s commands. This page explains the execution model, the credentials each component requires, and the resource lifetimes you manage. With that context, you can run the companion recipe and adapt the same pattern in your own application. The companion recipe investigates a synthetic inference-service incident. Three specialist subagents analyze latency, errors, and capacity. Their coordinator combines the results into an incident report and answers a follow-up. The application downloads the results, and a separate local verifier checks the calculations and recorded agent activity.

Execution model

OpenAI runs the agent loop, manages conversation context, and supplies delegation tools. CoreWeave runs the executor and the programs the agents write. Your application manages sandbox provisioning, file transfer, and cleanup. The coordinator and its subagents share one sandbox and one filesystem. Creating a subagent doesn’t create a separate CoreWeave sandbox. Give each specialist its own output files and let the coordinator own the final report. These file assignments are conventions for avoiding write conflicts, not access controls. See OpenAI’s multi-agent guide.

Requirements

Before you run the example, meet these requirements:

W&B API 키와 CPU 샌드박스 1개를 실행할 수 있는 용량이 필요합니다. 자격 증명 선택을 참고하세요.
Agents API 액세스 권한과 선택한 모델에 대한 액세스 권한이 있는 OpenAI 프로젝트가 필요합니다.
Python과 uv가 필요합니다. 버전과 lockfile은 함께 제공되는 레시피에 지정된 것을 사용하세요.
api.openai.com에 대한 아웃바운드 HTTPS 연결과 codex-cloud-environments.chatgpt.com에 대한 보안 WebSocket 액세스가 필요합니다. 이미지를 설정할 때는 executor와 런타임 의존성을 설치하는 데 사용하는 패키지 레지스트리에도 액세스할 수 있어야 합니다.

This example uses CPU compute to analyze supplied telemetry. It doesn’t launch an inference server or request a GPU. OpenAI model usage and CoreWeave sandbox compute have separate billing terms.

Keep application and executor credentials separate

This example uses three credentials: one sandbox credential and two OpenAI keys. Each credential belongs to a single component, which keeps application access out of the sandbox:

자격 증명	사용 주체	용도
`WANDB_API_KEY`	애플리케이션	W&B 인증으로 샌드박스 프로비저닝 및 운영
`OPENAI_API_KEY`	애플리케이션	세션 생성, 입력 제출, 결과 확인
`OPENAI_EXECUTOR_API_KEY`	샌드박스 executor(`CODEX_API_KEY`로 사용)	이 실행 환경을 OpenAI에 연결

레시피는 기본적으로 CoreWeave 인증을 사용합니다. W&B 키를 사용하려면 --sandbox-auth wandb를 전달하세요. 샌드박스 자격 증명은 선택한 것 하나만 있으면 되지만, 어느 모드를 사용하든 OpenAI 키는 두 개 모두 필요합니다. 애플리케이션이 선택한 모드를 기록해 두므로, 정리할 때도 동일한 공급자 자격 증명이 사용됩니다. The OpenAI application key requires api.agents.read, api.agents.write, and api.responses.write. Create the separate environment key in Agents > Environments > Keys. It must have the same organization, project, and user or service-account ownership as the session. Set unrelated permissions to None. The recipe passes the restricted executor key through the environment_variables argument in the SDK. It doesn’t configure a secret store. Upload only task inputs. Keep application credentials, local configuration, and the verifier outside the sandbox. Follow the OpenAI authentication instructions.

Agent-generated code can read the executor key. Restrict its permissions to limit what that code can access through OpenAI.

Connect an agent session

The runnable recipe implements these steps with the OpenAI and CoreWeave SDKs:

Create a self-hosted Agents API session and save its session ID and environment ID. Use the exact returned remote_url when starting the executor.
Create a CoreWeave sandbox with an explicit maximum lifetime and both Python and Node.
Start codex exec-server with the returned environment ID and unchanged remote URL. Inject only the restricted executor key as CODEX_API_KEY.
Upload the synthetic inputs and task instructions, then confirm the environment connection. Submit the task and observe its outcome.
Retrieve generated artifacts and API activity records before cleanup.

At the end of this sequence, the agent’s output files and the session’s activity records are available locally for inspection. The following configuration excerpt enables built-in delegation at session creation. The recipe passes these dictionaries to client.beta.agents.sessions.create():

agent = {
    "model": "gpt-6-astra",
    "instructions": "Follow TASK.md. Delegate the three independent analyses, then synthesize their findings.",
    "multi_agent": {"enabled": True, "max_concurrent_subagents": 3},
}
environment = {
    "type": "self_hosted",
    "workspace_directory": "/workspace/project",
}

This configuration permits up to three concurrent subagents, excluding the coordinator. The instructions request delegation. Configuration alone doesn’t prove the model used it. The recipe attributes API-completed script commands through turn and subagent IDs. Commands with explicit nonzero exit codes don’t count as successful execution evidence. The verifier reports omitted exit codes as unknown. The optional --require-exit-codes check requires numeric zero-exit evidence for every specialist. Overlapping started_at and completed_at intervals show concurrent subagent turns. These timestamps have whole-second precision, so they don’t prove simultaneous shell processes or a speedup over a sequential run.

Run the example

Follow the recipe setup and run steps. The recipe includes original synthetic data, a task specification, the application, and an independent verifier. Inspect the downloaded report alongside the verifier’s findings. You can also inspect session turns and tool calls in OpenAI Logs > Agents while the session exists. Select the matching organization and project. This example doesn’t provide a chat UI or establish ChatGPT or Codex app continuity. For an existing command-line interface (CLI) workflow, see OpenAI Agents API in cws-agent. The recipe uses the SDKs directly and doesn’t require that CLI.

Session, sandbox, and file lifetimes

Manage the conversation, compute, and workspace files separately when choosing what to preserve.

Resource	What preserves it	What ends it
API conversation	Reusing the same OpenAI session ID	Explicit API session deletion, subject to provider retention policies
Running sandbox	Keeping CoreWeave compute alive	Explicit stop, maximum lifetime, or infrastructure failure
Workspace files	Keeping the sandbox or saving files or snapshots	Losing compute without a preserved copy

Choose the compute lifetime explicitly. The recipe sets a 20-minute maximum lifetime. A maximum lifetime is a cap, not an inactivity timer that each prompt refreshes. Reconnecting an executor to the same running sandbox retains its workspace. Starting replacement compute with the same environment ID doesn’t restore its files. Download artifacts or use CoreWeave persistence features before stopping compute. The recipe downloads artifacts and deletes its resources. It doesn’t implement automatic recovery or snapshot and restore. Stopping a sandbox doesn’t delete its API conversation. Deleting the conversation doesn’t stop the sandbox. Attempt both cleanup operations and report each failure.

Handle failures

To investigate failures, use the following guidance:

The executor never connects: check environment-key ownership, outbound network access, executor compatibility, and the exact remote URL returned by OpenAI.
OpenAI reports a usage or billing limit: check the OpenAI organization and project billing limits before retrying. An executor connection alone doesn’t establish that a model turn can run.
The stream disconnects or the client times out: inspect session state and saved events before retrying input. A timeout doesn’t itself cancel cloud work.
Delegation or overlap isn’t observed: read the saved activity evidence. A correct report alone is insufficient evidence of a parallel multi-agent run.
The OpenAI environment expires: inspect its state before retrying. The recipe may wait until its work deadline rather than fail immediately.
The sandbox expires: recover saved artifacts if available. A replacement sandbox requires an explicit file-restoration policy.
The application is interrupted: use the recipe’s saved resource journal and cleanup command. The maximum sandbox lifetime is a fallback, not a substitute for deleting the API session.

For applications that retain sessions, coordinate shutdown with incoming work. An idle event alone isn’t a safe shutdown signal. Webhook-driven provisioning is a separate deployment pattern. See OpenAI’s sandbox lifecycle guide.

​Execution model

​Requirements

​Keep application and executor credentials separate

​Connect an agent session

​Run the example

​Session, sandbox, and file lifetimes

​Handle failures

Execution model

Requirements

Keep application and executor credentials separate

Connect an agent session

Run the example

Session, sandbox, and file lifetimes

Handle failures