Panduan Sandbox Native dan Manifest OpenAI Agents SDK

OpenAI merilis pembaruan penting Agents SDK pada 15 April 2026, dan petunjuknya terlihat dari baris instalasi di posting peluncurannya: pip install "openai-agents>=0.14.0" (OpenAI). Baris versi itu penting. Ini bukan template prompt baru atau wrapper function-calling lain. Ini adalah langkah OpenAI memindahkan pekerjaan file, pekerjaan shell, patching, siklus hidup sandbox, dan deskripsi workspace menjadi primitive di level SDK.

Bagi developer yang membangun agen coding, agen dokumen, agen pembersihan data, atau bot pemeliharaan repo, pergeseran desainnya sederhana: berhenti membuat setiap tim membangun ulang harness rapuh yang sama di sekitar Docker, direktori sementara, skema tool, staging file, dan logika retry. SDK kini memberi Anda harness native untuk model, eksekusi native sandbox, tool filesystem, MCP, AGENTS.md, akses shell, apply_patch, dan abstraksi Manifest untuk mendeskripsikan workspace portabel.

Perubahannya: dari tool call ke workspace sungguhan

Agents SDK awal sudah berguna untuk orkestrasi: agen, tool, handoff, guardrail, tracing. Pembaruan April menambahkan bentuk runtime yang selama ini kurang untuk agen yang perlu bekerja dengan file dalam jangka waktu lama.

OpenAI menggambarkan SDK yang diperbarui ini sebagai alat yang membantu developer membangun agen yang dapat menginspeksi file, menjalankan command, mengedit kode, dan mengerjakan tugas berjangka panjang di dalam lingkungan sandbox yang terkendali (OpenAI). Frasa “workspace terkendali” adalah kuncinya. Agen pengolah file yang serius membutuhkan lebih dari sekadar daftar tool. Ia membutuhkan direktori root, input yang di-mount, lokasi output, shell, permission, snapshot, dan cara untuk melanjutkan saat container mati.

Sebelum pembaruan ini, setup produksi tipikal tampak seperti ini:

• membuat workspace sementara
• menyalin file ke dalamnya
• mengekspos tool baca, tulis, shell, dan patch
• memvalidasi path secara manual
• memulai sandbox atau container
• mengumpulkan artifact
• melakukan snapshot state jika job berjalan lama
• menerjemahkan semua itu menjadi instruksi yang menghadap ke model

Glue code seperti itulah yang diam-diam membuat banyak proyek agen menjadi berantakan. SDK baru menjadikan sebagian besar hal tersebut sebagai konfigurasi kelas utama.

Posting peluncuran OpenAI mencantumkan dukungan bawaan untuk Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, dan Vercel sebagai penyedia sandbox, dengan jalur “bring your own sandbox” juga tersedia (OpenAI). Itu berarti tujuh penyedia hosted saat peluncuran, plus jalur pengembangan lokal.

Manifest adalah lapisan portabilitas

Abstraksi Manifest adalah bagian paling praktis dari rilis ini. Ia mendeskripsikan apa yang harus berisi di workspace sandbox sebelum model mulai bekerja.

Dalam dokumentasi Python, Sandbox Agents ditandai beta, membutuhkan Python 3.10 atau lebih tinggi, dan disajikan sebagai cara untuk memberi model workspace persisten tempat ia dapat mencari kumpulan dokumen, mengedit file, menjalankan command, menghasilkan artifact, dan melanjutkan dari state sandbox yang tersimpan (dokumentasi Python OpenAI Agents SDK).

Bentuk Python yang ringkas terlihat seperti ini:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

Bagian pentingnya bukan sintaksnya. Melainkan kontraknya. Manifest dapat mendeskripsikan file lokal, direktori, repo Git, file sintetis, environment variable, user, group, direktori output, dan mount penyimpanan remote. Dokumentasi JavaScript menyatakan bahwa path entry Manifest bersifat relatif terhadap workspace, tidak boleh absolut, dan tidak boleh keluar dari workspace dengan .., yang persis jenis batasan membosankan yang sebaiknya ditegakkan oleh runtime, bukan harus diingat di setiap prompt (dokumentasi JS OpenAI Agents SDK).

