
OpenAI Agents API: Run a Data Audit in a Cloud Sandbox
Summary
Run a durable Codex-powered agent in OpenAI's hosted sandbox with a custom tool and file outputs.
At DevDay on September 29, OpenAI shipped the Agents API: the harness that powers Codex, offered as a managed service. You describe an agent (model, instructions, tools), point it at a sandbox, and OpenAI runs the model-and-tool loop, keeps the session alive, compacts context, and lets you steer it mid-turn. You stop writing the loop that every agent project used to start with.
This guide builds something concrete with it: a data-audit agent. You hand it a messy sales CSV, it cleans the data with pandas inside an OpenAI-hosted sandbox, calls your Python function for currency rates, writes a markdown summary and a chart, and then takes a follow-up request in the same session. You will download the files it produced and, importantly, check its numbers against an independent pandas run.
Everything below was checked against the official docs and the current openai Python SDK (3.22.1). One honest caveat up front: the Agents API is in beta and I did not have a live API key in the environment that wrote this, so the event-handling code was exercised against a fake client and the request shape was verified against the real SDK, not run end to end. Where that matters, I say so.
What you will learn
- The four objects in the API: agent, environment, session, and events/items, and how they map to calls.
- How to start a streamed session in an OpenAI-hosted sandbox with input files and Python packages.
- How to implement a function tool using the
requires_actionpause, including error results. - How to continue a session, handle dropped streams, download artifacts, and clean up.
- The traps that will bite you: subagent events, a 'completed' turn that hid a tool failure, sandbox expiry, and cost.
Prerequisites
- Python 3.10+ and
pip install -U openai(theclient.beta.agentsnamespace needs a recent SDK). - An OpenAI project API key with the
api.agents.read,api.agents.writeandapi.responses.writepermissions. A restricted key without these will fail. - Access to
gpt-6-astra, the model the official quickstart uses. The docs do not publish a list of supported models, so treat that as the safe default. - A US-based data posture: per the overview page, the Agents API currently supports data residency only in the United States and does not support Zero Data Retention.
The mental model: four nouns
| Concept | What it is | In code |
|---|---|---|
| Agent | Model, instructions, tools, MCP servers | agent={...} on session create |
| Environment | The computer: files, packages, network, skills | environment={...} |
| Session | A durable instance of the agent working on tasks | session_id you store |
| Events / items | Inputs you send and outputs it produces | events.stream, items.list |
The loop is: create a session with a first task, watch the event stream, answer any requires_action pause, and stop when a top-level agent.session.turn.completed arrives. The session survives after that, so the next message continues the same work. Raw HTTP needs the header OpenAI-Beta: agents=v1; the SDK adds it for you (I confirmed this by capturing a request with a mock transport).
Step 1: Make some messy data
A good test for an agent is data where the right answer is knowable. This script writes 252 rows of orders in four currencies with 12 exact duplicates, 6 US-style dates and 5 blank amounts, then we compute ground truth with plain pandas.
"""Generate a deliberately messy sales CSV (deterministic) and the ground-truth totals."""
import csv, random, json
from datetime import date, timedelta
random.seed(7)
FX = {"USD": 1.0, "EUR": 1.08, "GBP": 1.27, "JPY": 0.0066}
customers = ["Acme", "Globex", "Initech", "Umbrella", "Hooli", "Stark"]
rows = []
start = date(2026, 7, 1)
for i in range(240):
d = start + timedelta(days=random.randint(0, 89))
cur = random.choices(list(FX), weights=[50, 25, 15, 10])[0]
base = random.randint(40, 900)
amount = base * 150 if cur == "JPY" else base
rows.append({"order_id": f"A{1000+i}", "date": d.isoformat(), "customer": random.choice(customers),
"currency": cur, "amount": amount})
# mess: 12 exact duplicate rows, 6 rows with a US-style date, 5 rows with blank amount
rows += random.sample(rows, 12)
for r in random.sample(rows, 6):
y, m, dd = r["date"].split("-"); r["date"] = f"{m}/{dd}/{y}"
for r in random.sample(rows, 5):
r["amount"] = ""
random.shuffle(rows)
with open("sales_q3.csv", "w", newline="") as f:
w = csv.DictWriter(f, fieldnames=list(rows[0])); w.writeheader(); w.writerows(rows)
print(len(rows), "rows written")
Now the independent check. This is the most important file in the project, because it is how you will know whether to trust the agent later.
"""Independent pandas check: what the agent's numbers SHOULD be."""
import pandas as pd
FX = {"USD": 1.0, "EUR": 1.08, "GBP": 1.27, "JPY": 0.0066}
df = pd.read_csv("sales_q3.csv")
print("raw rows:", len(df))
df = df.drop_duplicates()
print("after dedupe:", len(df))
df["date"] = pd.to_datetime(df["date"], format="mixed")
blank = df["amount"].isna().sum()
df = df.dropna(subset=["amount"])
print("blank amounts dropped:", blank, "-> clean rows:", len(df))
df["usd"] = df["amount"] * df["currency"].map(FX)
print("total USD: %.2f" % df["usd"].sum())
m = df.groupby(df["date"].dt.strftime("%Y-%m"))["usd"].sum().round(2)
print(m.to_string())
print("top customer:", df.groupby("customer")["usd"].sum().idxmax())
Real output from running both scripts:
252 rows written
raw rows: 252
after dedupe: 240
blank amounts dropped: 5 -> clean rows: 235
total USD: 110518.27
date
2026-07 43142.77
2026-08 33770.29
2026-09 33605.21
top customer: Acme
Step 2: Define the agent and its one custom tool
The agent config is small. instructions are appended to the harness's own base instructions, not a replacement for them, so write the task rules, not a persona. Tools go in agent.tools; a function tool is the familiar name, description and JSON Schema triple.
FX_TO_USD = {"USD": 1.0, "EUR": 1.08, "GBP": 1.27, "JPY": 0.0066}
GET_FX_RATE = {
"type": "function",
"name": "get_fx_rate",
"description": "Return the USD value of one unit of a currency (ISO 4217 code).",
"parameters": {
"type": "object",
"properties": {"currency": {"type": "string", "description": "e.g. EUR"}},
"required": ["currency"],
},
}
INSTRUCTIONS = (
"You are a careful data analyst. The input file is /workspace/sales_q3.csv. "
"Use pandas. Drop exact duplicate rows, parse mixed date formats, drop rows with a blank amount, "
"and convert every amount to USD with the get_fx_rate tool (call it once per currency). "
"Save a markdown summary to /workspace/outputs/summary.md and a bar chart of USD revenue by month "
"to /workspace/outputs/revenue_by_month.png. In your final answer, state rows before/after cleaning, "
"total USD revenue, revenue per month, and the top customer."
)
def get_fx_rate(currency: str) -> dict:
code = currency.upper()
if code not in FX_TO_USD:
raise ValueError(f"unsupported currency: {currency}")
return {"currency": code, "usd_per_unit": FX_TO_USD[code]}
TOOL_IMPLS = {"get_fx_rate": get_fx_rate}
Why a function tool for a lookup the agent could hardcode? Because it demonstrates the part you will actually need in production: the agent runs in OpenAI's sandbox, but your function runs on your side, next to your secrets and databases. The sandbox never sees them.
Step 3: Answer the requires_action pause
When the model calls a function, the session does not call you back over HTTP. It emits agent.session.requires_action and waits. The event carries the session, whose required_actions list holds each pending call with a call_id, turn_id, name and arguments. You reply with one agent.session.input.tool_result event per call. The session resumes once every pending call has a result.
def answer_actions(client, session) -> int:
"""Run every pending function_call and submit the results in one events.create call."""
results = []
for action in session.required_actions:
if action.type != "function_call":
raise RuntimeError(f"unhandled required action: {action.type}")
args = action.arguments
if isinstance(args, str): # be tolerant: object or JSON string
args = json.loads(args)
try:
out = TOOL_IMPLS[action.name](**args)
results.append({"type": "agent.session.input.tool_result", "turn_id": action.turn_id,
"call_id": action.call_id, "success": True, "output": json.dumps(out)})
except Exception as exc: # report tool errors to the agent instead of crashing the run
results.append({"type": "agent.session.input.tool_result", "turn_id": action.turn_id,
"call_id": action.call_id, "success": False, "error": str(exc)})
if results:
client.beta.agents.sessions.events.create(session.id, events=results)
return len(results)
Two details worth copying. First, failures are returned with success: false and an error string, so the model can recover (try another approach, tell the user) rather than your script dying. Second, output must be a string or content parts, so JSON objects are serialized with json.dumps. The arguments field is typed as a generic object in the SDK, so the code accepts either a dict or a JSON string.
Step 4: Consume the event stream correctly
The docs' reference loop treats a handful of events as terminal. Mine follows the same rules and adds text streaming and tool answering.
class RunState:
session_id: str | None = None
tool_calls: int = 0
def pump(client, events, st: RunState) -> bool:
"""Consume an event iterator. True once the TOP-LEVEL turn completed."""
for ev in events:
t = ev.type
if t == "agent.session.created":
st.session_id = ev.session.id
elif t == "agent.session.turn.output_text.delta":
print(ev.delta, end="", flush=True)
elif t == "agent.session.requires_action":
st.tool_calls += answer_actions(client, ev.session)
elif t == "error":
raise RuntimeError(ev.error.message)
elif t in ("agent.session.failed", "agent.session.environment.failed"):
raise RuntimeError(f"lifecycle failure: {t}")
elif t == "agent.session.turn.failed" and ev.turn.subagent_id is None:
raise RuntimeError(f"turn failed: {ev.turn.error.message if ev.turn.error else ''}")
elif t == "agent.session.turn.cancelled" and ev.turn.subagent_id is None:
raise RuntimeError("turn cancelled")
elif t == "agent.session.turn.completed" and ev.turn.subagent_id is None:
return True
return False
The subagent_id is None checks matter even though this agent never delegates. A turn event from a subagent carries a non-null subagent_id; if you treat its turn.completed as the end of the whole run, you will stop reading while the parent is still working. It costs one condition now and saves a confusing bug when you turn on multi-agent later.
Streams also drop. The docs say that if a stream closes before a turn ends you should retrieve the saved state. settle does exactly that: it fetches the session, answers any pending actions, and reopens the stream, up to five times.
def settle(client, st: RunState, events) -> None:
"""Drive one turn to completion, reconnecting if the stream drops."""
if pump(client, events, st):
return
for _ in range(5): # stream closed early: reconcile from saved state
session = client.beta.agents.sessions.retrieve(st.session_id)
if session.status == "requires_action":
st.tool_calls += answer_actions(client, session)
elif session.status == "idle":
return
elif session.status == "failed":
raise RuntimeError(f"session failed: {session.error}")
with client.beta.agents.sessions.events.stream(st.session_id) as again:
if pump(client, again, st):
return
raise RuntimeError("gave up reconnecting")
Step 5: Start the session in a hosted sandbox
This is where the environment earns its keep. The call below creates the session, uploads the CSV as an inline file (limit 5 MiB per inline file, 10 MiB per request, 50 files), installs pandas and matplotlib, and streams the first turn.
def start(client, csv_path: str, task: str) -> RunState:
st = RunState()
data = base64.b64encode(pathlib.Path(csv_path).read_bytes()).decode()
events = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra", "instructions": INSTRUCTIONS, "tools": [GET_FX_RATE]},
environment={
"type": "openai_hosted",
"container_size": "small",
"packages": {"python": ["pandas", "matplotlib"]},
"files": [{"type": "inline", "path": "/workspace/sales_q3.csv", "data": data}],
},
input=task,
stream=True,
)
settle(client, st, events)
return st
A few choices explained. container_size: small is 1 vCPU and 1 GB; the docs list small, medium and large. The working directory is /workspace. Anything the agent writes under /workspace/outputs is published as an immutable artifact when the turn completes, which is why the instructions name that path explicitly. For files above the inline limit, upload through the Files API and use {"type": "file_id", ...} instead.
The environment can also run setup_commands, load skills and plugins, set env variables, and restrict network to a list of exact hostnames. I left the network at its default (enabled) because package installation needs it; the hardening section below covers locking it down.
Step 6: Continue the same session
Here is the payoff of a durable session. The sandbox still has the cleaned DataFrame logic, the files and the installed packages. Send a short follow-up and the agent picks up where it left off. Open the stream first, then send the message, so you cannot miss early events. That ordering is straight from the docs.
def follow_up(client, st: RunState, text: str) -> None:
with client.beta.agents.sessions.events.stream(st.session_id) as events:
client.beta.agents.sessions.events.create(st.session_id, events=[{
"type": "agent.session.input.message",
"input": [{"role": "user", "content": [{"type": "input_text", "text": text}]}],
}])
settle(client, st, events)
If you send a message while a turn is running, you are not queuing a new task. You are steering the current one. That is useful for corrections like 'exclude JPY orders' while work is in flight, and surprising if you assumed queue semantics.
Step 7: Download the artifacts and clean up
def download_artifacts(client, st: RunState, out_dir: str = "out") -> list[str]:
saved = []
pathlib.Path(out_dir).mkdir(exist_ok=True)
for art in client.beta.agents.sessions.artifacts.list(st.session_id, order="asc"):
target = pathlib.Path(out_dir) / pathlib.Path(art.path).name
target.write_bytes(client.beta.agents.sessions.artifacts.content(art.id, session_id=st.session_id).read())
saved.append(str(target))
return saved
if __name__ == "__main__":
client = OpenAI()
st = start(client, "sales_q3.csv", "Audit sales_q3.csv and write the summary and chart.")
print("\n--- tool calls answered:", st.tool_calls)
follow_up(client, st, "Add a section to summary.md ranking customers by USD revenue, and save it again.")
print("\nsaved:", download_artifacts(client, st))
client.beta.agents.sessions.delete(st.session_id) # also asks OpenAI to clean up the sandbox
Artifacts are per-file downloads with no batch endpoint, so ask the agent to ZIP multiple outputs if you need one fetch. They survive the sandbox expiring but cannot be edited through the API; the published limit is 200 MiB per artifact. Deleting the session asks OpenAI to clean up the sandbox. If you call it mid-turn you can get a 409, so retry with a bounded number of attempts, or cancel the turn first with an agent.session.input.cancel event.
Test it without spending a cent
Agent code is awkward to test because the interesting part is a remote loop. The trick is that all the SDK calls are plain method calls, so a fake client with the same attribute path (client.beta.agents.sessions...) is enough. This test forces the nastiest path: the stream ends right after requires_action, one of the two calls fails, and the code must recover through retrieve.
"""Offline test: drive audit_agent with a fake client that replays realistic events, including a stream drop."""
from types import SimpleNamespace as NS
import audit_agent as A
def ev(t, **k): return NS(type=t, **k)
calls = []
class Events:
def create(self, sid, events): calls.append((sid, events))
def stream(self, sid):
class CM:
def __enter__(s): return iter([ev("agent.session.turn.output_text.delta", delta="done."),
ev("agent.session.turn.completed", turn=NS(subagent_id=None))])
def __exit__(s,*a): pass
return CM()
actions = [NS(type="function_call", name="get_fx_rate", call_id="c1", turn_id="t1", arguments={"currency":"eur"}),
NS(type="function_call", name="get_fx_rate", call_id="c2", turn_id="t1", arguments='{"currency":"XXX"}')]
class Sessions:
events = Events()
def create(self, **kw):
assert kw["stream"] and kw["environment"]["type"] == "openai_hosted"
sess = NS(id="sess_1", required_actions=actions)
# stream DROPS right after requires_action -> forces the reconcile path
return iter([ev("agent.session.created", session=sess), ev("agent.session.requires_action", session=sess)])
def retrieve(self, sid): return NS(id=sid, status="idle")
client = NS(beta=NS(agents=NS(sessions=Sessions())))
st = A.start(client, "sales_q3.csv", "go")
sid, evs = calls[0]
assert sid == "sess_1" and len(evs) == 2
assert evs[0]["success"] is True and '"usd_per_unit": 1.08' in evs[0]["output"]
assert evs[1]["success"] is False and "unsupported currency" in evs[1]["error"]
print("OK session:", st.session_id, "| tool results sent:", [(e["call_id"], e["success"]) for e in evs])
Output:
OK session: sess_1 | tool results sent: [('c1', True), ('c2', False)]
That proves the handler logic: the lowercase eur was normalized, an unsupported currency became a success: false result instead of an exception, and the reconnect path ran. It does not prove the live service behaves as documented, so run the real script once with a small CSV before you build on it.
What a correct run should report
Do not eyeball the agent's answer. Compare it to the ground truth from Step 1 programmatically. For this file, a correct final answer has these numbers:
| Quantity | Expected value |
|---|---|
| Rows before / after cleaning | 252 / 235 (12 duplicates, 5 blank amounts removed) |
| Total USD revenue | 110,518.27 |
| 2026-07 / 2026-08 / 2026-09 | 43,142.77 / 33,770.29 / 33,605.21 |
| Top customer | Acme |
| Tool calls to get_fx_rate | Four, one per currency (USD, EUR, GBP, JPY) |
If the agent's totals differ by a few dollars, the usual cause is rounding at a different step, or converting JPY with a rate it remembered instead of the one your tool returned. If they differ by thousands, it probably skipped the duplicate or blank-row rules. Both are worth knowing before you trust the same agent on real data.
Hardening and cost
- Lock the network after setup.
network.accessacceptsenabled,disabledorrestricted(1 to 100 exact host names, no wildcards). For an agent that only reads your file, restrict it. CheckGET /v1/agents/environments/{id}for afailedstatus if package installation breaks after you tighten it. - Keep secrets out of
env. Use vaults for credentials. The docs reserve names such asPATH,CODEX_*andOPENAI_API_KEY. - What you pay for. There is no separate Agents API fee. You pay model tokens at normal API rates, OpenAI-hosted tools at their rates, and sandbox time at container rates. One third-party write-up lists the small 1 GB container at about $0.03 per 20 minutes, billed per minute with a 5 minute minimum; confirm on OpenAI's pricing page before budgeting.
- Service tier. The agent config accepts
service_tiervalues includingfastandultrafast. Ultrafast was announced at a 6x price premium, so do not set it on a batch audit job.
Common pitfalls and gotchas
- 'Completed' does not mean 'every tool worked'. The docs say so explicitly. A turn can complete after a command failed or a function errored. Read the final items, and for anything that matters verify the output independently, as in the pandas check above.
- Subagent events look like top-level events. Filter on
turn.subagent_id is Nonebefore deciding the run is over. Skipping this works fine until the day you enable multi-agent. - Stream closed is not 'done'. Treat an ended stream as unknown state and call
sessions.retrieve. Arequires_actionstatus means the agent is waiting on you, and nobody else will answer. - Forgetting
/workspace/outputs. Files written anywhere else vanish with the sandbox. Name the path in the instructions, and checkartifacts.listrather than assuming. - Sandbox expiry. If there is no activity and no keep-alive for an hour, the sandbox can be deleted, and the timeout is not configurable. The session state is saved, but files you needed should have been published as artifacts first. Your application owns file persistence.
- Disconnected tools do not restart themselves. If an
environment_connectionrequired action appears, you need to reconnect the environment. The code above raises on unknown action types on purpose, so you notice. - Environment deletion does not stop external compute. With self-hosted or partner sandboxes (Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel are listed), you still own shutting down what you started.
- Unbounded loops cost real money. You are billed for every model turn and container minute. Put a wall-clock limit around
settle, and useagent.session.input.cancelwhen a run goes sideways. - Beta means moving parts. The endpoint needs
OpenAI-Beta: agents=v1, the SDK namespace isclient.beta.agents, and field names could change. Pin your SDK version. - Data residency. US only, no ZDR. If your contract requires zero retention, this API is currently not an option.
Quick reference
| Task | Call |
|---|---|
| Start (streamed) | client.beta.agents.sessions.create(agent=..., environment=..., input=..., stream=True) |
| Send follow-up / steer | sessions.events.create(id, events=[{'type': 'agent.session.input.message', ...}]) |
| Answer a function call | events.create(id, events=[{'type': 'agent.session.input.tool_result', 'call_id', 'turn_id', 'success', 'output'}]) |
| Cancel active turn | events.create(id, events=[{'type': 'agent.session.input.cancel'}]) |
| Reattach to stream | sessions.events.stream(id) |
| Inspect state | sessions.retrieve(id) (status, required_actions, usage) |
| Saved history | sessions.items.list(id, order='asc', limit=50) |
| Files out | sessions.artifacts.list(id) then artifacts.content(artifact_id, session_id=id) |
| Delete | sessions.delete(id) |
| Terminal events | turn.completed, turn.failed, turn.cancelled, session.failed, environment.failed |
| Session status values | idle, in_progress, requires_action, failed |
Next steps
- Add
{"type": "mcp", "server_label": ..., "transport": ...}toagent.toolsto give the agent your internal tools, and use vaults for the credentials. - Turn on
multi_agentand let the agent fan out one subagent per CSV, then wait on all of them. - Save the agent as a reusable object (
client.beta.agents.create) and start sessions withagent_id, overriding only what changes. - Register a webhook instead of holding a stream open, for jobs that run for minutes.
- Replace the toy FX table with a real call to your own service, and add a unit test per tool like the mock test above.
Sources
- OpenAI, Agents API overview: developers.openai.com/api/docs/guides/agents-api/overview
- OpenAI, Agents API quickstart: developers.openai.com/api/docs/guides/agents-api/quickstart
- OpenAI, Run and continue sessions; Events and items; Function tools; OpenAI-hosted sandboxes; Files and artifacts (same docs section)
- openai-python 3.22.1 type definitions for
client.beta.agents
Comments
Be the first to comment
Found this useful?
Get new AI guides for builders by email. Free.
Join 3,594 builders reading daily.