OpenAI Agents API 沙箱边界：在不泄露密钥的前提下交付长时运行 Agent

OpenAI Agents API Sandbox Boundaries: Ship Long-Running Agents Without Shipping Your Secrets Ethan Mark 11 min read · Just now -- Listen Share Press enter or click to view image in full size Giving an agent a sandbox feels like a security decision. It is really a product-design decision with security consequences. The agent now has a place to run commands, change files, install packages, and leave work behind. That is exactly what makes a long-running agent useful — and exactly why a vague “safe environment” is not enough. OpenAI’s newly announced Agents API brings the managed Codex harness to developers, including long-session context management, subagents, and an OpenAI-hosted sandbox option. The temptation is to connect a repository, add a few environment variables, and call it production. The better move is to define what the agent may start with, what it may change, what it may request, and what must be reviewed by a person or a separate service. This guide is for engineering teams building coding, analysis, document, or operations agents. It shows how to make an agent useful without treating a sandbox as a tiny production server with a chatbot attached. The surprising failure mode: a sandbox becomes a side door Most teams do not deliberately grant an agent broad access. They accumulate it. A helpful test needs a package registry token. A deployment check needs a cloud credential. A support workflow needs a customer export. A debugging task needs network access. Soon the sandbox has a persistent filesystem, a powerful service account, outbound internet access, and a repository that contains more than the task requires. At that point, the container boundary is doing less work than people assume. It may isolate one process from another, but it does not decide whether a model should see a secret, whether generated code should use it, or whether an artifact is safe to publish. Those are application-policy choices. A sandbox limits where an agent works. A boundary design decides what the agent is allowed to accomplish. The OpenAI Agents SDK documentation makes this distinction explicit: a manifest defines a fresh workspace, while the outer runtime still owns approvals, tracing, handoffs, and resume state. That separation is a useful mental model even if you use the managed Agents API rather than the SDK directly. Press enter or click to view image in full size Start with a job contract, not a general-purpose workspace Before provisioning anything, write a one-page job contract for the agent. Do not start with its tools. Start with the completed outcome a reviewer should be able to verify. Goal: “Analyze the uploaded CSV and produce a draft anomaly report.” Inputs: the upload, a read-only metric dictionary, and approved helper scripts. Allowed effects: create files only under /workspace/output and make read-only calls to a named data API. Forbidden effects: email users, write to the warehouse, create cloud resources, or change source repositories. Evidence: source file hashes, commands run, tool calls, output hashes, and the unresolved assumptions. Exit: a bounded runtime, a cost ceiling, and a clear cancellation path. This may look like paperwork, but it fixes a common agent-design mistake: using instructions to compensate for permissions. “Never deploy” is an instruction. A deploy token that does not exist in the sandbox is a boundary. Use both, but do not confuse their roles. Design the workspace as an allowlist The fresh workspace should contain only the materials required to complete the named job. In OpenAI’s sandbox model, the manifest can define files, repositories, mounts, directories, and environment values. Treat that manifest like an API surface, not a convenience list. What a good sandbox manifest includes A useful default layout is deliberately boring: /workspace/input for immutable task files. /workspace/reference for short, curated rules and schemas. /workspace/tools for reviewed helper programs. /workspace/output for artifacts that may leave the sandbox. /workspace/scratch for temporary work that is not exported. Mount a narrow subdirectory, not an entire drive. Clone a specific repository ref, not the organization’s default branch. Provide a small data extract when a production database is unnecessary. The more unrelated material the agent can inspect, the harder it becomes to predict both its behavior and your exposure. Give the agent instructions that match the filesystem Instructions should name the work area and the verification command, then state what a successful finish looks like. They should not paste a huge internal handbook into the prompt. Put durable reference material in the workspace, make it discoverable, and point the agent to it. Task: repair the failing parser tests.Work only in /workspace/repo and write your final report to /workspace/output/report.md. Run `npm test -- parser` before finishing. Do not use network access or add dependencies. If the repair needs either, stop and write a request for review in the report. That is more reliable than “be careful.” It gives the agent a destination, a test, and a graceful way to surface a missing dependency rather than improvising around it. Keep secrets out of the model’s working room Environment variables are easy to inject and easy to forget. They are also visible to commands and generated programs running in the sandbox. If the task does not need a secret, do not mount it. If it needs an external action, prefer a narrow brokered tool over a general credential. For example, a billing-analysis agent might need “fetch invoice by ID,” not a cloud key with blanket access to the entire billing account. Your application can expose a server-side function that validates the ID, checks the user’s authorization, fetches the record, redacts fields, and returns a typed result. The sandbox receives the answer, not the master key. When a credential is truly necessary, make it short-lived, task-scoped, and auditable. Bind it to a single audience and a minimal action set. Give it an expiry shorter than the maximum agent run. Revoke it when the job is canceled. Never place a long-lived operator credential in a reusable snapshot. Think of secrets as a pull request: every new one needs a specific reason, an owner, a permitted action list, and an expiry. This is especially important for persistent sandboxes, where a harmless-looking credential can outlive the job that justified it. Press enter or click to view image in full size Separate network permission from code execution Code execution is often essential. Open internet access usually is not. A coding agent can format files, run unit tests, and build a local artifact without fetching arbitrary domains. When it does need the network, make the request explicit. Get Ethan Mark’s stories in your inbox Join Medium for free to get updates from this writer. Subscribe Subscribe Remember me for faster sign in A practical policy has three modes: Offline: default for code edits, analysis of supplied files, and reproducible tests. Allowlisted: access only to an approved package mirror, documentation host, or internal API. Reviewed egress: a human or policy service approves a narrow, time-limited destination for a named reason. Do not make the model decide this alone. Let the agent formulate a request — host, purpose, expected response shape, and duration — then let your policy layer decide. This makes requests reviewable and prevents a task from quietly becoming web research, package installation, or data transfer. Use snapshots as checkpoints, not as hidden memory Long-running work needs recovery. The current Agents SDK sandbox guides support saved state and snapshots, which can reconnect later work to a workspace or seed a fresh one. That is useful, but persistence changes your threat model. A snapshot should be a reviewed checkpoint with a purpose: “compiled documentation draft after source validation,” not “everything the agent happened to create.” Store the task ID, source revision, timestamp, artifact hashes, and policy version alongside it. Exclude tokens, temporary downloads, raw customer exports, browser data, and shell histories by default. For each resumed run, ask two questions: Is this still the same job? and Would we still grant these inputs now? If either answer is no, start a fresh sandbox from a new manifest. Resuming state because it is convenient is how a one-hour task turns into an untraceable durable workspace. Put an artifact gate between the sandbox and the real world Artifacts are the one thing an agent should be allowed to make freely. But “allowed to make” does not mean “allowed to publish.” Treat exports as candidates that need a gate. For a source-code agent, the gate might run tests, scan the diff, enforce a changed-file allowlist, and open a draft pull request. For a data agent, it might validate a JSON schema, check that no restricted fields appear, attach the query receipt, and route the result to a reviewer. For a document agent, it might run malware scanning, render a preview, and require an owner to click publish. const decision = await reviewArtifact({ taskId, path: "/workspace/output/report.json", checks: ["schema", "sensitive-data", "source-receipt"], publishTarget: "drafts-only" });if (decision.status !== "approved") { return { status: "needs_review", reasons: decision.reasons }; } The example is intentionally application-level pseudocode. The point is architectural: the sandbox writes to an output tray; another system decides whether that tray can cross a trust boundary. Do not give the same agent a direct publishing token just to avoid this step. Make each run explainable after it ends A good agent trace answers more than “did it finish?” It should tell an engineer what it received, which tools it used, which commands changed state, what it produced, and why it was permitted to do so. The managed harness can simplify orchestration, but it does not remove your responsibility to retain application-level evidence. Record the job contract, manifest version, model and harness version, tool requests and responses, approvals, artifact hashes, policy decisions, cancellation events, and final outcome. Avoid collecting raw chain-of-thought or copying secrets into logs. Event facts are usually enough: a tool was called with a redacted parameter set, a command exited with code 1, a reviewer approved artifact hash X. Those records create a feedback loop. You can identify where the agent asks for unnecessary permissions, which packages repeatedly cause network exceptions, and which artifact checks reject real work. That is how a sandbox policy gets less annoying over time without becoming less safe. A rollout plan that earns trust Start with work that is valuable but reversible: document extraction, report drafts, test failure triage, or patch proposals. Keep network access off. Give the sandbox synthetic or non-sensitive inputs. Export to drafts only. Run enough real tasks to learn what the agent actually needs. Then add one capability at a time. A package mirror for a specific build. A brokered read-only data lookup. A ticket-creation tool that produces drafts. Measure the approval rate, policy denials, retries, time to a useful artifact, and manual correction rate. If a capability does not produce a clear improvement, remove it. Only after this evidence should you consider a more persistent workspace, a wider data source, or a write action. Teams often reverse this order and end up with a broad prototype that is hard to audit. A narrow launch produces constraints that engineers can understand, test, and improve. The practical takeaway The Agents API can remove a lot of unglamorous harness work: session management, context compaction, tool coordination, and infrastructure choices. That is a genuine advantage. But it makes your own boundary decisions more important, not less. Give each agent a clear job. Materialize only the inputs it needs. Broker sensitive actions. Make network access exceptional. Snapshot deliberately. Gate artifacts before publishing. And retain evidence without turning your logs into another secret store. Do that, and a sandbox becomes a productive workspace rather than an accidental side door into your systems. A concrete first-week implementation checklist You do not need a mature platform team to begin safely. You need a small pilot that makes the boundary visible. Pick one agent job with a single owner and run it against a representative, non-sensitive task set. The goal in the first week is not full autonomy. It is to learn which inputs and actions actually produce a useful outcome. On day one, create the job contract and a fresh manifest. Include only one repository or a small fixture set. Make the output directory writable and make every other mounted source read-only. Set a modest run-time and token budget. Keep egress disabled. This baseline will feel restrictive, which is useful: each blocked step becomes a question about a real requirement rather than a hypothetical capability. On day two, watch three to five runs. Categorize every failure. Did the agent lack a library? Did its instructions omit a test command? Did it need a missing reference file? Did the task actually require an external service? Fix the narrowest cause. A reviewed package image or an internal helper tool is usually better than giving the sandbox broad installation or network access. On day three, build the artifact gate. Even a simple version is valuable: verify the artifact stays under the expected directory, inspect its file type, run the relevant test or schema check, and attach a short receipt. Send it to a draft location rather than a live target. The engineer reviewing it should not need to reconstruct the run from memory. By the end of the week, make a decision using evidence. If a permission repeatedly improves completed work and the review history is clean, promote it to an allowlisted capability. If it is rare, keep it as an approval request. If it is used once because the agent wandered, remove it. This is a much healthier model than granting a broad role upfront and hoping prompts provide the missing policy. What to measure during the pilot Track completion rate, reviewer acceptance rate, median time to a usable artifact, tool-denial count, policy-exception count, and the rate of changes humans must make after approval. A high completion rate with a low reviewer acceptance rate is not a win; it means the agent is fast at producing convincing drafts. Likewise, a perfect safety record with no completed tasks may mean the manifest is too thin. The useful target is a steady reduction in exceptions while accepted artifacts rise. These measures also prevent vendor comparisons from becoming theater. A managed harness, a self-hosted container, and a partner sandbox can all be valid choices. Compare them on the work you need to complete: startup time, image parity, data residency, lifecycle control, artifact review, and evidence quality. Do not choose an environment only because it makes the first demo shorter. Frequently asked questions What is an OpenAI Agents API sandbox? It is an execution environment an agent can use to work with files, run code, and produce artifacts. OpenAI offers a hosted option, while the broader Agents ecosystem also supports self-hosted and partner-managed environments. Is a sandbox enough to secure an AI agent? No. A sandbox isolates execution, but your application still controls which files, credentials, network paths, tools, approvals, and publishing actions the agent can use. Should an agent sandbox have production credentials? Usually no. Prefer a brokered, task-specific tool. If a credential is unavoidable, make it short-lived, narrowly scoped, auditable, and unavailable to future runs. Can a long-running agent reuse a sandbox? Yes, but reuse should be tied to a documented task and checkpoint. Revalidate the inputs and permissions before resuming; otherwise start a fresh workspace. How should agents publish code or reports? Write artifacts to a designated output directory, run automated checks, and send them to a human or policy gate. Use draft pull requests, draft documents, or review queues instead of direct publishing. When should an agent receive internet access? Only when the current task needs a named external destination. Default to no network, then use allowlists or reviewed, time-limited egress for package mirrors, documentation, or specific APIs.