Skip to main content

What You’ll Learn

  • Uploading a dataset once as a Declaw volume
  • Fanning out N agents, each in an isolated sandbox
  • Attaching the same volume to every sandbox at create time (no per-sandbox re-upload)
  • Wiring a single run_shell tool that dispatches into the sandbox the agent is attached to

Prerequisites

Env:
  • DECLAW_API_KEY, DECLAW_DOMAIN — your Declaw creds
  • OPENAI_API_KEY — OpenAI key for GPT-4.1

The Pattern

One upload, N sandboxes, N agents asking different questions of the same data.

Code Walkthrough

Upload the dataset once:
Spin up N sandboxes in parallel, each with the volume attached and its own GPT-4.1 agent:

Why a Volume Instead of sbx.files.write() per Sandbox?

The naive way would be to upload the CSV separately into each sandbox with sbx.files.write("/data/sales.csv", csv_bytes). That re-sends the bytes for every fan-out branch. A 500 MiB dataset across 10 agents = 5 GB of egress from your process. With a volume:
  1. The bytes cross the network once (the AsyncVolumes.create upload to Declaw’s object store).
  2. Every Sandbox.create(volumes=[...]) streams the same blob straight from object storage into its own overlay — in parallel, with no back-pressure between the sandboxes.
  3. Your script doesn’t re-read or re-send the dataset past step 1.

Security Surface Still Applies

Attaching a volume does not bypass any of Declaw’s guardrails. Each sandbox still runs behind its own network proxy, with PII redaction, prompt-injection detection, and the other SecurityPolicy scanners scoped to that sandbox. The volume’s bytes are delivered directly into the sandbox without passing through the network proxy.

Full Example

The runnable version is at cookbook/examples/openai-agents-volumes/main.py:
It synthesizes a 1000-row sales CSV, plants two outlier rows, and fans out three agents (revenue per product, average-per-region, outlier detector). Each agent returns a concrete numerical answer — the outlier agent correctly flags the planted rows.

Limitations recap

  • Volume body must be application/gzip (a tar archive gzipped).
  • 4 GiB upload cap.
  • Volumes are read-at-boot. Edits a sandbox makes to files under mount_path stay private to that sandbox and do not flow back to the volume.