OpenAI Agents SDK: jak uruchamiać agentów w piaskownicach Modal

Nowszy przepływ pracy piaskownicy Agents od OpenAI zmienia sposób strukturyzacji wykonywania agenta. Zamiast trzymać agenta, pliki, narzędzia i środowisko uruchomieniowe w jednej chaotycznej pętli, framework oddziela zaufaną warstwę orkiestracji od środowiska wykonawczego.

Oznacza to, że Państwa aplikacja może obsługiwać logikę agenta, wywołania modelu i podejmowanie decyzji, podczas gdy właściwa praca odbywa się wewnątrz odizolowanego środowiska z dostępem do plików, poleceń i generowanych wyników.

Takie ustawienie jest szczególnie przydatne, gdy agent musi zrobić więcej niż tylko odpowiadać na podstawie kontekstu promptu. Na przykład może przejrzeć projekt, tworzyć lub modyfikować pliki, uruchamiać kod, testować wyniki i generować artefakty w kontrolowanym środowisku.

W tym przewodniku nauczymy się, jak połączyć framework OpenAI Agents z piaskownicami Modal, aby zbudować praktyczną aplikację agents. Agent będzie mógł działać w odizolowanym środowisku Modal, bezpiecznie wykonywać polecenia, pracować z plikami i zwracać przydatne wyniki do głównej aplikacji.

Dla wprowadzenia bez użycia piaskownic polecam także nasz samouczek OpenAI Agents SDK. 

Co nowego w OpenAI Agents SDK?

Nowsze OpenAI Agents SDK wprowadza czystszy sposób budowania agentów, którzy mogą pracować z prawdziwymi plikami, narzędziami i środowiskami wykonawczymi. Zamiast trzymać wszystko w jednej pętli promptu, SDK oddziela warstwę orkiestracji agenta od piaskownicy, w której wykonywana jest praca.

Kluczowe aktualizacje obejmują:

• Natywne wsparcie dla piaskownic do uruchamiania agentów w odizolowanych środowiskach
• Manifest do definiowania plików, folderów i wyników, do których agent ma dostęp
• SandboxAgent do łączenia agenta z odizolowaną przestrzenią roboczą
• SandboxRunConfig do kontrolowania, gdzie i jak odbywa się uruchomienie w piaskownicy
• Narzędzia w stylu Codex do edycji plików, poleceń shell i inspekcji projektu
• Wsparcie MCP, aby umożliwić agentom łączenie się z zewnętrznymi narzędziami i usługami
• Skills i wsparcie dla AGENTS.md, aby przekazywać agentom jaśniejsze instrukcje projektowe
• Wsparcie wielu dostawców piaskownic, w tym Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop i Vercel

Łącznie te aktualizacje ułatwiają budowę aplikacji agents, które mogą inspekcjonować projekty, uruchamiać kod, edytować pliki i zwracać wygenerowane wyniki z kontrolowanego środowiska pracy.

1. Konfigurowanie projektu

W tym projekcie demonstracyjnym zbudujemy mały przykład triage zgłoszeń wsparcia z użyciem OpenAI Agents SDK i piaskownic Modal. Aplikacja utworzy odizolowaną przestrzeń roboczą, doda do niej kilka plików projektu, a następnie poprosi agenta GPT-5.4-mini o przejrzenie tych plików przed udzieleniem odpowiedzi.

Zacznij od zainstalowania wymaganych pakietów w swoim środowisku:

pip install "openai-agents[modal]" modal

Przed uruchomieniem projektu potrzebne są dwa konta:

• Konto OpenAI: Utwórz konto na OpenAI Platform i dodaj środki do API przy użyciu karty kredytowej. Upewnij się, że konto jest zweryfikowane, aby mieć dostęp do najnowszych obsługiwanych modeli.
• Konto Modal: Zarejestruj się w Modal. Darmowy plan zawiera miesięczne kredyty wystarczające do przetestowania tego przewodnika.

Następnie dodaj klucz API OpenAI do lokalnego środowiska.

