OpenAI Agents API Security and Data Guide: Network Allowlists, Sandbox Expiry, US Residency, No ZDR, and Artifact Retention

Start with the responsibility split, not the sandbox toggle

The OpenAI Agents API should be treated as a managed agent execution layer with shared responsibilities, not as a security boundary that automatically solves application risk. OpenAI’s Agents API documentation describes a managed interface to the Codex harness: OpenAI operates the session infrastructure, orchestration, context compaction, and recovery mechanisms, while the developer specifies the task, model, tools, and environment. That split matters because the highest-risk decisions usually sit outside the harness: which user is allowed to start a session, which tools the agent can call, what secrets those tools can reach, which network destinations are permitted, which outputs become durable artifacts, and which human reviewer must approve high-impact actions.

The practical security model has at least six layers. The managed harness coordinates turns and sessions; the application authenticates users, enforces authorization, stores session IDs, and validates outcomes; the execution environment determines whether code runs in an OpenAI-hosted workspace, your own infrastructure, or no filesystem at all; tools and MCP connections define what the agent can affect outside the session; data controls determine residency, retention, artifact handling, and whether a workflow is eligible for a given enterprise policy; and human operators approve sensitive changes, investigate failures, and decide when agent output is sufficient evidence for a business decision. A secure deployment documents each layer separately so that “the agent did it” never becomes an audit answer.

OpenAI’s documentation frames the Agents API around four concepts: an Agent, an Environment, a Session, and Events or Items. The Agent captures instructions, model choice, and tool configuration. The Environment is where work can be performed. The Session preserves configuration, conversation, and saved work across turns. Events and Items let the application follow progress, recover state, and inspect completed work. This article focuses on the security and data consequences of those concepts: where files live, when hosted sandboxes may expire, what happens to published artifacts, why network allowlists must be exact, and why the current Agents API retention posture is different from endpoint-specific compaction options in the Responses API.

Operational rule: choose the environment only after classifying the workload. The environment setting controls execution surface and file behavior, but it does not override application authorization, enterprise retention requirements, data residency constraints, human review obligations, or tool-level permissions.

Three environment choices at a high level

The first architecture decision is whether a workflow should use openai_hosted, self_hosted, or none. That choice is not merely a convenience preference. It determines where commands run, how files are handled, which network controls are available, how artifacts are produced, and what your team must monitor. A founder building an internal code-analysis assistant, an enterprise administrator reviewing data residency obligations, a research lead running reproducible data preparation, and a security team approving MCP access may all choose different environments for valid reasons.

The openai_hosted environment is the most convenient option for many developer workflows because OpenAI provides a Linux workspace with Python, Node.js, and command-line tools. The working directory is /workspace, and configuration can include pinned Python, system, and npm packages, ordered setup commands, files supplied through the Files API or inline base64, string environment variables, skills, plugins, capability directories, and reusable environment templates. Those features create an operational benefit, but they also expand the review surface: setup commands can fail, packages must be pinned intentionally, environment variables should not become a substitute for a secrets-management design, and published artifacts may outlive the sandbox.

The self_hosted environment shifts execution into infrastructure you operate or select, which can be attractive when a workflow must reach internal systems, use a pre-approved sandbox, integrate with existing logging, or satisfy infrastructure isolation requirements. It does not, however, change the core Agents API data rule stated in OpenAI’s documentation: the Agents API currently supports data residency only in the United States and does not support Zero Data Retention. A self-hosted sandbox may reduce what runs in OpenAI-hosted compute, but it does not convert the Agents API session into a ZDR endpoint or create non-US residency support for the API session.

The none environment is often the safest starting point for planning, triage, analysis, and structured-output workflows that do not require command execution. It avoids workspace file persistence and hosted artifact publication because there is no filesystem. The tradeoff is capability: if the workflow needs to run tests, transform files, zip outputs, or use command-line tools, none is the wrong execution model. A disciplined team starts with none when possible, moves to openai_hosted when managed execution is justified, and moves to self_hosted when infrastructure control is a hard requirement.

Classify the workload before approving an Agents API design

A workable classification process starts with a written task contract. The task contract should say what the agent is allowed to do, what it is forbidden to do, what systems it may reach, what data classes it may process, what outputs are expected, and what counts as completion. The contract must also state who owns approval for irreversible actions such as changing production code, publishing external content, modifying regulated records, executing financial transactions, or sending instructions to operational systems. Without this contract, environment selection becomes a guess and tool permissions tend to expand until they match the most permissive demo.

This article covers ChatGPT Sites security and privacy boundaries, including access controls, secrets, data residency, and safe publishing for hosted AI-generated sites. The complete ChatGPT Sites Security and Privacy Guide: Access Controls, Secrets, Data Residency, and Safe Publishing article provides the destination-specific detail for this section’s OpenAI Data Residency Guide decision because it is the closest allowed match for a data residency marker because it explicitly addresses data residency alongside adjacent security controls, making it useful context for the current article’s residency and trust-boundary discussion.

