Skip to main content
Connect an OpenAI-hosted agent to a Blaxel Sandbox to run commands, read documents, and create files. Agent Drive keeps selected files available when you replace a Sandbox or hand work to another agent.
The cookbook currently uses OpenAI’s Agents API preview client. You need an OpenAI project with Agents API access and GitHub access to the client referenced in pyproject.toml.

​
Architecture

OpenAI manages the agent, model calls, and session state. Blaxel supplies the computer that runs its commands, plus storage and controls for that computer. Your application defines the task, agent instructions, and resource lifecycle. The cookbook connects codex exec-server in each worker Sandbox to the session’s self-hosted environment. That connection is outbound, so the worker does not need a public inbound port. The diagram shows webhook-managed execution. For an application-managed run, your application starts the Sandbox and executor directly through the Blaxel SDK.

​
Credentials and access

The cookbook requires Python 3.11 through 3.14, Git, OpenAI Agents API access, and a Blaxel workspace. Application-managed examples accept a bl login session or BL_WORKSPACE and BL_API_KEY. The deployed handler requires the latter because it creates workers after your local process exits. Create the executor key in the same OpenAI project and under the same owner as the application key. Under strict executor permission enforcement, it needs api.agents.environments.connect; List models: Read alone is insufficient. Ask your OpenAI representative if that permission is unavailable.
If the executor key is absent, application-managed examples warn and pass the project key into the Sandbox. Webhook deployment requires a separate executor key and rejects reuse of the project key.
This integration connects directly to the Agents API. It does not require a Model Gateway connection in Blaxel’s OpenAI integration settings.

​
Persistent files and agent teams

Agent Drive mounts durable files at /workspace/context in the cookbook. Those files survive deletion of the Sandbox that wrote them. Unmounted Sandbox files remain temporary. The team example uses Python to schedule two specialists in parallel and wait for their verified outputs before submitting the coordinator’s task. Agent Drive stores their files; it does not schedule tasks or transfer conversation history or model memory. Use Agent Drive permissions to define which workloads can access each Drive and path. A mount subdirectory alone does not isolate unrelated tenants or sessions.

​
Webhook lifecycle

The cookbook includes a handler deployed in a controller Sandbox with a public webhook endpoint. The first deployment prints OPENAI_AGENT_ID; export that ID so later deployments and the reconnect example use the same saved agent. Register the handler’s URL in your OpenAI project for agent.session.action_required and agent.session.failed.
  • The handler verifies each signature and accepts environment work only for its configured OPENAI_AGENT_ID.
  • On an agent.session.action_required delivery with an environment_connection action, it stores the session ID in SQLite, acknowledges the delivery, and re-reads the session before provisioning.
  • One worker serves each session. The worker connects outbound to OpenAI, and the pending input continues without being resubmitted.
  • The handler keeps the worker awake while its executor is connected. It does not delete a worker when the session becomes idle.
  • A failed session triggers worker cleanup. Deleting a session sends no cleanup webhook, so your application must also delete its worker.
To release a worker deliberately, stop its executor before deleting the Sandbox. Wait for OpenAI’s session.environment.disconnected event before sending the next input. OpenAI can then request a replacement worker, which mounts the same session’s Drive.
Sending input before OpenAI reports the environment disconnected can leave the turn without file access and does not trigger the provisioning webhook. Wait for the event rather than assuming deletion has already updated the OpenAI session.
The controller’s SQLite queue survives process restarts inside that Sandbox. Deleting or expiring the controller loses the local queue.

​
Configuration and limits

These are cookbook defaults and behavior, not platform-wide limits. The baseline can complete with temporary storage when Agent Drive access is unavailable. The fresh-session handoff, team example, and file-preserving reconnection check require Agent Drive. With temporary storage, a replacement worker starts with an empty filesystem. The examples verify a completed turn and durable idle state before reading the output file. They submit each task once, reject concurrent input to the same session, and use bounded waits: 180 seconds for application-managed turns and 600 seconds for webhook-managed turns, including worker setup.

​
Examples and cleanup

The cookbook README provides installation and credential setup. From a configured checkout, choose the example for your workflow: These examples create hosted resources, and the agent examples invoke a model. Check their printed cleanup results: the scripts delete temporary sessions and workers, while Agent Drive is retained deliberately. The reconnect example also retains the controller and webhook registration. When a deployment is no longer needed, remove its OpenAI webhook, controller, remaining workers, and API sessions. Inspect or export retained files before deleting their Drive, and use the configured resource prefix to avoid removing another deployment’s resources.

​
Resources

OpenAI Agents API tutorial

Run the example, hand files to another agent, and reconnect a session on a replacement Sandbox.

OpenAI Agents API cookbook

Run the examples and inspect their lifecycle, verification, and cleanup code.

Agent Drive

Configure durable files and access permissions.

Blaxel Sandboxes

Configure the computer, network controls, and resource lifetime.
Last modified on September 10, 2026