• Na macOS lub Linux: export OPENAI_API_KEY="your_openai_api_key"
• W Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

Następnie uwierzytelnij Modal lokalnie:

modal setup

To otworzy okno przeglądarki i poprosi o zalogowanie do Modal. Po zalogowaniu zatwierdź żądanie wygenerowania tokenu. Modal automatycznie doda poświadczenia do lokalnego środowiska.

Po zakończeniu konfiguracji w terminalu powinna pojawić się wiadomość o powodzeniu, potwierdzająca ukończenie uwierzytelniania Modal.

2. Definiowanie przestrzeni roboczej piaskownicy

Następnie utwórz plik Pythona, np. main.py i dodaj wymagane importy. Te importy wprowadzają OpenAI Agents SDK, klasy konfiguracji piaskownicy oraz klienta piaskownicy 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

Teraz musimy zdefiniować przestrzeń roboczą piaskownicy. W tym przykładzie obejmuje ona mały projekt triage zgłoszeń wsparcia z plikiem README.md, plikiem aplikacji i listą kontrolną wydania.

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 informuje agenta, jakie pliki znajdują się w piaskownicy. Daje to agentowi prawdziwą strukturę projektu do przeglądania, edycji i rozumowania, zamiast polegania wyłącznie na tekście w promptach.

W tym przypadku agent będzie mógł przejrzeć logikę kierowania zgłoszeń wsparcia, sprawdzić dokumentację i wprowadzać zmiany w odizolowanej przestrzeni roboczej.

3. Tworzenie agenta piaskownicy

Gdy przestrzeń robocza jest zdefiniowana, utwórz agenta opartego na piaskownicy. SandboxAgent jest zaprojektowany do pracy z realną przestrzenią roboczą, co oznacza, że może przeglądać pliki, rozumieć strukturę projektu i odpowiadać w oparciu o to, co istnieje w piaskownicy.

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

Tutaj nazywamy agenta Modal Sandbox Assistant i używamy modelu gpt-5.4-mini dla szybszych odpowiedzi. Instrukcje nakazują agentowi przejrzeć przestrzeń roboczą piaskownicy przed odpowiedzią, co jest ważne, gdy odpowiedź zależy od faktycznych plików w projekcie.

Ustawienie default_manifest=manifest łączy agenta z utworzoną wcześniej przestrzenią roboczą. Opcja tool_choice="required" zachęca agenta do korzystania z dostępnych narzędzi piaskownicy zamiast odpowiadać wyłącznie z pamięci lub kontekstu promptu.

4. Tworzenie klienta piaskownicy Modal

Następnie utwórz klienta piaskownicy Modal. To połączenie między przepływem pracy OpenAI Agents a piaskownicą Modal, gdzie nastąpi faktyczne wykonywanie plików i poleceń.

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

ModalSandboxClient() wskazuje agentowi, aby używał Modal jako dostawcy piaskownicy. Oznacza to, że agent może działać w odizolowanym środowisku Modal zamiast uruchamiać się bezpośrednio na lokalnej maszynie.

ModalSandboxClientOptions kontroluje konfigurację piaskownicy Modal. Tutaj app_name nadaje aplikacji Modal czytelną nazwę, a workspace_persistence="tar" informuje Modal, jak pakować i utrwalać pliki przestrzeni roboczej podczas uruchomienia.

5. Uruchamianie sesji piaskownicy

Gdy klient i opcje są gotowe, utwórz piaskownicę na podstawie manifest i rozpocznij sesję. 

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

await sandbox.start()

Wywołanie client.create() tworzy nową piaskownicę Modal przy użyciu plików zdefiniowanych w Manifest. Oznacza to, że piaskownica startuje z tą samą strukturą projektu, w tym z README.md, src/app.py i docs/release-checks.md.

Następnie await sandbox.start() uruchamia sesję piaskownicy. W tym momencie mają Państwo aktywną, odizolowaną przestrzeń roboczą działającą w Modal, gotową, by agent przeglądał pliki, uruchamiał polecenia i pracował z projektem.

