OpenAI Agents SDK: Modal Sandboxes'ta Ajanlar Nasıl Çalıştırılır

OpenAI’nin daha yeni Agents sandbox iş akışı, ajan yürütmenin yapısını değiştiriyor. Ajanı, dosyaları, araçları ve çalışma zamanını tek bir karmaşık döngüde tutmak yerine, çerçeve güvenilir orkestrasyon katmanını yürütme ortamından ayırıyor.

Bu, uygulamanızın ajan mantığını, model çağrılarını ve karar verme sürecini yönetebileceği, asıl işin ise dosyalara, komutlara ve üretilen çıktılara erişimi olan izole bir sandbox çalışma alanında gerçekleşeceği anlamına gelir.

Bu kurulum, ajanınızın yalnızca istem bağlamına yanıt vermekten fazlasını yapması gerektiğinde özellikle kullanışlıdır. Örneğin bir projeyi inceleyebilir, dosyalar yazabilir veya değiştirebilir, kod çalıştırabilir, çıktıları test edebilir ve denetimli bir ortamda yapıtlar üretebilir.

Bu kılavuzda, pratik bir ajan uygulaması oluşturmak için OpenAI Agents çerçevesini Modal Sandboxes ile nasıl birleştireceğimizi öğreneceğiz. Ajan izole bir Modal ortamında çalışabilecek, komutları güvenle yürütebilecek, dosyalarla çalışabilecek ve ana uygulamaya faydalı çıktılar geri döndürebilecek.

Sandbox kullanmadan bir giriş için, ayrıca OpenAI Agents SDK Eğitimi yazımızı okumanızı öneririm. 

OpenAI Agents SDK’da Neler Yeni?

Yeni OpenAI Agents SDK, gerçek dosyalar, araçlar ve yürütme ortamlarıyla çalışabilen ajanlar oluşturmak için daha temiz bir yol sunuyor. Her şeyi tek bir istem döngüsünde tutmak yerine, SDK artık ajan orkestrasyon katmanını işlerin gerçekleştiği sandbox’tan ayırıyor.

Öne çıkan güncellemeler şunları içerir:

• Yerel sandbox desteği: Ajanları izole ortamlarda çalıştırma
• Manifest: Ajanın erişebileceği dosyaları, klasörleri ve çıktıları tanımlama
• SandboxAgent: Ajanı sandbox’lanmış bir çalışma alanına bağlama
• SandboxRunConfig: Sandbox çalıştırmasının nerede ve nasıl gerçekleşeceğini kontrol etme
• Codex tarzı araçlar: Dosya düzenleme, kabuk komutları ve proje inceleme
• MCP desteği: Ajanların harici araç ve hizmetlere bağlanmasını sağlama
• Skills ve AGENTS.md desteği: Ajanlara daha net proje talimatları verme
• Birden çok sandbox sağlayıcı desteği: Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop ve Vercel dahil

Birlikte, bu güncellemeler proje inceleyebilen, kod çalıştırabilen, dosya düzenleyebilen ve denetimli bir çalışma alanından üretilen çıktıları döndürebilen ajanik uygulamaları geliştirmeyi kolaylaştırır.

1. Projenin Kurulumu

Bu demo projede, OpenAI Agents SDK ve Modal Sandboxes kullanarak küçük bir destek bileti önceliklendirme örneği oluşturacağız. Uygulama bir sandbox çalışma alanı oluşturacak, içine birkaç proje dosyası ekleyecek ve ardından yanıtlamadan önce bu dosyaları incelemesi için bir GPT-5.4-mini ajanına görev verecek.

Gerekli paketleri ortamınıza kurarak başlayın:

pip install "openai-agents[modal]" modal

Projeyi çalıştırmadan önce iki hesaba ihtiyacınız var:

• OpenAI hesabı: OpenAI Platformunda bir hesap oluşturun ve kredi kartı ile API kredisi ekleyin. En son desteklenen modellere erişmek için hesabınızın doğrulanmış olduğundan emin olun.
• Modal hesabı: Modal’a kaydolun. Ücretsiz plan, bu kılavuzu test etmek için yeterli aylık kredi içerir.

Ardından OpenAI API anahtarınızı yerel ortamınıza ekleyin.

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