This Anthropic safeguards analysis provides a contrasting zero-data-retention architecture with customer-owned logs, helping readers see why the Agents API’s documented lack of ZDR must be evaluated as a product-specific boundary rather than a generic enterprise-AI assumption. The complete Anthropic Enterprise Frontier Safeguards Explained: Customer-Owned Logs, Zero Data Retention, and Cross-Session Misuse Detection article provides the destination-specific detail for this section’s Zero Data Retention Explained decision because the target is retained only as an explicit cross-vendor contrast that sharpens the Agents API no-ZDR decision.

Step 3: classify execution needs. Ask whether the agent must execute code, read or write files, install packages, call command-line tools, or generate downloadable outputs. If none of those are necessary, begin with none. If managed code execution and file production are necessary, evaluate openai_hosted. If the workflow must run inside your own isolation model, reach private infrastructure under your controls, or use pre-existing enterprise telemetry, evaluate self_hosted. This step should be documented as a capability requirement, not as a developer preference.

Step 4: classify network egress. For openai_hosted, OpenAI documents three network modes: enabled, disabled, and restricted. Restricted mode accepts only 1 to 100 exact hostnames. It does not accept wildcards, protocols, paths, or ports, and subdomains or redirect destinations may require separate entries. A template’s inherited network policy cannot be broadened by an override. Those rules make the allowlist review concrete: list every external hostname the workflow needs, include redirect targets, reject catch-all domains, and test failure behavior when a destination is not permitted.

Step 5: classify tool authority. Tools should be reviewed as delegated permissions rather than convenience functions. A search tool, MCP server, custom function, or command-line capability can expose data, trigger writes, or create business obligations depending on what it reaches. The application should authorize tool use based on the end user, tenant, task type, and approval state. The application API key should not be embedded inside the agent sandbox, because the sandbox should never become the place where your privileged platform credential can be discovered, printed, copied into an artifact, or used outside the intended server-side control path.

Step 6: classify artifact obligations. In the OpenAI-hosted environment, files placed under /workspace/outputs are published as immutable artifacts after a turn completes and remain downloadable after sandbox expiry. That behavior is useful when a workflow must produce a report, archive, patch, dataset extract, or audit bundle. It also means teams need artifact naming rules, download procedures, retention decisions, deletion procedures, and content scanning where required. Artifact deletion does not erase the live environment file while the environment still exists, so teams should treat live files, published artifacts, and session items as related but distinct records.

Step 7: classify lifecycle and failure handling. Session creation means setup has started, not that the hosted environment is ready. A hosted environment must reach connected before the application treats it as usable, and failed includes an environment error. A completed turn is not proof that every tool succeeded, agent.session.idle alone is not success, and closing an event stream does not cancel the task. Applications must inspect turn outcomes, saved items, and required actions; recover disconnected streams without blindly retrying; and delete sessions when they are no longer needed.

The first approval gate: decide whether Agents API is allowed for the workload

The first gate should be a binary policy decision before implementation begins. If the workload requires non-US data residency, the current Agents API documentation says the answer is no. If the workload requires Zero Data Retention, the current Agents API documentation says the answer is no. If the workload requires code execution but cannot permit outbound network access except to reviewed hostnames, openai_hosted may still be viable with restricted network mode, but only if the exact-host allowlist can be maintained and tested. If the workload requires hosted stdio MCP servers, note that OpenAI documents enabled network access as currently required for hosted stdio MCP servers, which may conflict with a restricted-egress policy.

The second gate is whether the organization can operate the session lifecycle responsibly. Hosted sandboxes receive keep-alives while connected, but OpenAI documents that if activity and keep-alives stop for one hour, the sandbox can be deleted, and that timeout is not configurable. Templates save configuration rather than preserving a running workspace. Therefore, any workflow that treats the sandbox as durable storage is misdesigned. Durable records should be retrieved from saved session items or downloaded artifacts according to your retention policy, and transient workspace state should be considered disposable.

The third gate is whether human review is built into the workflow at the right points. Agents can generate code, modify files, prepare artifacts, and coordinate subagents, but the application and its operators remain responsible for deciding whether output is correct, safe, compliant, and complete. In multi-agent mode, the coordinator and subagents share one environment filesystem; creating a subagent does not create a separate sandbox. Independent tasks can benefit from delegation, but agents editing the same files need coordination, and completion of a coordination item does not prove the subagent finished its assigned work. Human review and application-level validation must reflect those mechanics.

