Skip to main content
Use this when an AI agent needs to work with real files and tools without running on your laptop or production server. OpenAI manages the agent session, Blaxel gives it a disposable cloud computer, and Agent Drive can keep selected files after that computer is deleted. This gives you three useful boundaries:
  • Let an agent run commands and create deliverables away from your local machine
  • Delete temporary compute after the task instead of maintaining another server
  • Pass explicit files to a fresh agent without pretending that model memory is shared
This tutorial uses the Blaxel OpenAI Agents API cookbook to demonstrate that lifecycle with a small report.

​
Who owns what

​
Prerequisites

  • Python 3.11 through 3.14 and Git
  • An OpenAI project and API key with Agents API access
  • The Agents API client version pinned by the cookbook, which ./run.sh installs
  • A Blaxel workspace and API key
Agent Drive is optional for the first run and required only for the fresh-session handoff.

​
1. Run the example

​
Prompt your agent

Copy this into a coding agent with terminal access:

​
Run it yourself

The default auto mode uses Agent Drive when available. Set BL_AGENT_DRIVE_MODE=off before the run for completely disposable storage.

​
2. Check the result

A successful run gives you a short, deterministic proof:
confirmed generated file is the line that matters. The script reads summary.md back and checks it for an exact marker from the source file, which proves the agent used the provided file instead of returning an ungrounded answer.

​
3. Try the fresh-session handoff

Agent Drive becomes most useful when another agent continues from an explicit file instead of copied conversation history.
The handoff performs one extra loop:
Both summary.md and review.md remain in the same Agent Drive run directory. The second agent must read the original verification marker before its review passes.
Agent Drive shares inspectable files. It does not copy model memory, conversation history, or session state.

​
4. Choose the storage behavior

If Drive access is unavailable, the baseline still completes and prints the workspace-specific Console page for requesting access. The --handoff path stops because a fresh Sandbox needs the persisted summary.md. Agent Drive currently requires us-was-1, which is the cookbook default.

​
5. Make it yours

Keep the lifecycle and replace the example task: Start with main.py for one session. Use handoff.py when your workflow needs a fresh agent to continue from a persisted artifact.

​
6. What’s next

Three idea starters, ordered by effort. Each is a prompt for a coding agent that has the cookbook cloned and the same environment variables set, and each was run end to end from the cookbook before being written down. The full prompts live in the cookbook’s What’s next section.
  1. Swap in your own document (2 minutes). Replace sample_report.txt with a document of yours, keep the verification-marker line, rerun ./run.sh, and confirm the kept summary.md reflects your document.
  2. Analyze data and open the result in your browser. The cookbook ships sample_data.csv. Have the agent compute totals and the busiest day, write a self-contained report.html with an inline SVG chart, then serve it from the sandbox and open it on a public preview URL.
  3. Run it as a hosted Blaxel job. Deploy the same orchestration as a Blaxel job and trigger an execution with no laptop in the loop. Inside a job, Blaxel injects workspace credentials, so the only secret the job needs is OPENAI_API_KEY.

​
7. Advanced details

OpenAI hosts the agent and session. Blaxel runs the Codex executor inside the isolated Sandbox. The executor connects outbound with a session-scoped environment ID, so you do not expose an inbound Sandbox port. The cookbook installs the pinned Codex executor in the Sandbox and starts it with codex exec-server --remote <agents-api-url> --environment-id <id>, so the version you test with is the version you run.
Wait for the session to return to idle, then call session.stream(input=...) again. Keep the same Sandbox and executor only for turns in that same session. Create a fresh Sandbox for a fresh OpenAI session.
Sandboxes move to standby when nothing is connected. The cookbook starts the executor with process keep-alive, so the Sandbox stays awake for as long as the executor runs and the session can take another turn without a reconnect.Treat the executor as bound to its Sandbox. If that Sandbox stops or reaches its expiration, start a fresh Sandbox and a fresh OpenAI session, and carry the work forward through the files on Agent Drive rather than expecting the previous session to resume.
The script prints every temporary session ID and Sandbox name. bl get sandboxes verifies only the Blaxel side. Delete a leaked Sandbox with bl delete sandbox <printed-name> -y, and delete the printed OpenAI session through the Agents API SDK when its deletion signal is absent.
Reusing this cookbook with the same BL_AGENT_DRIVE_NAME applies the correct workload label and scoped path. Custom consumers must use the same workspace and region, apply the matching workload label, and mount the permitted path. See Agent Drive permissions.
The Sandbox’s 15-minute lifetime is a cleanup backstop. It does not delete an OpenAI session or replace explicit cleanup.

​
Resources

OpenAI Agents API cookbook

Review the complete runnable example.

Blaxel Sandboxes

Learn how isolated execution environments work.

Agent Drive

Share durable files and artifacts across Sandboxes and agents.
Last modified on July 28, 2026