OpenAI Agents SDK: Cara Menjalankan Agent di Modal Sandboxes

Alur kerja sandbox Agents terbaru dari OpenAI mengubah cara eksekusi agent disusun. Alih-alih menempatkan agent, file, tool, dan runtime dalam satu loop yang berantakan, framework ini memisahkan lapisan orkestrasi tepercaya dari lingkungan eksekusi.

Artinya, aplikasi Anda dapat menangani logika agent, panggilan model, dan pengambilan keputusan, sementara pekerjaan sebenarnya terjadi di dalam workspace sandboxed dengan akses ke file, perintah, dan output yang dihasilkan.

Pengaturan ini sangat berguna saat agent Anda perlu melakukan lebih dari sekadar merespons berdasarkan konteks prompt saja. Misalnya, agent dapat memeriksa sebuah proyek, menulis atau memodifikasi file, menjalankan kode, menguji output, dan menghasilkan artefak dalam lingkungan yang terkontrol.

Dalam panduan ini, kita akan mempelajari cara menggabungkan framework OpenAI Agents dengan Modal Sandboxes untuk membangun aplikasi agentic yang praktis. Agent akan mampu berjalan di dalam lingkungan Modal yang terisolasi, mengeksekusi perintah dengan aman, bekerja dengan file, dan mengembalikan output yang berguna kembali ke aplikasi utama.

Untuk pengantar tanpa menggunakan sandbox, saya juga merekomendasikan membaca Tutorial OpenAI Agents SDK kami. 

Apa yang Baru di OpenAI Agents SDK?

OpenAI Agents SDK yang baru menyediakan cara yang lebih rapi untuk membangun agent yang dapat bekerja dengan file, tool, dan lingkungan eksekusi nyata. Alih-alih menyimpan semuanya dalam satu loop prompt, SDK kini memisahkan lapisan orkestrasi agent dari sandbox tempat pekerjaan berlangsung.

Pembaruan utama meliputi:

• Dukungan sandbox native untuk menjalankan agent di lingkungan terisolasi
• Manifest untuk mendefinisikan file, folder, dan output yang dapat diakses agent
• SandboxAgent untuk menghubungkan agent dengan workspace sandboxed
• SandboxRunConfig untuk mengontrol di mana dan bagaimana run sandbox berlangsung
• Tool bergaya Codex untuk pengeditan file, perintah shell, dan inspeksi proyek
• Dukungan MCP agar agent dapat terhubung dengan tool dan layanan eksternal
• Skills dan dukungan AGENTS.md untuk memberi agent instruksi proyek yang lebih jelas
• Dukungan untuk banyak penyedia sandbox, termasuk Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop, dan Vercel

Secara bersama-sama, pembaruan ini memudahkan pembuatan aplikasi agentic yang dapat memeriksa proyek, menjalankan kode, mengedit file, dan mengembalikan output yang dihasilkan dari workspace terkontrol.

1. Menyiapkan Proyek

Dalam proyek demo ini, kita akan membangun contoh triase tiket dukungan kecil menggunakan OpenAI Agents SDK dan Modal Sandboxes. Aplikasi akan membuat workspace sandboxed, menambahkan beberapa file proyek ke dalamnya, lalu meminta agent GPT-5.4-mini untuk memeriksa file-file tersebut sebelum menjawab.

Mulailah dengan menginstal paket yang diperlukan di lingkungan Anda:

pip install "openai-agents[modal]" modal

Sebelum menjalankan proyek, Anda memerlukan dua akun:

• Akun OpenAI: Buat akun di OpenAI Platform dan tambahkan kredit API menggunakan kartu kredit. Pastikan akun Anda terverifikasi untuk mengakses model terbaru yang didukung.
• Akun Modal: Daftar ke Modal. Paket gratis menyertakan kredit bulanan, cukup untuk menguji panduan ini.

Selanjutnya, tambahkan kunci API OpenAI Anda ke lingkungan lokal.

• Di macOS atau Linux: export OPENAI_API_KEY="your_openai_api_key"
• Di Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Lalu autentikasi Modal secara lokal:

modal setup

Ini akan membuka jendela browser dan meminta Anda masuk ke Modal. Setelah masuk, setujui permintaan pembuatan token. Modal akan otomatis menambahkan kredensial ke lingkungan lokal Anda.

Setelah semuanya siap, Anda akan melihat pesan sukses di terminal yang mengonfirmasi autentikasi Modal telah selesai.

2. Mendefinisikan Workspace Sandbox

Selanjutnya, buat file Python seperti main.py dan tambahkan impor yang diperlukan. Impor ini membawa OpenAI Agents SDK, kelas konfigurasi sandbox, dan klien sandbox Modal. 