6. Uruchamianie agenta w piaskownicy

Gdy piaskownica jest aktywna, uruchom agenta względem niej, przekazując działającą sesję piaskownicy poprzez SandboxRunConfig. Informuje to OpenAI Agents SDK, że podczas działania agent powinien korzystać z przestrzeni roboczej piaskownicy Modal. 

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)

Tu wszystko się ze sobą łączy. Model odpowiada za rozumowanie, a piaskownica daje mu dostęp do prawdziwych plików przestrzeni roboczej.

W tym przykładzie agent może przejrzeć projekt triage zgłoszeń wsparcia, zrozumieć, co robi usługa, sprawdzić notatki wydania i zwrócić krótką odpowiedź na podstawie plików w piaskownicy Modal.

7. Sprzątanie po piaskownicy

Po zakończeniu działania agenta usuń piaskownicę, aby nie pozostawić nieużywanych sesji działających w Modal.

await client.aclose(sandbox)

To usuwa sesję piaskownicy po zakończeniu pracy. To dobry nawyk, ponieważ aktywne sesje piaskownicy mogą zużywać zasoby obliczeniowe.

W prawdziwym projekcie należy umieścić to w bloku finally. Dzięki temu sprzątanie wykona się nawet, jeśli wywołanie agenta się nie powiedzie lub skrypt napotka błąd.

8. Pełny przykład kodu

Oto kompletny skrypt w jednym miejscu. Tworzy przestrzeń roboczą, uruchamia piaskownicę Modal, uruchamia w niej agenta, drukuje wynik końcowy, a następnie sprząta sesję piaskownicy. 

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

Ten skrypt podąża za obecną strukturą piaskownicy OpenAI i używa Modal jako backendu wykonawczego. Logika agenta pozostaje w Państwa aplikacji w Pythonie, podczas gdy właściwa przestrzeń robocza działa w piaskownicy Modal.

Blok finally jest ważny, ponieważ zamyka i usuwa piaskownicę nawet, jeśli uruchomienie agenta się nie powiedzie. Pomaga to utrzymać środowisko Modal w czystości i unikać pozostawiania nieużywanych sesji.

9. Testowanie aplikacji lokalnie

Gdy skrypt jest gotowy, uruchom go lokalnie z terminala w tym samym folderze, w którym zapisano main.py:

python main.py

Jeśli wszystko jest poprawnie skonfigurowane, skrypt utworzy piaskownicę Modal, załaduje do niej manifest, uruchomi agenta OpenAI względem przestrzeni roboczej, wydrukuje odpowiedź, a następnie posprząta piaskownicę.

Powinni Państwo zobaczyć podobny wynik:

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.

Uruchomienie może potrwać kilka sekund. W trakcie działania proszę otworzyć panel Modal, kliknąć aplikację openai-agents-modal-demo i sprawdzić logi. To przydatny sposób, aby potwierdzić, że piaskownica została utworzona, uruchomiona, użyta przez agenta i pomyślnie posprzątana.

10. Tworzenie interaktywnej aplikacji webowej 

Pierwszy skrypt jest statyczny, co oznacza, że możemy wysłać tylko jedno żądanie, otrzymać jedną odpowiedź i zakończyć. Aby ułatwić korzystanie z projektu, możemy przekształcić go w interaktywną aplikację webową za pomocą Gradio. Dzięki temu możemy rozmawiać z agentem w piaskownicy, zadawać pytania uzupełniające, tworzyć lub edytować pliki oraz uruchamiać testy z prostego interfejsu przeglądarkowego.

Najpierw zainstaluj najnowszą wersję Gradio:

pip install gradio

Następnie utwórz nowy plik o nazwie app.py i skopiuj do niego kod aplikacji Gradio (OpenAI-Agents-in-Modal/app.py). Ta aplikacja korzysta z tego samego ustawienia OpenAI Agents i piaskownicy Modal, ale opakowuje je w interfejs czatu. Kod ponownie wykorzystuje też sesję piaskownicy, gdy to możliwe, więc każda wiadomość nie musi tworzyć całkowicie nowej piaskownicy od zera.