Capability: shell, filesystem, skill, memory, compaction

Sebuah SandboxAgent bukan sekadar agen biasa dengan folder sementara. Ia membawa capability khusus sandbox.

Dokumentasi konsep JS mencantumkan capability bawaan termasuk shell(), filesystem(), skills(), memory(), dan compaction() (dokumentasi JS OpenAI Agents SDK). Default penting di sini: dokumentasi menyatakan bahwa Capabilities.default() mencakup filesystem, shell, dan compaction. Artinya loop coding-agent yang umum tidak lagi berupa tumpukan definisi tool khusus yang dibuat sendiri-sendiri.

Capability filesystem mengekspos edit file bergaya patch. Capability shell mengekspos eksekusi command di dalam sesi sandbox. Skill memungkinkan Anda mengungkapkan instruksi atau prosedur khusus secara progresif. Memory dan compaction membantu run yang lebih panjang mempertahankan state yang berguna tanpa memasukkan setiap token sebelumnya kembali ke turn berikutnya.

Ini sesuai dengan cara kerja coding agent yang kuat. Mereka menginspeksi. Mereka menjalankan command. Mereka mengedit file. Mereka menjalankan command yang lebih kecil. Mereka menginspeksi diff. Mereka merangkum apa yang berubah. Jika harness Anda memperlakukan setiap langkah sebagai API call yang tidak saling terkait, model menghabiskan terlalu banyak perhatian untuk merekonstruksi dunianya. Sesi sandbox memberi model tempat untuk berpijak.

AGENTS.md juga cocok secara alami dengan model ini. Situs terbuka AGENTS.md mendeskripsikannya sebagai format Markdown untuk memandu coding agent dan mengatakan bahwa format ini digunakan oleh lebih dari 60.000 proyek open-source (AGENTS.md). File itu sebaiknya memuat command build, instruksi test, aturan style, dan peringatan spesifik repo. Di dunia sandbox, AGENTS.md menjadi konteks operasi lokal workspace, bukan prompt raksasa yang ditempelkan ke setiap tugas.

Python lebih dulu, TypeScript menyusul

Saat peluncuran, ini lebih dulu hadir untuk Python. TechCrunch melaporkan pada 15 April bahwa harness dan capability sandbox baru ini diluncurkan lebih dulu di Python, dengan dukungan TypeScript direncanakan kemudian (TechCrunch). PyPI menguatkan tanggal tersebut: versi openai-agents 0.14.0 dan 0.14.1 diunggah pada 15 April 2026 (PyPI).

Per 16 Juni 2026, gambaran praktisnya lebih seimbang. Dokumentasi JS resmi kini mencakup Sandbox Agents beta, membutuhkan Node.js 22 atau lebih tinggi, dan menampilkan Manifest, SandboxAgent, UnixLocalSandboxClient, dukungan Docker, serta client penyedia hosted melalui @openai/agents-extensions (quickstart JS OpenAI Agents SDK). Dokumentasi JS juga mencatat bahwa Deno dan Bun dapat bekerja jika resolusi package dan API runtime kompatibel.

Area	Python	TypeScript / JavaScript
Status peluncuran pada 15 Apr	Jalur pertama yang didukung	Direncanakan kemudian
Dokumentasi sandbox saat ini	Beta, Python 3.10+	Beta, Node.js 22+
Sandbox lokal	UnixLocalSandboxClient	UnixLocalSandboxClient
Sandbox Docker	openai-agents[docker]	DockerSandboxClient
Penyedia hosted	Didukung melalui integrasi SDK	Jalur penyedia @openai/agents-extensions