A secure Agents API program should end this opening review with a one-page workload record: approved environment, allowed data classes, residency and ZDR decision, network mode and hostnames, tool permissions, secret-handling plan, artifact rules, session deletion rule, failure-recovery plan, and human approval gates. That record gives developers a concrete implementation target, gives security teams something testable, and gives enterprise administrators an audit trail for why a workflow used openai_hosted, self_hosted, or none instead of relying on an informal sandbox choice.

Design network access and secrets as separate control planes

The OpenAI-hosted environment gives each session a separate Linux workspace with Python, Node.js, command-line tools, and a working directory at /workspace. That convenience should not be treated as a reason to collapse network policy, credentials, package installation, and task authorization into one setting. A secure Agents API design separates four questions: whether the sandbox may reach the network, which exact destinations are allowed, which credentials are injected into the sandbox, and how the application proves the environment is ready before the agent starts relying on installed tools or files.

This article compares Falcon Guardian runtime detection with Codex managed configuration, distinguishing behavior monitoring from preventive controls that constrain what AI agents can attempt. The complete Falcon Guardian vs Codex Managed Configuration: Runtime Detection vs Preventive Agent Controls article provides the destination-specific detail for this section’s Network Egress Controls decision because network egress allowlists are preventive agent-boundary controls, so this target adds relevant context on the difference between configuring limits up front and detecting risky behavior later.

What enabled, disabled, and restricted network policies mean operationally

Use disabled as the default for workflows that transform provided files, run unit tests against code already present in the workspace, produce reports from attached data, or operate on session items without requiring live external retrieval. This mode forces the team to package inputs deliberately and prevents the sandbox from becoming an implicit internet client. If the task later fails because a tool expected network access, that failure is a useful signal that the dependency model was incomplete.

Use restricted when the workflow has a defined external dependency list. Restricted mode accepts only exact hostnames, and OpenAI’s documentation states that it does not accept wildcards, protocols, paths, or ports. That means api.vendor.com can be an allowlist entry, while https://api.vendor.com/v1, *.vendor.com, api.vendor.com:443, and path-specific entries are not valid representations of the documented rule. Security reviewers should require a business owner, data classification, expected method of authentication, and failure behavior for every hostname.

Use enabled only when the workflow’s requirements cannot be expressed as a stable 1–100 hostname allowlist or when an OpenAI-documented capability requires it. The important example in the current hosted-environment documentation is stdio MCP: hosted stdio MCP servers currently require enabled network access. That does not mean all MCP usage should be approved casually; it means the architecture review must explicitly account for the broader egress posture created by the current stdio MCP requirement.

Exact-host allowlists: redirects, subdomains, and dependency endpoints

Restricted mode is exact-host based, so reviewers must model the real traffic path rather than the human-facing vendor name. A request to one hostname may redirect to another hostname, and OpenAI’s hosted-environment guide states that redirect destinations require separate entries. Subdomains also require separate entries. If a workflow calls github.com but file downloads are served from another GitHub-controlled hostname, the redirect or asset hostname must be reviewed and listed separately if the workflow depends on it.

Do not approve wildcard-style reasoning such as “all vendor subdomains are fine” when the configured control only accepts exact hostnames. If a team needs api.vendor.com, auth.vendor.com, and files.vendor.com, those are three separate review items. The same rule applies to package ecosystems. Installing packages during setup may require registry hosts, metadata hosts, tarball hosts, or binary-wheel hosts; each reachable hostname should be identified through a dry run, a package-lock review, or an internal dependency proxy rather than guessed from a package manager name.

A practical review pattern is to start with disabled, run setup with all required files preattached, and record the first failure that truly requires outbound network access. If network access is justified, move to restricted with the smallest observed hostname set. If restricted mode cannot support a documented requirement, escalate to an enabled-network exception with a time-bound owner and compensating controls such as reduced credentials, synthetic test data, and post-run artifact review.

Environment templates inherit controls; they do not preserve a live workspace

OpenAI’s hosted environment supports reusable environment templates, but a template is configuration, not a preserved running sandbox. A new session still gets its own workspace, and session creation means setup has started rather than completed. Treat templates as a way to standardize package pins, setup commands, files, skills, plugins, capability directories, environment variables, and network policy—not as a way to keep stateful secrets or a warmed, long-lived machine.

The most important template rule for network security is that an override cannot broaden an inherited network policy. If a template defines a restrictive posture, a session using that template cannot widen it through an override. This is useful for platform teams because it lets them publish approved templates for sensitive workloads and prevent application teams from silently turning a locked-down environment into an open egress environment. Conversely, a permissive base template is dangerous because downstream users may assume it represents an approved baseline.

Secrets: isolate the application API key from sandbox credentials

The application API key that calls the Agents API belongs on the application side of the trust boundary. OpenAI’s Agents API overview and quickstart requirements include application permissions such as api.agents.read, api.agents.write, and api.responses.write, but that key should not be embedded inside the agent sandbox. If model-generated code can read the application key, a compromised prompt, dependency, or tool invocation can attempt to act as the application rather than as a constrained task worker.

