Skip to main content
Give an OpenAI-hosted agent a Blaxel computer to turn a source report into a summary. The cookbook saves a verified local result and optionally uses Agent Drive so a fresh session can review the work after the first computer is deleted.
The Agents API is a public beta. The cookbook uses the public openai package and client.beta.agents; private GitHub access is not required.

​
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 baseline is application-managed: the script starts one computer, runs the file task, verifies the result, and deletes its session and computer. The optional handoff starts a fresh pair only after the first has been deleted. Follow the tutorial for that reader journey. Webhook-managed execution is an optional extension. A controller starts or reconnects a worker when OpenAI requests an environment. Its separate cookbook guide covers deployment and registration.

​
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 BL_WORKSPACE and BL_API_KEY, or an installed Blaxel CLI with a bl login session. The deployed handler requires BL_WORKSPACE and BL_API_KEY because it creates workers after your local process exits. Create OPENAI_API_KEY on the API keys page with Agents read/write and Responses write permissions. Create a separate OPENAI_EXECUTOR_API_KEY on the Agents environment-key page, in the same organization, project, and user or service account as the session. Set all other permissions to None. The environment key permits connecting the executor only; a generic restricted API key with List models access does not establish that permission. Both keys are required. Missing or identical keys fail before a worker is provisioned. The application key stays outside workers; only the environment key is passed as CODEX_API_KEY to codex exec-server. Follow the OpenAI self-hosted setup for the current dashboard flow. This integration connects directly to the Agents API. It does not require a Model Gateway connection in Blaxel’s OpenAI integration settings.

​
Persistent files

The baseline saves a verified local copy in outputs/<run-id>/summary.md. Handoff saves review.md beside it. These copies let the reader inspect the result after temporary resources are removed. 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 saves its agent ID and controller identity in .runs/deployment-<prefix-or-default>.json. Later deployments and reconnection reuse that saved identity; OPENAI_AGENT_ID can select an existing saved agent explicitly. 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 agent.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. Start with the baseline, then try the optional handoff. The remaining commands are separate advanced examples: 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. Temporary resources are recorded immediately in .runs/<run-id>.json. Receipts distinguish created/reused ownership, deletion requested, deletion verified, intentional retention, and cleanup failure. Preserve the receipt if the process is interrupted:
The recovery command acts on the exact owned sessions and workers in that receipt and preserves Drives. Inspect or export retained files before deleting their named Drive. For a webhook deployment, keep the same OPENAI_WEBHOOK_RESOURCE_PREFIX and inspect or tear down its recorded resources:
The deployment manifest binds recovery to the original Blaxel workspace and API endpoint. A target mismatch stops cleanup. The controller records the workers and Drives it actually allocates, including resources left by partial setup; teardown stops provisioning before reading that inventory. Reused resources and application-owned OpenAI sessions are preserved. Before removing the controller, teardown saves its final inventory locally so a later cleanup attempt can resume. If the controller expires before that inventory is captured, automatic teardown stops because ownership cannot be recovered safely. Teardown retains Drives by default. Add --delete-drives only when you intend to remove the deployment’s recorded owned Drives and their files. OpenAI webhook registration is a separate dashboard resource. Export OPENAI_WEBHOOK_ID when deploying to record its identity. Teardown reports manual registration removal as pending until you remove that exact registration in the OpenAI dashboard and record your confirmation:
This command records your dashboard verification; it does not delete the registration through an API. Keep the signing secret in the environment, never in the manifest.

​
Troubleshooting

OpenAI Agents API tutorial

Create a summary, open the result, and let a fresh agent review the saved file.

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 11, 2026