import asyncio

from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions

Sekarang kita perlu mendefinisikan workspace sandbox. Dalam contoh ini, workspace mencakup proyek triase tiket dukungan kecil dengan README.md, sebuah file aplikasi, dan daftar periksa rilis.

manifest = Manifest(
    entries={
        "README.md": File(
            content=(
                b"# Support Ticket Triage\n\n"
                b"Small service that labels customer tickets by urgency and team.\n"
            )
        ),
        "src/app.py": File(
            content=(
                b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                b"    return {\n"
                b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                b"    }\n"
            )
        ),
        "docs/release-checks.md": File(
            content=(
                b"# Release Checks\n\n"
                b"- Confirm routing rules match the current support escalation policy.\n"
            )
        ),
    }
)

Manifest memberi tahu agent file apa saja yang ada di dalam sandbox. Ini memberikan agent struktur proyek nyata untuk diperiksa, diedit, dan dianalisis, alih-alih hanya mengandalkan teks di dalam prompt.

Dalam kasus ini, agent akan dapat meninjau logika perutean tiket dukungan, memeriksa dokumentasi, dan melakukan perubahan di dalam workspace sandboxed.

3. Membuat Sandbox Agent

Setelah workspace didefinisikan, buat agent yang didukung sandbox. SandboxAgent dirancang untuk bekerja dengan workspace nyata, yang berarti ia dapat memeriksa file, memahami struktur proyek, dan merespons berdasarkan apa yang ada di dalam sandbox.

agent = SandboxAgent(
    name="Modal Sandbox Assistant",
    model="gpt-5.4-mini",
    instructions=(
        "You are a coding assistant reviewing a small production service. "
        "Inspect the sandbox workspace before answering. "
        "Keep the answer short and practical."
    ),
    default_manifest=manifest,
    model_settings=ModelSettings(tool_choice="required"),
)

Di sini, kita menamai agent Modal Sandbox Assistant dan menggunakan model gpt-5.4-mini untuk respons yang lebih cepat. Instruksi memberi tahu agent untuk memeriksa workspace sandbox sebelum menjawab, yang penting ketika respons bergantung pada file nyata di dalam proyek.

Pengaturan default_manifest=manifest menghubungkan agent ke workspace yang kita buat sebelumnya. Pengaturan tool_choice="required" mendorong agent menggunakan tool sandbox yang tersedia alih-alih menjawab hanya dari ingatan atau konteks prompt.

4. Membuat Klien Modal Sandbox

Selanjutnya, buat klien Modal sandbox. Ini adalah koneksi antara alur kerja OpenAI Agents dan sandbox Modal, tempat eksekusi file dan perintah sebenarnya akan terjadi.

client = ModalSandboxClient()
options = ModalSandboxClientOptions(
    app_name="openai-agents-modal-demo",
    workspace_persistence="tar",
)

ModalSandboxClient() memberi tahu agent untuk menggunakan Modal sebagai penyedia sandbox. Ini berarti agent dapat berjalan di lingkungan Modal yang terisolasi alih-alih berjalan langsung di mesin lokal Anda.

Kelas ModalSandboxClientOptions mengontrol bagaimana sandbox Modal dikonfigurasi. Di sini, app_name memberi nama yang jelas untuk aplikasi Modal, sementara workspace_persistence="tar" memberi tahu Modal cara mengemas dan mempertahankan file workspace selama run.

5. Memulai Sesi Sandbox

Sekarang klien dan opsinya sudah siap, buat sandbox dari manifest dan mulai sesi. 

sandbox = await client.create(
    manifest=manifest,
    options=options,
)

await sandbox.start()

Panggilan client.create() membuat sandbox Modal baru menggunakan file yang kita definisikan di Manifest. Artinya, sandbox dimulai dengan struktur proyek yang sama, termasuk README.md, src/app.py, dan docs/release-checks.md.

Lalu, await sandbox.start() memulai sesi sandbox. Pada tahap ini, Anda memiliki workspace terisolasi yang aktif di Modal, siap untuk agent memeriksa file, menjalankan perintah, dan bekerja dengan proyek.

6. Menjalankan Agent di Sandbox

Setelah sandbox aktif, jalankan agent terhadapnya dengan meneruskan sesi sandbox langsung melalui SandboxRunConfig. Ini memberi tahu OpenAI Agents SDK bahwa agent harus menggunakan workspace sandbox Modal selama run. 

result = await Runner.run(
    agent,
    (
        "Explain what this service does and name one production check "
        "before release. Keep it under 3 sentences."
    ),
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox),
        workflow_name="Modal sandbox example",
    ),
)

print(result.final_output)