Sonra Modal’ı yerelde kimlik doğrulayın:

modal setup

Bu, bir tarayıcı penceresi açacak ve sizden Modal’a giriş yapmanızı isteyecektir. Giriş yaptıktan sonra, belirteç oluşturma isteğini onaylayın. Modal kimlik bilgilerini otomatik olarak yerel ortamınıza ekleyecektir.

Her şey kurulduktan sonra, terminalinizde Modal kimlik doğrulamasının tamamlandığını onaylayan bir başarı mesajı görmelisiniz.

2. Sandbox Çalışma Alanını Tanımlama

Sonraki adımda, main.py gibi bir Python dosyası oluşturun ve gerekli içe aktarmaları ekleyin. Bu içe aktarmalar OpenAI Agents SDK’yı, sandbox yapılandırma sınıflarını ve Modal sandbox istemcisini getirir. 

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

Şimdi sandbox çalışma alanını tanımlamamız gerekiyor. Bu örnekte çalışma alanı, bir README.md, bir uygulama dosyası ve bir sürüm kontrol listesi içeren küçük bir destek bileti önceliklendirme projesini kapsar.

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, ajanına sandbox içinde hangi dosyaların bulunduğunu söyler. Bu, ajana yalnızca istemdeki metne güvenmek yerine inceleyebileceği, düzenleyebileceği ve üzerinde mantık yürütebileceği gerçek bir proje yapısı sunar.

Bu durumda, ajan destek bileti yönlendirme mantığını gözden geçirebilecek, dokümantasyonu kontrol edebilecek ve sandbox’lanmış çalışma alanında değişiklikler yapabilecektir.

3. Sandbox Ajanı Oluşturma

Çalışma alanı tanımlandıktan sonra, sandbox destekli ajanı oluşturun. Bir SandboxAgent gerçek bir çalışma alanıyla çalışmak üzere tasarlanmıştır; bu da dosyaları inceleyebileceği, proje yapısını anlayabileceği ve sandbox içinde bulunanlara dayanarak yanıt verebileceği anlamına gelir.

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"),
)

Burada ajana Modal Sandbox Assistant adını veriyor ve daha hızlı yanıtlar için gpt-5.4-mini modelini kullanıyoruz. Talimatlar, yanıtlamadan önce sandbox çalışma alanını incelemesini söylüyor; bu, yanıtın projedeki gerçek dosyalara bağlı olduğu durumlarda önemlidir.

default_manifest=manifest ayarı ajanı daha önce oluşturduğumuz çalışma alanına bağlar. tool_choice="required" ayarı ise ajanın yalnızca hafızadan veya istem bağlamından yanıt vermek yerine mevcut sandbox araçlarını kullanmasını teşvik eder.

4. Modal Sandbox İstemcisini Oluşturma

Sonra Modal sandbox istemcisini oluşturun. Bu, OpenAI Agents iş akışı ile asıl dosya ve komut yürütmenin gerçekleşeceği Modal sandbox arasındaki bağlantıdır.

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

ModalSandboxClient(), ajana sandbox sağlayıcısı olarak Modal’ı kullanmasını söyler. Bu, ajanın doğrudan yerel makinenizde çalışmak yerine izole bir Modal ortamında çalışabileceği anlamına gelir.

ModalSandboxClientOptions Modal sandbox’ın nasıl yapılandırıldığını kontrol eder. Burada, app_name Modal uygulamasına net bir ad verirken, workspace_persistence="tar" Modal’a çalışma alanı dosyalarının çalışma sırasında nasıl paketleneceğini ve kalıcı hale getirileceğini söyler.

5. Sandbox Oturumunu Başlatma

İstemci ve seçenekler hazır olduğuna göre, manifestten sandbox’ı oluşturun ve oturumu başlatın. 

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

await sandbox.start()

client.create() çağrısı, Manifestte tanımladığımız dosyaları kullanarak yeni bir Modal sandbox oluşturur. Bu, sandbox’ın README.md, src/app.py ve docs/release-checks.md dahil aynı proje yapısıyla başladığı anlamına gelir.

Ardından, await sandbox.start() sandbox oturumunu başlatır. Bu noktada Modal üzerinde çalışan, ajanın dosyaları incelemesi, komutları çalıştırması ve projeyle çalışması için hazır canlı bir izole çalışma alanınız vardır.