Credentials passed into the sandbox should be narrower than the application credential and scoped to the specific external resource the task needs. For example, a sandbox that reads from a documentation API should receive a read-only token for that API, not the application’s platform credential, administrator token, or broad cloud account secret. For financial, healthcare, research, or regulated enterprise workflows, prefer short-lived, task-specific credentials issued by the application after authorization checks rather than persistent secrets embedded in templates.

String environment variables are a supported hosted-environment configuration mechanism, but they are not a substitute for secret governance. Treat every environment variable injected into the sandbox as readable by code executed in that session. Do not place secrets in setup-command output, dependency-install logs, generated artifacts, or files under /workspace/outputs. Files in /workspace/outputs are published as immutable artifacts after a turn completes, so accidentally writing a token there can convert a transient runtime mistake into a downloadable artifact-retention issue.

# Illustrative setup pattern, not an API schema.
# Goal: verify tools without printing secret values.

python --version
node --version
mkdir -p /workspace/outputs
python -m pip install --require-hashes -r /workspace/requirements.txt
python - <<'PY'
import os, sys
required = ["TASK_API_TOKEN", "TASK_API_BASE_HOST"]
missing = [name for name in required if not os.getenv(name)]
if missing:
    raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
print("Runtime configuration check passed; secret values were not printed.")
PY

The example above demonstrates a safe readiness pattern: check that required variables exist, but do not echo their values. The same principle applies to package manager commands, shell debugging, and error handling. Avoid set -x in setup commands when secrets may appear in command arguments or environment-expanded strings. If a diagnostic trace is needed, redact values before writing logs into the workspace or artifacts.

Setup commands and dependency pinning are part of the security boundary

The hosted sandbox supports ordered setup commands and pinned Python, system, and npm packages. Use those features to make the environment reproducible and reviewable. A setup script that installs whatever is latest at session start creates two risks: the agent may see different behavior across sessions, and an attacker who influences package resolution may gain code execution before the task begins. Pinning does not prove a dependency is safe, but it creates a stable object for vulnerability review, license review, and incident rollback.

For Python, pin exact versions and prefer hash verification where your packaging workflow supports it. For npm, use a lockfile committed and reviewed outside the sandbox. For system packages, document the package name, version expectation, and why it is required. If a dependency is needed only to unpack a file or run a simple transformation, consider replacing it with a smaller reviewed utility or precomputing that step before session creation.

# Illustrative dependency review checklist for a hosted environment template.
# This is a governance artifact, not an Agents API payload.

network_policy: restricted
allowed_hosts:
  - pypi.org
  - files.pythonhosted.org
  - registry.npmjs.org
setup_controls:
  - "All Python packages are exact-version pinned."
  - "npm install uses a reviewed lockfile."
  - "Setup commands do not print environment variables."
  - "The session fails if expected tools are missing."
  - "No production administrator credentials are injected into the sandbox."
readiness_gate:
  - "Environment state must be connected before task acceptance."
  - "A failed environment state blocks the user workflow and surfaces the environment error."

The hostname list in this illustrative checklist is not a universal recommendation. It shows how exact hostnames should be represented when a team has intentionally approved public package registries. Many enterprise teams should instead use an internal package proxy or preattached dependency bundle, especially when handling confidential data or when outbound network review requires fewer destinations.

Readiness checks: creation is not connection

The create-session response for an OpenAI-hosted sandbox means setup has started; it does not mean the environment is ready. OpenAI’s hosted-environment documentation states that environment state must reach connected, and that failed includes an environment error. Applications should expose this distinction in their own state machine rather than letting users submit sensitive work into a session whose tools, files, or packages may not exist yet.

A practical readiness gate has three layers. First, wait for the environment state to become connected before accepting work that depends on command-line execution. Second, run a lightweight verification command that checks tool versions, expected directories, required environment variables, and access to approved hosts without printing secrets. Third, after the turn completes, inspect saved items and tool outcomes; a completed turn is not proof that every command, package install, MCP call, or generated artifact succeeded.

Threat models to apply before approving network and secret settings

The strongest design is usually boring: no application API key in the sandbox, no broad network access unless a documented requirement forces it, exact-host allowlists when external access is necessary, pinned dependencies, nonprinting setup checks, and a readiness gate that treats connected as a prerequisite rather than a success outcome. That pattern does not remove the need for application authorization, audit, budget controls, human approval, or domain review, but it prevents the sandbox from becoming the uncontrolled part of an otherwise well-governed Agents API deployment.

Model the session lifecycle as a data-retention system

The hosted sandbox is not just a compute target; it is a temporary workspace with files, turns, published artifacts, session state, and deletion behavior that must be designed before the first production user submits a task. OpenAI documents that each hosted session has a separate workspace, files persist across turns while the sandbox exists, and files written under /workspace/outputs are published as immutable artifacts after a turn completes. That means the same workflow can have at least two materially different copies of the same result: a live file inside the running workspace and a published artifact available after sandbox expiry.