Uruchom aplikację poleceniem:

python app.py

W terminalu powinna pojawić się lokalna ścieżka URL:

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

Proszę otworzyć lokalny adres URL w przeglądarce, aby skorzystać z aplikacji czatu. Mogą Państwo poprosić agenta o inspekcję projektu, wyjaśnienie działania usługi, utworzenie nowych plików pomocniczych, edycję istniejących plików lub uruchamianie testów w piaskownicy Modal.

Na przykład najpierw poprosiłem o wyjaśnienie, co robi usługa projektu i w ciągu kilku sekund otrzymałem szczegółową odpowiedź opartą na plikach piaskownicy.

Następnie poprosiłem agenta o utworzenie nowego pliku pomocniczego do routingu. To żądanie zajęło nieco więcej czasu, ponieważ agent musiał zmodyfikować przestrzeń roboczą piaskownicy, dodać testy i uruchomić zestaw testów.

Agent utworzył src/routing_rules.py, dodał nowy plik testowy w tests/test_routing_rules.py i zweryfikował zmiany za pomocą pytest. Wszystkie 6 testów przeszło pomyślnie, co potwierdziło, że nowy helper działa poprawnie, a istniejąca logika kierowania zgłoszeń pozostała nienaruszona.

W dużym uproszczeniu, ta aplikacja Gradio zapewnia prosty frontend do pracy z agentem OpenAI działającym w Modal. Użytkownik wysyła wiadomość przez przeglądarkę, aplikacja przekazuje ją do SandboxAgent, agent pracuje w piaskownicy Modal, a odpowiedź końcowa jest wyświetlana w interfejsie czatu.

Podsumowanie

OpenAI Agents wraz z piaskownicami Modal oferują przejrzysty sposób budowy aplikacji agents, które mogą pracować z prawdziwymi plikami, uruchamiać polecenia i zwracać przydatne wyniki z odizolowanego środowiska. 

Proces konfiguracji Modal był płynny, a utworzenie samej piaskownicy — proste. Po połączeniu wszystkiego agent był w stanie przejrzeć projekt, utworzyć nowy plik pomocniczy do routingu, dodać testy i potwierdzić, że wszystkie 6 testów przeszło.

Niemniej zbudowanie interaktywnej aplikacji i skonfigurowanie modelu wymagało więcej pracy, niż oczekiwałem. Kroki tworzenia plików i testowania też trwały dłużej, ponieważ piaskownica Modal czasem przekraczała limit czasu. Musiałem zwiększyć limit czasu piaskownicy z 300 sekund do 600 sekund, aby dać agentowi wystarczająco dużo czasu na ukończenie pełnego przepływu.

Innym punktem bólu były logowanie i widoczność. Podczas oczekiwania na zakończenie pracy agenta nie zawsze było jasne, co SDK Agents robi w tle. Nawet logi Modal nie zawsze pokazywały wystarczająco dużo szczegółów, by zrozumieć, czy agent przegląda pliki, edytuje kod, czy uruchamia testy. 

W przyszłości pomocne byłoby bardziej szczegółowe logowanie agenta, podobne do tego, które widzimy w narzędziach takich jak Claude Code, gdzie można wyraźniej śledzić każdy krok.

Ogólnie rzecz biorąc, to solidny przepływ pracy do budowy aplikacji agentów w piaskownicy, zwłaszcza jeśli Państwa agent musi pracować z plikami, kodem i generowanymi wynikami. Cały projekt można znaleźć na GitHubie, sklonować lokalnie i uruchomić samodzielnie: kingabzpro/OpenAI-Agents-in-Modal.

Jeśli chcą Państwo poznać niuanse budowy zaawansowanych systemów AI, polecam nasz kurs Building Scalable Agentic Systems.