6. Ajanı Sandbox’ta Çalıştırma

Sandbox etkinleştirildikten sonra, canlı sandbox oturumunu SandboxRunConfig üzerinden geçirerek ajanı ona karşı çalıştırın. Bu, OpenAI Agents SDK’ya, çalıştırma sırasında ajanın Modal sandbox çalışma alanını kullanması gerektiğini söyler. 

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)

Her şeyin bir araya geldiği yer burasıdır. Model akıl yürütmeyi yönetir; sandbox ise gerçek çalışma alanı dosyalarına erişim sağlar.

Bu örnekte, ajan destek bileti önceliklendirme projesini inceleyebilir, hizmetin ne yaptığını anlayabilir, sürüm notlarını kontrol edebilir ve Modal sandbox içindeki dosyalara dayanarak kısa bir yanıt döndürebilir.

7. Sandbox’ı Temizleme

Ajan çalışması tamamlandıktan sonra, Modal’da kullanılmayan oturumlar bırakmamak için sandbox’ı silin.

await client.aclose(sandbox)

Bu, iş tamamlandıktan sonra sandbox oturumunu kaldırır. İyi bir alışkanlıktır; çünkü sandbox oturumları etkin oldukları sürece hesaplama kaynaklarını kullanabilir.

Gerçek bir projede, bunu bir finally bloğunun içine yerleştirmelisiniz. Böylece, ajan çağrısı başarısız olsa veya betik bir hataya çarpsa bile temizlik yine de çalışır.

8. Tam Kod Örneği

İşte tek parça halinde tam betik. Çalışma alanını oluşturur, bir Modal sandbox başlatır, ajanı içinde çalıştırır, nihai çıktıyı yazdırır ve ardından sandbox oturumunu temizler. 

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())

Bu betik, mevcut OpenAI sandbox yapısını takip eder ve yürütme arka ucu olarak Modal’ı kullanır. Ajan mantığı Python uygulamanızda kalır; asıl çalışma alanı ise bir Modal sandbox içinde çalışır.

finally bloğu önemlidir; çünkü ajan çalışması başarısız olsa bile sandbox’ı kapatır ve siler. Bu, Modal ortamınızı temiz tutmanıza ve kullanılmayan oturumların çalışır durumda kalmasını önlemenize yardımcı olur.

9. Uygulamayı Yerelde Test Etme

Betik hazır olduğunda, main.py dosyasının kayıtlı olduğu aynı klasörde bir terminalden yerelde çalıştırın:

python main.py

Her şey doğru yapılandırıldıysa, betik bir Modal sandbox oluşturacak, manifesti içine yükleyecek, OpenAI ajanını çalışma alanına karşı çalıştıracak, yanıtı yazdıracak ve ardından sandbox’ı temizleyecektir.

Şuna benzer bir çıktı görmelisiniz:

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.

Çalıştırmanın tamamlanması birkaç saniye sürebilir. Çalışırken Modal panonuzu açın, openai-agents-modal-demo uygulamasına tıklayın ve günlükleri kontrol edin. Bu, sandbox’ın oluşturulduğunu, başlatıldığını, ajan tarafından kullanıldığını ve başarıyla temizlendiğini doğrulamanın kullanışlı bir yoludur.

10. Etkileşimli Bir Web Uygulaması Oluşturma 

İlk betik statiktir; yani yalnızca bir istek gönderebilir, bir yanıt alabilir ve durabiliriz. Projeyi kullanmayı kolaylaştırmak için, Gradio kullanarak bunu etkileşimli bir web uygulamasına dönüştürebiliriz. Bu sayede sandbox ajanıyla sohbet edebilir, takip soruları sorabilir, dosyalar oluşturup düzenleyebilir ve basit bir tarayıcı arayüzünden testler çalıştırabilirsiniz.

Önce Gradio’nun en son sürümünü kurun:

pip install gradio

Ardından app.py adlı yeni bir dosya oluşturun ve Gradio uygulama kodunu (OpenAI-Agents-in-Modal/app.py) içine kopyalayın. Bu uygulama aynı OpenAI Agents ve Modal Sandbox kurulumunu kullanır, ancak bunu bir sohbet arayüzü içine sarar. Kod ayrıca mümkün olduğunda sandbox oturumunu yeniden kullanır; böylece her mesajın sıfırdan tamamen yeni bir sandbox oluşturması gerekmez.