The safest operational pattern is to define a retention contract for every class of file before the agent runs. Source inputs, intermediate scratch files, model-generated reports, logs, exported datasets, screenshots, package caches, and final deliverables should not be treated as one bucket. A financial research workflow, for example, may allow a generated presentation artifact to be retained long enough for download while requiring intermediate valuation spreadsheets and raw provider exports to be removed or excluded from published outputs. A code-repair workflow may allow patch files to become artifacts but block credentials, local dependency mirrors, or private test output from being copied into /workspace/outputs.

Separate session workspaces do not mean separate data classifications

OpenAI’s hosted environment gives each session its own workspace, so one session’s live files are not the same running filesystem as another session’s live files. That isolation is useful for containment, but it is not a substitute for data classification, application authorization, or tenant-aware design. If your application lets users upload files into a session, the application still needs to verify that the user is allowed to process those files, that the selected environment is allowed for the data category, and that any published outputs can be exposed to the intended recipient.

Use separate sessions when work should have separate lifecycle boundaries. A customer-support summarization job, a legal document comparison, and a software build investigation should not be placed into the same durable session merely because they are all initiated by the same user. Reusing a session carries forward conversation, configuration, and saved work across turns, which is valuable for iterative work but risky when the next task has a different access level, matter number, customer account, project, or retention policy.

This article provides an enterprise guide to AI agent governance, covering security, compliance, and risk management for agents that can take actions across business systems. The complete AI Agent Governance for Enterprises: Complete Guide to Security, Compliance, and Risk Management in 2026 article provides the destination-specific detail for this section’s Secret Management for AI Agents decision because secret management is a core enterprise AI-agent security concern, and this governance-focused post is the strongest allowed match for placing secrets in the broader risk-control framework.

Multi-agent mode shares the filesystem, so file coordination is mandatory

Multi-agent execution changes the coordination problem but not the environment boundary. OpenAI documents that the coordinator and subagents share one environment filesystem; creating a subagent does not create a separate environment. Subagents inherit configured MCP tools, credentials and allowed tools, web-search settings, files, and command-line access. This is efficient for independent tasks that need to inspect or contribute to one workspace, but it creates predictable hazards when multiple agents edit the same directory, report, package lockfile, database dump, notebook, or generated artifact.

Design multi-agent file rules as if several engineers are working in the same checkout without branch protection. Independent tasks can use separate subdirectories, explicit filenames, and merge steps controlled by the coordinator. Dependent tasks should usually remain with the main agent because multi-agent mode is intended for independent delegation, not tightly ordered chains. If two subagents can write to /workspace/outputs, the application should define which agent owns the final artifact name and how conflicts are handled before publication.

A simple convention is to allocate a work path per subagent and reserve /workspace/outputs for coordinator-approved deliverables. For example, a research coordinator can instruct subagents to write drafts under /workspace/subagents/{task-name}/, then have the coordinator review, merge, and copy only the accepted report into /workspace/outputs. This pattern reduces accidental artifact publication and gives reviewers a clearer trail of intermediate work.

Operational warning: an event showing subagent creation or a coordination call is not proof that the subagent finished its task. OpenAI documents that saved items and turns are the reliable place to inspect prior work, and applications must distinguish root-agent outcomes from subagent events.

This article explains OpenAI Secure MCP Tunnel architecture, authentication boundaries, and how to connect ChatGPT to private MCP servers without exposing them publicly. The complete OpenAI Secure MCP Tunnel Explained: Connect ChatGPT to Private Servers Without Public Exposure article provides the destination-specific detail for this section’s MCP Security Guide decision because it is an exact MCP security match and directly supports the current article’s discussion of securely connecting agent workflows to private tools and servers.

Live files and immutable artifacts have different risk profiles

Live files exist inside the running environment and can be changed by the agent while the sandbox exists. Published artifacts are immutable copies created from files under /workspace/outputs after a turn completes. That difference matters for incident response: deleting an artifact does not delete the corresponding live environment file, and modifying or deleting a live file does not retroactively change an already published artifact. If sensitive material was accidentally published, remove the published artifact through the supported artifact deletion path and also inspect the live workspace while it still exists.

Do not use /workspace/outputs as a general scratch directory. The safer pattern is to write temporary data to a non-output path, run validation, redact or transform the deliverable, and only then copy the approved file to /workspace/outputs. For high-risk workflows, require a coordinator or application-side review step before the copy operation. The review can verify filenames, file sizes, expected content types, and whether the output contains secrets, regulated records, customer identifiers, or third-party data that should not become a downloadable artifact.