Di sinilah semuanya berpadu. Model menangani penalaran, sementara sandbox memberinya akses ke file workspace nyata.

Dalam contoh ini, agent dapat memeriksa proyek triase tiket dukungan, memahami apa yang dilakukan layanan tersebut, memeriksa catatan rilis, dan mengembalikan jawaban singkat berdasarkan file di dalam sandbox Modal.

7. Membersihkan Sandbox

Setelah run agent selesai, hapus sandbox agar Anda tidak meninggalkan sesi yang tidak terpakai berjalan di Modal.

await client.aclose(sandbox)

Ini menghapus sesi sandbox setelah pekerjaan selesai. Ini adalah kebiasaan yang baik karena sesi sandbox dapat menggunakan sumber daya komputasi selama aktif.

Dalam proyek nyata, Anda sebaiknya menempatkan ini di dalam blok finally. Dengan begitu, pembersihan tetap berjalan meskipun panggilan agent gagal atau skrip mengalami error.

8. Contoh Kode Lengkap

Berikut skrip lengkap dalam satu tempat. Skrip ini membuat workspace, memulai sandbox Modal, menjalankan agent di dalamnya, mencetak output akhir, lalu membersihkan sesi sandbox. 

import asyncio

from agents import ModelSettings, Runner
from agents.extensions.sandbox import ModalSandboxClient, ModalSandboxClientOptions
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File


async def main():
    manifest = Manifest(
        entries={
            "README.md": File(
                content=(
                    b"# Support Ticket Triage\n\n"
                    b"Small service that labels customer tickets by urgency and team.\n"
                )
            ),
            "src/app.py": File(
                content=(
                    b"def route_ticket(subject: str, customer_tier: str) -> dict:\n"
                    b"    urgent = customer_tier == \"enterprise\" or \"outage\" in subject.lower()\n"
                    b"    return {\n"
                    b"        \"priority\": \"high\" if urgent else \"normal\",\n"
                    b"        \"team\": \"support-ops\" if urgent else \"customer-care\",\n"
                    b"    }\n"
                )
            ),
            "docs/release-checks.md": File(
                content=(
                    b"# Release Checks\n\n"
                    b"- Confirm routing rules match the current support escalation policy.\n"
                )
            ),
        }
    )

    agent = SandboxAgent(
        name="Modal Sandbox Assistant",
        model="gpt-5.4-mini",
        instructions=(
            "You are a coding assistant reviewing a small production service. "
            "Inspect the sandbox workspace before answering. "
            "Keep the answer short and practical."
        ),
        default_manifest=manifest,
        model_settings=ModelSettings(tool_choice="required"),
    )

    client = ModalSandboxClient()
    options = ModalSandboxClientOptions(
        app_name="openai-agents-modal-demo",
        workspace_persistence="tar",
    )

    sandbox = await client.create(
        manifest=manifest,
        options=options,
    )

    await sandbox.start()

    try:
        result = await Runner.run(
            agent,
            (
                "Explain what this service does and name one production check "
                "before release. Keep it under 3 sentences."
            ),
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=sandbox),
                workflow_name="Modal sandbox example",
            ),
        )

        print(result.final_output)

    finally:
        await sandbox.aclose()

if __name__ == "__main__":
    asyncio.run(main())

Skrip ini mengikuti struktur sandbox OpenAI saat ini dan menggunakan Modal sebagai backend eksekusi. Logika agent tetap berada di aplikasi Python Anda, sementara workspace sebenarnya berjalan di dalam sandbox Modal.

Blok finally penting karena menutup dan menghapus sandbox meskipun run agent gagal. Ini membantu menjaga lingkungan Modal Anda tetap bersih dan menghindari meninggalkan sesi tidak terpakai.

9. Menguji Aplikasi Secara Lokal

Setelah skrip siap, jalankan secara lokal dari terminal di folder yang sama tempat main.py disimpan:

python main.py

Jika semuanya dikonfigurasi dengan benar, skrip akan membuat sandbox Modal, memuat manifest ke dalamnya, menjalankan agent OpenAI terhadap workspace, mencetak respons, lalu membersihkan sandbox.

Anda akan melihat output serupa ini:

This service triages customer support tickets by assigning urgency and routing them to the right team. One production check before release is to confirm the routing rules still match the current support escalation policy.

Run mungkin memerlukan beberapa detik untuk selesai. Saat berjalan, buka dasbor Modal Anda, klik aplikasi openai-agents-modal-demo, dan periksa log. Ini cara yang berguna untuk memastikan sandbox dibuat, dimulai, digunakan oleh agent, dan dibersihkan dengan sukses.

10. Membuat Aplikasi Web Interaktif 