Uygulamayı şu komutla çalıştırın:

python app.py

Terminalinizde yerel bir URL görmelisiniz:

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

Sohbet uygulamasını kullanmak için yerel URL’yi tarayıcınızda açın. Ajandan projeyi incelemesini, hizmetin ne yaptığını açıklamasını, yeni yardımcı dosyalar oluşturmasını, mevcut dosyaları düzenlemesini veya Modal sandbox içinde testler çalıştırmasını isteyebilirsiniz.

Örneğin, önce projedeki hizmetin ne yaptığını açıklamasını istedim ve birkaç saniye içinde sandbox dosyalarına dayalı ayrıntılı bir yanıt döndürdü.

Daha sonra ajandan yeni bir yönlendirme yardımcı dosyası oluşturmasını istedim. Bu istek biraz daha uzun sürdü; çünkü ajan sandbox çalışma alanını değiştirmek, testler eklemek ve test paketini çalıştırmak zorundaydı.

Ajan src/routing_rules.py dosyasını oluşturdu, tests/test_routing_rules.py konumunda yeni bir test dosyası ekledi ve değişiklikleri pytest ile doğruladı. Tüm 6 test geçti; bu da yeni yardımcının düzgün çalıştığını ve mevcut bilet yönlendirme mantığının bozulmadığını doğruladı.

Genel olarak, bu Gradio uygulaması size Modal destekli bir OpenAI ajanıyla çalışma için basit bir ön yüz sunar. Kullanıcı tarayıcı üzerinden bir mesaj gönderir, uygulama bunu SandboxAgent’a iletir, ajan Modal sandbox içinde çalışır ve nihai yanıt sohbet arayüzünde gösterilir.

Son Düşünceler

Modal Sandboxes ile OpenAI Agents, gerçek dosyalarla çalışabilen, komutlar yürütebilen ve izole bir ortamdan faydalı çıktılar döndürebilen ajanik uygulamalar oluşturmak için temiz bir yol sunuyor. 

Modal için kurulum süreci sorunsuzdu ve sandbox oluşturmak oldukça basitti. Her şey bağlandıktan sonra, ajan projeyi inceleyebildi, yeni bir yönlendirme yardımcı dosyası oluşturabildi, testler ekleyebildi ve tüm 6 testin geçtiğini doğrulayabildi.

Bununla birlikte, etkileşimli uygulamayı oluşturmak ve modeli yapılandırmak beklenenden daha fazla emek gerektirdi. Dosya oluşturma ve test adımları da daha uzun sürdü; çünkü Modal sandbox bazen zaman aşımına uğradı. Ajanın tüm iş akışını tamamlaması için yeterli süre vermek adına sandbox zaman aşımını 300 saniyeden 600 saniyeye çıkarmak zorunda kaldım.

Bir diğer sorun noktası ise günlükleme ve görünürlüktü. Ajanın bitirmesini beklerken, Agents SDK’nın arka planda ne yaptığı her zaman net değildi. Modal günlükleri bile ajanın dosyaları mı incelediğini, kodu mu düzenlediğini yoksa testleri mi çalıştırdığını anlamak için her zaman yeterli ayrıntıyı göstermedi. 

Gelecekte, Claude Code gibi araçlarla çalışırken gördüğünüze benzer şekilde, her adımı daha net takip edebileceğiniz daha ayrıntılı ajan günlüklerine sahip olmak faydalı olacaktır.

Genel olarak, bu, özellikle ajanınızın dosyalar, kod ve üretilen çıktılarla çalışması gerekiyorsa sandbox’lanmış ajan uygulamaları oluşturmak için güçlü bir iş akışıdır. Tam projeyi GitHub’da bulabilir, yerelde klonlayabilir ve kendiniz çalıştırabilirsiniz: kingabzpro/OpenAI-Agents-in-Modal.

Gelişmiş yapay zeka sistemleri oluşturmanın tüm inceliklerini öğrenmek istiyorsanız, Building Scalable Agentic Systems kursumuzu almanızı öneririm.