Artifact persistence is useful precisely because hosted sandboxes can expire. OpenAI documents that artifacts remain downloadable after sandbox expiry, while live files in the expired sandbox are no longer a reliable place to retrieve work. This means final deliverables should be intentionally published before the sandbox disappears, but it also means accidental publication can outlive the workspace that created it. Teams should treat artifact publication as a data-export event, not merely a filesystem operation.

Plan for one-hour inactivity expiry instead of trying to outwait it

OpenAI documents that connected hosted sandboxes receive keep-alives, and that if activity and keep-alives stop for one hour, the sandbox can be deleted. The timeout is not configurable. This should be treated as an upper-bound lifecycle constraint for live workspace access, not as a scheduling feature. A long-running application should not assume that pausing user interaction, closing a browser tab, or losing a stream leaves a recoverable live filesystem indefinitely available.

Keep-alives reduce accidental loss while a connected workflow is active, but they are not an archival strategy. If the business process requires a generated report, test log, transformed dataset, or screenshot, the agent should publish the approved output under /workspace/outputs and the application should download or register the resulting artifact according to policy. If the process requires no durable output, the agent should avoid placing files in /workspace/outputs and the application should delete the session and any artifacts that were created unintentionally.

Stream handling must not be confused with lifecycle control. OpenAI documents that closing an event stream does not cancel the task. If a user leaves a page, the server should decide whether to continue monitoring, open a recovery stream, retrieve saved items, cancel the active turn, or delete the session when safe. A client-side disconnect by itself is not a reliable privacy or cost-control action.

1. Before starting the turn, decide whether the workflow is expected to produce a durable artifact, only session items, or no retained output.
2. During the turn, keep intermediate files outside /workspace/outputs unless publication is intended.
3. When the root turn completes, fails, or is cancelled, inspect saved items and tool results instead of relying on idle or stream closure.
4. Before sandbox expiry, download required artifacts or copy approved deliverables into /workspace/outputs during a controlled follow-up turn.
5. At workflow close, delete unnecessary artifacts and the session according to the retention record maintained by your application.

File limits should shape your packaging strategy

The documented file limits are not cosmetic; they determine whether the agent should receive many source files, a compressed bundle, or a smaller manifest that fetches data through approved tools. OpenAI documents limits including 50 files supplied at session creation, 5 MiB per inline file before base64 encoding, 10 MiB total inline payload per create request, 50 MiB per Files API file, 200 MiB per published artifact, and 500 MiB total outputs published together. The API downloads one artifact per request, so multiple deliverables may need to be zipped inside the workspace before publication.

For source inputs, prefer a manifest plus explicit retrieval logic when the workflow deals with many files or large corpora. For final outputs, prefer predictable packaging: one human-readable report, one machine-readable data file, and one archive only when multiple files are necessary. Avoid publishing dependency directories, virtual environments, package caches, or full repository copies unless the review policy explicitly allows them and they fit within artifact limits.

Deletion semantics: remove the right object, at the right time

Deletion must target the correct object. Deleting a published artifact removes that published artifact, but it does not delete a live file that remains inside an active sandbox. Deleting or changing a live file does not remove an immutable artifact that was already created. Deleting the session is the workflow-level cleanup action, but required artifacts should be downloaded before deleting the session because artifacts are tied to session lifecycle and should not be treated as a permanent records repository.

When a session is busy, deletion can require retry logic rather than a single forced call. OpenAI documents that deleting a busy session can return 409, which should be retried with a bounded delay. The important control is bounded retry: a cleanup worker should not loop forever, and it should escalate when a session remains busy beyond the policy window. Escalation can mean cancellation, operator review, or quarantine of downstream access to any artifacts already produced.

Applications should also avoid blind retries after stream interruption. Saved session items and turn state should be retrieved before deciding whether to retry, cancel, or continue. Otherwise, the application may duplicate tool calls, publish duplicate artifacts, or overwrite a live file with a second attempt while the first turn is still completing.

{
  "retention_record": {
    "session_id": "stored_by_application",
    "data_classification": "internal | confidential | regulated",
    "artifact_policy": "none | approved_outputs_only | download_then_delete",
    "cleanup_deadline": "application_defined",
    "on_busy_delete": "bounded_retry_then_escalate",
    "verification": [
      "retrieve saved items",
      "list expected artifacts",
      "download required artifacts",
      "delete unnecessary artifacts",
      "delete session when safe"
    ]
  }
}

United States residency and no Agents API ZDR are hard eligibility constraints

OpenAI’s Agents API documentation states that the current API supports data residency only in the United States and does not support Zero Data Retention. That statement is workload-shaping, not a footnote. If a project requires non-US data residency, contractual ZDR for the endpoint, or a policy that forbids managed session retention, the Agents API should be considered ineligible unless OpenAI’s documentation and your agreement later establish a different supported posture.