Itu bukan berarti kedua ekosistem identik. Python adalah permukaan peluncuran awal, dan banyak contoh masih lebih dulu muncul di sana. TypeScript kini memiliki permukaan resmi yang cukup untuk membuat prototipe agen sandbox nyata, tetapi detail penyedia hosted, perilaku PTY, mount, dan dukungan siklus hidup tetap perlu dibaca secara cermat untuk tiap backend.

Cara saya menyusun agen pengolah file sekarang

Kesalahannya adalah memperlakukan sandbox sebagai kotak keamanan ajaib. Ia adalah batas runtime, bukan spesifikasi produk. Anda tetap harus merancang workspace.

Struktur yang bersih terlihat seperti ini:

• repo/: working tree atau repository yang di-mount
• task.md: spesifikasi tugas yang harus dibaca model terlebih dahulu
• inputs/: dokumen, dataset, screenshot, atau log read-only
• output/: satu-satunya tempat artifact final yang dihasilkan boleh diletakkan
• AGENTS.md: instruksi build, test, style, dan safety
• user sandbox: identitas non-root jika backend mendukungnya
• env Manifest: konfigurasi non-rahasia yang dipersist secara default, secret ditandai ephemeral

Manifest harus mendeskripsikan input. Instruksi agen harus mendeskripsikan workflow. Prompt pengguna harus mendeskripsikan tugas sekali jalan. Pisahkan ketiganya. Dokumentasi JS secara eksplisit memperingatkan agar tidak menjejalkan materi referensi panjang ke dalam instructions jika materi itu seharusnya berada di Manifest (dokumentasi JS OpenAI Agents SDK).

Untuk produksi, pilih backend berdasarkan blast radius, bukan jalur demo. Unix-local tidak masalah untuk pengembangan. Docker adalah default yang lebih baik saat Anda membutuhkan repeatability. Penyedia hosted masuk akal saat Anda membutuhkan isolasi bersih per run, eksekusi remote, scaling, atau perilaku snapshot spesifik penyedia. Dokumentasi client JS menyatakan bahwa dukungan penyedia hosted bervariasi dan developer harus memeriksa dokumentasi penyedia untuk environment variable, port, PTY, snapshot, dan perilaku cleanup (client JS OpenAI Agents SDK).

Membaca ekosistemnya

Pembaruan ini penting karena menstandarkan bentuk agen pengolah file. Industri sudah berkumpul pada beberapa primitive: MCP untuk tool eksternal, AGENTS.md untuk instruksi repo, shell untuk inspeksi nyata, patching untuk edit yang bisa di-review, dan sandbox untuk containment. OpenAI Agents SDK kini mengemas potongan-potongan itu menjadi runtime yang benar-benar dapat dikomposisikan oleh developer.

Sisi tajamnya tetap permission. Agen yang di-sandbox dengan jaringan luas, mount yang dapat ditulis, kredensial berumur panjang, dan instruksi yang samar tetap dapat menimbulkan kerusakan. Manifest membantu karena membuat input dan grant workspace terlihat. Ia tidak menghapus kebutuhan akan kebijakan approval, kebersihan secret, dependency pinning, dan review artifact.

Use case terbaik hari ini bukan “agen melakukan segalanya.” Yang lebih sempit dan lebih bernilai adalah: beri model workspace berbatas, file tugas yang jelas, instruksi lokal repo, tool shell dan patch, serta satu jalur verifikasi eksplisit. Biarkan ia bekerja seperti engineer junior di lingkungan sekali pakai. Lalu inspeksi diff-nya.

Itu abstraksi yang jauh lebih sehat daripada membuat lagi setengah-sandbox sendiri di sekitar chat loop.

Pembaca yang ingin mencoba model-model ini secara langsung dapat memanggilnya melalui onehop dengan API yang kompatibel dengan OpenAI cukup dengan mengubah satu base_url. Ini lebih murah daripada pihak pertama, dan akun baru mendapat kredit gratis $10 tanpa perlu kartu: panggil Claude dan model lain di onehop, atau daftar untuk kredit gratis $10.