Skrip pertama bersifat statis, artinya kita hanya bisa mengirim satu permintaan, mendapat satu respons, lalu berhenti. Agar proyek lebih mudah digunakan, kita bisa mengubahnya menjadi aplikasi web interaktif dengan menggunakan Gradio. Ini memungkinkan kita mengobrol dengan agent sandbox, mengajukan pertanyaan lanjutan, membuat atau mengedit file, dan menjalankan pengujian dari antarmuka browser yang sederhana.

Pertama, instal versi terbaru Gradio:

pip install gradio

Lalu buat file baru bernama app.py dan salin kode aplikasi Gradio (OpenAI-Agents-in-Modal/app.py) ke dalamnya. Aplikasi ini menggunakan pengaturan OpenAI Agents dan Modal Sandbox yang sama, tetapi membungkusnya dalam antarmuka chat. Kode juga menggunakan kembali sesi sandbox jika memungkinkan, sehingga setiap pesan tidak perlu membuat sandbox baru dari awal.

Jalankan aplikasi dengan:

python app.py

Anda akan melihat URL lokal di terminal:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set share=True in launch().

Buka URL lokal tersebut di browser untuk menggunakan aplikasi chat. Anda dapat meminta agent memeriksa proyek, menjelaskan apa yang dilakukan layanan, membuat file helper baru, mengedit file yang ada, atau menjalankan pengujian di dalam sandbox Modal.

Sebagai contoh, saya pertama-tama memintanya menjelaskan apa yang dilakukan layanan proyek, dan dalam beberapa detik, agent mengembalikan respons terperinci berdasarkan file sandbox.

Kemudian saya meminta agent membuat file helper perutean baru. Permintaan ini memakan waktu sedikit lebih lama karena agent harus memodifikasi workspace sandbox, menambahkan pengujian, dan menjalankan test suite.

Agent membuat src/routing_rules.py, menambahkan file uji baru di tests/test_routing_rules.py, dan memverifikasi perubahan dengan pytest. Semua 6 pengujian lolos, mengonfirmasi bahwa helper baru berfungsi dengan benar dan logika perutean tiket yang ada tetap utuh.

Secara garis besar, aplikasi Gradio ini memberi Anda frontend sederhana untuk bekerja dengan agent OpenAI berbasis Modal. Pengguna mengirim pesan melalui browser, aplikasi meneruskannya ke SandboxAgent, agent bekerja di dalam sandbox Modal, dan respons akhir ditampilkan kembali di antarmuka chat.

Pemikiran Akhir

OpenAI Agents dengan Modal Sandboxes memberi kita cara yang rapi untuk membangun aplikasi agentic yang dapat bekerja dengan file nyata, menjalankan perintah, dan mengembalikan output yang berguna dari lingkungan terisolasi. 

Proses penyiapan untuk Modal berjalan mulus, dan pembuatan sandbox itu sendiri cukup langsung. Setelah semuanya terhubung, agent mampu memeriksa proyek, membuat file helper perutean baru, menambahkan pengujian, dan mengonfirmasi bahwa semua 6 pengujian lolos.

Meski begitu, membangun aplikasi interaktif dan mengonfigurasi model memerlukan lebih banyak pekerjaan daripada yang diperkirakan. Langkah pembuatan file dan pengujian juga memakan waktu lebih lama karena sandbox Modal sesekali mengalami timeout. Saya harus meningkatkan timeout sandbox dari 300 detik menjadi 600 detik agar agent memiliki cukup waktu untuk menyelesaikan alur kerja penuh.

Titik lemah lain adalah logging dan visibilitas. Saat menunggu agent selesai, tidak selalu jelas apa yang dilakukan Agents SDK di latar belakang. Bahkan log Modal pun tidak selalu menunjukkan detail yang cukup untuk memahami apakah agent sedang memeriksa file, mengedit kode, atau menjalankan pengujian. 

Ke depan, akan sangat membantu jika ada log agent yang lebih verbose, mirip dengan saat bekerja dengan tool seperti Claude Code, di mana Anda dapat mengikuti setiap langkah dengan lebih jelas.

Secara keseluruhan, ini adalah alur kerja yang kuat untuk membangun aplikasi agent bersandbox, terutama jika agent Anda perlu bekerja dengan file, kode, dan output yang dihasilkan. Anda dapat menemukan proyek lengkapnya di GitHub, mengkloningnya secara lokal, dan menjalankannya sendiri: kingabzpro/OpenAI-Agents-in-Modal.

Jika Anda ingin mempelajari seluk-beluk membangun sistem AI tingkat lanjut, saya merekomendasikan mengikuti kursus Building Scalable Agentic Systems kami.