Self-hosting the sandbox does not change that Agents API retention boundary. A self-hosted environment can change where code executes, how files are mounted, how outputs are retrieved, and how your infrastructure enforces local controls. It does not make the managed Agents API ZDR-eligible, and it does not create a non-US data residency option for Agents API session state. Treat self-hosting as an environment-control decision, not a way to bypass endpoint-level data policy.

This point is especially important for regulated enterprises that already use different OpenAI API endpoints under different data controls. A project approved for one endpoint should not automatically be approved for Agents API sessions. The approval record should name the endpoint, environment type, data residency requirement, retention requirement, artifact behavior, and whether any customer, patient, employee, financial, legal, or source-code data will enter the managed session.

Do not transfer Responses API compaction assumptions to Agents API sessions

OpenAI documents a separate compaction guide for the Responses API. In that context, server-side compaction can be ZDR-friendly when Responses requests use store=false, and the standalone compact endpoint is stateless and ZDR-friendly. OpenAI also describes compaction outputs as opaque encrypted state that is not intended for human interpretation. Those conditions belong to the documented Responses API compaction paths, not to the Agents API’s durable managed sessions.

The distinction is subtle enough to deserve an explicit architecture review. Agents API sessions include managed orchestration, durable state, automatic context management, recovery behavior, environment interaction, saved items, and artifact publication. Responses API compaction is an endpoint-specific mechanism for carrying compressed context state under documented conditions. A security design that says “we use compaction, therefore we are ZDR-friendly” is incomplete unless it names the endpoint and confirms the documented ZDR conditions for that endpoint.

Approval checklist for lifecycle and retention controls

Before moving an Agents API workflow into production, require a written answer for each lifecycle question rather than leaving behavior to agent discretion. The application should know which files can be created, which directories are scratch-only, which outputs may be published, how large they may be, who may download them, when they are deleted, and whether the workload is eligible for United States-only residency and no ZDR. If any answer is unknown, the workflow should remain in a lower-risk test environment with synthetic or approved non-sensitive data.

• Session boundary: one session maps to one authorized workload, tenant boundary, retention policy, and data classification.
• Multi-agent filesystem: subagents use assigned working directories, and the coordinator owns final publication into /workspace/outputs.
• Live-file hygiene: secrets, raw regulated data, caches, and unreviewed intermediate files are not placed in the outputs directory.
• Artifact governance: published artifacts are treated as immutable exports that can outlive sandbox expiry and must be deleted when no longer needed.
• Expiry handling: required deliverables are published and downloaded before relying on a sandbox that may be deleted after one hour without activity and keep-alives.
• Limit compliance: input and output packaging respects documented file, inline payload, artifact, and total-output limits.
• Deletion workflow: cleanup distinguishes artifact deletion, live file removal, cancellation, session deletion, and bounded retry after busy-session conflicts.
• Endpoint eligibility: projects requiring non-US residency or Agents API ZDR are rejected or redesigned around a documented endpoint that satisfies those requirements.

Governance pack: registers, matrices, and review evidence

Recommendation: treat every Agents API deployment as a governed data flow, not only as a coding project. The official documentation describes managed sessions, environment choices, OpenAI-hosted sandboxes, self-hosted options, multi-agent execution, artifact publication, United States data residency, and the absence of Zero Data Retention for the Agents API. A security review should therefore record where data enters, where it is processed, where it is copied, when it becomes an artifact, and which objects must be deleted or exported before the session is removed.

This article covers ChatGPT Library sharing governance, including viewer and editor roles, folder ownership, access revocation, and file custody. The complete ChatGPT Library Sharing Governance Guide: Viewer and Editor Roles, Folder Ownership, Access Revocation, and File Custody article provides the destination-specific detail for this section’s Agent Artifact Governance decision because artifact retention and governance depend on ownership, custody, and revocation rules, making this file-governance article a useful companion for the current article’s artifact-handling section.

Data-flow register for an Agents API workflow

Retention matrix for sessions, environments, files, and artifacts

Network approval checklist for restricted, disabled, and enabled access

Decision rule: start with network access disabled unless the task has a documented need for outbound connectivity. Move to restricted access when the exact external hosts are known and stable. Use enabled access only when the task requires broader connectivity, such as cases where a documented hosted stdio MCP requirement cannot be met under restricted access, and record the risk acceptance separately.

1. Confirm the environment type. OpenAI-hosted, self-hosted, supported partner environments, and environment type none have different file and network implications.
2. List every required destination. For restricted mode, OpenAI documents 1–100 exact hostnames only; do not include protocols, paths, ports, or wildcards.
3. Test redirects and subdomains. If a host redirects to another hostname, or if assets are served from subdomains, approve each required hostname separately.
4. Review package installation paths. Setup commands that install Python, system, or npm packages can introduce additional network dependencies and supply-chain risk.
5. Validate inherited template controls. A template’s inherited network policy cannot be broadened by an override, so template design should match the strongest expected control.
6. Separate credentials from egress approval. A hostname allowlist does not prove the tool call is authorized, and a credential does not justify broad network access.
7. Record MCP requirements explicitly. If a hosted stdio MCP server requires enabled network access, document why restricted access is insufficient and what compensating controls apply.

Incident response runbook for session, artifact, and egress failures

Procedure: classify incidents by the object affected. A leaked application API key, an overbroad hostname allowlist, an unintended published artifact, a failed turn, and a stream disconnect require different containment steps. The runbook should also preserve evidence because streams do not replay missed events and list endpoints are paginated.

Quarterly evidence review for administrators and risk owners

Recommended review cadence: every quarter, sample production workflows and verify that documentation, configuration, and observed behavior still match. This is especially important because the Agents API is documented as a beta surface and because environment templates, tools, network policies, and data classifications can drift after the original launch approval.

• Residency and ZDR eligibility: confirm that every approved workload can operate with United States data residency and without Agents API Zero Data Retention.
• Environment inventory: list OpenAI-hosted, self-hosted, partner-hosted, and no-filesystem workflows; verify that each has a retention and deletion plan.
• Network policies: compare configured restricted hostnames with the approved register; remove unused destinations and document any enabled-network exceptions.
• Secret paths: prove application API keys remain outside sandboxes and that sandbox environment variables contain only task-appropriate credentials.
• Artifact sampling: inspect a sample of published artifacts, confirm they were intentionally created under /workspace/outputs, and verify deletion records where applicable.
• Recovery testing: simulate a disconnected stream and verify that the application retrieves saved items, handles pagination, and checks root-turn outcomes before retrying.
• Multi-agent file coordination: confirm that workflows using subagents account for the shared filesystem and do not assume each subagent has its own sandbox.
• Documentation deltas: compare implementation assumptions with the current OpenAI documentation before renewing approval.

Deployment decision tree for security approval

1. Does the workload require non-US residency or Agents API ZDR? If yes, do not deploy on the Agents API under the current documented constraints. If no, continue.
2. Does the task require a filesystem? If no, consider an environment design without a filesystem and read output from session items. If yes, continue.
3. Can the task run without outbound network access? If yes, disable network access. If no, continue.
4. Are all outbound destinations exact, stable hostnames? If yes, use restricted mode and approve each hostname. If no, continue only with explicit risk acceptance for enabled access.
5. Will the workflow write user-deliverable files? If yes, define which files may enter /workspace/outputs, who may download artifacts, and when artifacts are deleted.
6. Will multiple agents edit shared files? If yes, require file-locking conventions, path ownership, or coordinator review because subagents share one environment filesystem.
7. Can the application recover safely from incomplete event streams? If no, block production deployment until item reconciliation, root-turn status checks, required-action handling, and bounded retries are implemented.

Claims the current documentation does not support

• The documentation does not support a claim that the Agents API is Zero Data Retention eligible.
• The documentation does not support a claim that self-hosting the sandbox makes Agents API sessions ZDR-eligible or provides additional regional residency.
• The documentation does not support a claim that data residency is available outside the United States for the Agents API.
• The documentation does not support a claim that restricted network access accepts wildcards, URL paths, protocols, ports, or partial domains.
• The documentation does not support a claim that an environment template preserves a running workspace.
• The documentation does not support a claim that session creation means the hosted environment is connected and ready.
• The documentation does not support a claim that closing an event stream cancels the running task.
• The documentation does not support a claim that agent.session.idle, stream closure, or a completed turn proves every tool succeeded.
• The documentation does not support a claim that each subagent receives a separate sandbox or filesystem.
• The documentation does not support a claim that deleting a published artifact also deletes the live workspace file.
• The documentation does not support transferring Responses API compaction ZDR assumptions to Agents API sessions.

Closing governance position

The safest way to approve an Agents API deployment is to make the hidden copies visible: session state, workspace files, published artifacts, external tool traffic, and application storage must each have an owner, a retention rule, and a failure procedure. The OpenAI documentation gives enough detail to build strong controls, but it also defines hard boundaries: United States residency only for the Agents API, no Agents API ZDR, exact-host restricted networking, non-configurable hosted sandbox inactivity expiry, immutable published artifacts, and environment-specific file behavior.

A production review should therefore ask one final question before launch: if a stream disconnects, a sandbox expires, an artifact is published, a tool fails, or a regulator asks where the data went, can the team answer from records rather than memory? If the answer is yes, the workflow has moved from an experimental agent script to an auditable system design.

Useful Links

• OpenAI Agents API overview
• OpenAI-hosted Agents API environments
• Self-hosted Agents API environments
• Agents API multi-agent guide
• OpenAI compaction guide
• OpenAI Your Data guide