OpenAI Agents SDK: วิธีรันเอเจนต์ใน Modal Sandboxes

เวิร์กโฟลว์ sandbox ของ Agents รุ่นใหม่ของ OpenAI เปลี่ยนโครงสร้างการทำงานของเอเจนต์ จากเดิมที่รวมเอเจนต์ ไฟล์ เครื่องมือ และรันไทม์ไว้ในลูปเดียวที่ยุ่งเหยิง เฟรมเวิร์กใหม่จะแยกชั้น orchestration ที่เชื่อถือได้ออกจากสภาพแวดล้อมสำหรับรันงานจริง

นั่นหมายความว่าแอปพลิเคชันของคุณจะจัดการลอจิกของเอเจนต์ การเรียกโมเดล และการตัดสินใจ ขณะที่งานจริงจะเกิดขึ้นในพื้นที่ทำงานแบบ sandbox ที่เข้าถึงไฟล์ คำสั่ง และเอาต์พุตที่สร้างขึ้นได้

การตั้งค่านี้มีประโยชน์มากเมื่อเอเจนต์ต้องทำมากกว่าการตอบจากคอนเท็กซ์ของพรอมต์เพียงอย่างเดียว เช่น ตรวจสอบโปรเจกต์ เขียนหรือแก้ไขไฟล์ รันโค้ด ทดสอบเอาต์พุต และสร้างอาร์ติแฟกต์ในสภาพแวดล้อมที่ควบคุมได้

ในคู่มือนี้ เราจะเรียนรู้การผสานเฟรมเวิร์ก OpenAI Agents เข้ากับ Modal Sandboxes เพื่อสร้างแอปเอเจนต์ที่ใช้งานได้จริง เอเจนต์จะสามารถรันในสภาพแวดล้อมแบบแยกขาดของ Modal รันคำสั่งอย่างปลอดภัย ทำงานกับไฟล์ และส่งเอาต์พุตที่เป็นประโยชน์กลับไปยังแอปหลัก

สำหรับบทนำที่ไม่ใช้ sandbox ขอแนะนำให้อ่าน OpenAI Agents SDK Tutorial ของเรา 

มีอะไรใหม่ใน OpenAI Agents SDK?

OpenAI Agents SDK รุ่นใหม่ เพิ่มวิธีที่เป็นระเบียบกว่าในการสร้างเอเจนต์ที่ทำงานกับไฟล์จริง เครื่องมือ และสภาพแวดล้อมรันโค้ดได้ โดยแทนที่จะเก็บทุกอย่างไว้ในลูปพรอมต์เดียว SDK จะแยกชั้น orchestration ของเอเจนต์ออกจาก sandbox ที่งานเกิดขึ้นจริง

อัปเดตสำคัญประกอบด้วย:

• รองรับ sandbox ในตัว สำหรับรันเอเจนต์ในสภาพแวดล้อมที่แยกขาด
• Manifest เพื่อกำหนดไฟล์ โฟลเดอร์ และเอาต์พุตที่เอเจนต์เข้าถึงได้
• SandboxAgent เพื่อเชื่อมเอเจนต์เข้ากับพื้นที่ทำงานแบบ sandbox
• SandboxRunConfig เพื่อควบคุมว่าจะรัน sandbox ที่ไหนและอย่างไร
• เครื่องมือสไตล์ Codex สำหรับแก้ไขไฟล์ รันคำสั่งเชลล์ และตรวจสอบโปรเจกต์
• รองรับ MCP เพื่อให้เอเจนต์เชื่อมต่อกับเครื่องมือและบริการภายนอก
• Skills และรองรับ AGENTS.md เพื่อมอบคำแนะนำโครงการที่ชัดเจนขึ้นแก่เอเจนต์
• รองรับผู้ให้บริการ sandbox หลายราย ได้แก่ Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop และ Vercel

เมื่อรวมกันแล้ว อัปเดตเหล่านี้ทำให้สร้างแอปแบบ agentic ได้ง่ายขึ้นซึ่งสามารถตรวจสอบโปรเจกต์ รันโค้ด แก้ไขไฟล์ และส่งคืนเอาต์พุตที่สร้างขึ้นจากพื้นที่ทำงานที่ควบคุมได้

1. การตั้งค่าโปรเจกต์

ในโปรเจกต์สาธิตนี้ เราจะสร้างตัวอย่างคัดกรองทิกเก็ตซัพพอร์ตอย่างง่ายด้วย OpenAI Agents SDK และ Modal Sandboxes แอปจะสร้างพื้นที่ทำงานแบบ sandbox เพิ่มไฟล์โปรเจกต์บางส่วน แล้วให้เอเจนต์ GPT-5.4-mini ตรวจสอบไฟล์เหล่านั้นก่อนตอบ

เริ่มจากติดตั้งแพ็กเกจที่จำเป็นในสภาพแวดล้อมของคุณ:

pip install "openai-agents[modal]" modal

ก่อนรันโปรเจกต์ คุณต้องมีสองบัญชี:

• บัญชี OpenAI: สร้างบัญชีที่ OpenAI Platform และเพิ่มเครดิต API ด้วยบัตรเครดิต ตรวจสอบให้แน่ใจว่าบัญชีผ่านการยืนยันเพื่อเข้าถึงโมเดลล่าสุดที่รองรับ
• บัญชี Modal: สมัครใช้ Modal แผนฟรีมีเครดิตรายเดือนเพียงพอสำหรับทดสอบคู่มือนี้

ถัดไป เพิ่มคีย์ OpenAI API ลงในสภาพแวดล้อมเครื่องของคุณ

• บน macOS หรือ Linux: export OPENAI_API_KEY="your_openai_api_key"
• บน Windows PowerShell: $env:OPENAI_API_KEY="your_openai_api_key"

จากนั้นยืนยันตัวตน Modal ในเครื่อง:

modal setup

คำสั่งนี้จะเปิดหน้าต่างเบราว์เซอร์และขอให้ลงชื่อเข้าใช้ Modal หลังจากลงชื่อเข้าใช้แล้ว ให้อนุมัติคำขอสร้างโทเค็น Modal จะเพิ่มข้อมูลยืนยันตัวตนลงในสภาพแวดล้อมเครื่องของคุณโดยอัตโนมัติ

เมื่อตั้งค่าทุกอย่างเสร็จ จะเห็นข้อความยืนยันความสำเร็จในเทอร์มินัลว่าการยืนยันตัวตน Modal เสร็จสมบูรณ์

2. กำหนดพื้นที่ทำงานของ Sandbox

ถัดไป สร้างไฟล์ Python เช่น main.py และเพิ่มการนำเข้าโมดูลที่จำเป็น ซึ่งจะดึง OpenAI Agents SDK คลาสกำหนดค่า sandbox และไคลเอนต์ Modal sandbox เข้ามา 

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

ตอนนี้ต้องกำหนดพื้นที่ทำงานของ sandbox ในตัวอย่างนี้ พื้นที่ทำงานประกอบด้วยโปรเจกต์คัดกรองทิกเก็ตซัพพอร์ตเล็ก ๆ ที่มี README.md ไฟล์แอป และเช็กลิสต์ก่อนปล่อยเวอร์ชัน

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 บอกเอเจนต์ว่าใน sandbox มีไฟล์อะไรบ้าง ทำให้เอเจนต์มีโครงสร้างโปรเจกต์จริงให้ตรวจสอบ แก้ไข และใช้เหตุผล แทนที่จะอาศัยแต่ข้อความในพรอมต์

กรณีนี้ เอเจนต์จะตรวจสอบลอจิกการจัดเส้นทางทิกเก็ตซัพพอร์ต ตรวจดูเอกสาร และทำการเปลี่ยนแปลงภายในพื้นที่ทำงานแบบ sandbox ได้

3. สร้าง Sandbox Agent

เมื่อกำหนดพื้นที่ทำงานแล้ว ให้สร้างเอเจนต์ที่เชื่อมกับ sandbox SandboxAgent ถูกออกแบบให้ทำงานกับพื้นที่ทำงานจริง หมายความว่าสามารถตรวจไฟล์ เข้าใจโครงสร้างโปรเจกต์ และตอบโดยอิงจากสิ่งที่อยู่ใน 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"),
)

ที่นี่ เราตั้งชื่อเอเจนต์ว่า Modal Sandbox Assistant และใช้โมเดล gpt-5.4-mini เพื่อการตอบที่รวดเร็ว คำสั่งจะบอกเอเจนต์ให้ตรวจพื้นที่ทำงานใน sandbox ก่อนตอบ ซึ่งสำคัญเมื่อคำตอบขึ้นกับไฟล์จริงในโปรเจกต์

พารามิเตอร์ default_manifest=manifest เชื่อมเอเจนต์เข้ากับพื้นที่ทำงานที่สร้างไว้ก่อนหน้า ส่วนการตั้งค่า tool_choice="required" ช่วยกระตุ้นให้เอเจนต์ใช้เครื่องมือ sandbox ที่มี แทนการตอบจากความจำหรือคอนเท็กซ์ของพรอมต์เพียงอย่างเดียว

4. สร้างไคลเอนต์ Modal Sandbox

ถัดไป สร้างไคลเอนต์ Modal sandbox ซึ่งเป็นตัวเชื่อมระหว่างเวิร์กโฟลว์ OpenAI Agents กับ Modal sandbox ที่จะรันการเข้าถึงไฟล์และคำสั่งจริง

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

ModalSandboxClient() บอกเอเจนต์ให้ใช้ Modal เป็นผู้ให้บริการ sandbox หมายความว่าเอเจนต์จะรันในสภาพแวดล้อม Modal ที่แยกขาด แทนที่จะรันบนเครื่องของคุณโดยตรง

ส่วน ModalSandboxClientOptions ใช้ควบคุมการตั้งค่า Modal sandbox ที่นี่ app_name ตั้งชื่อแอปใน Modal ให้ชัดเจน ส่วน workspace_persistence="tar" กำหนดวิธีบรรจุและคงสภาพไฟล์พื้นที่ทำงานระหว่างการรัน

5. เริ่มเซสชัน Sandbox

เมื่อพร้อมทั้งไคลเอนต์และออปชันแล้ว ให้สร้าง sandbox จาก manifest และเริ่มเซสชัน 

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

await sandbox.start()

คำสั่ง client.create() จะสร้าง Modal sandbox ใหม่โดยใช้ไฟล์ที่กำหนดไว้ใน Manifest ทำให้ sandbox เริ่มต้นด้วยโครงสร้างโปรเจกต์เดียวกัน รวมถึง README.md, src/app.py และ docs/release-checks.md

จากนั้น await sandbox.start() จะเริ่มเซสชัน sandbox ตอนนี้คุณมีพื้นที่ทำงานแบบแยกขาดที่รันอยู่บน Modal พร้อมให้เอเจนต์ตรวจไฟล์ รันคำสั่ง และทำงานกับโปรเจกต์

6. รันเอเจนต์ใน Sandbox

เมื่อ sandbox ทำงานแล้ว ให้รันเอเจนต์กับมันโดยส่งเซสชัน sandbox แบบไลฟ์ผ่าน SandboxRunConfig นี่จะแจ้ง OpenAI Agents SDK ว่าเอเจนต์ควรใช้พื้นที่ทำงาน Modal sandbox ระหว่างการรัน 

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)

นี่คือตอนที่ทุกอย่างทำงานร่วมกัน โมเดลจะจัดการเหตุผล ขณะที่ sandbox เปิดให้เข้าถึงไฟล์พื้นที่ทำงานจริง

ในตัวอย่างนี้ เอเจนต์จะตรวจโปรเจกต์คัดกรองทิกเก็ตซัพพอร์ต ทำความเข้าใจว่าบริการทำอะไร ตรวจเช็คหมายเหตุการปล่อยเวอร์ชัน และส่งคำตอบสั้น ๆ โดยอิงจากไฟล์ภายใน Modal sandbox

7. ทำความสะอาด Sandbox

หลังเอเจนต์รันเสร็จ ให้ลบ sandbox เพื่อไม่ให้มีเซสชันที่ไม่ใช้งานค้างอยู่ใน Modal

await client.aclose(sandbox)

คำสั่งนี้จะลบเซสชัน sandbox หลังงานเสร็จ เป็นนิสัยที่ดีเพราะขณะเซสชันทำงานอยู่จะใช้ทรัพยากรคอมพิวต์

ในโปรเจกต์จริง ควรวางไว้ในบล็อก finally เพื่อให้การทำความสะอาดยังทำงานแม้เอเจนต์ล้มเหลวหรือสคริปต์เกิดข้อผิดพลาด

8. ตัวอย่างโค้ดฉบับเต็ม

นี่คือสคริปต์ฉบับสมบูรณ์ในที่เดียว สร้างพื้นที่ทำงาน เริ่ม Modal sandbox รันเอเจนต์ภายใน แสดงผลลัพธ์สุดท้าย แล้วทำความสะอาดเซสชัน 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())

สคริปต์นี้ปฏิบัติตามโครงสร้าง sandbox ปัจจุบันของ OpenAI และใช้ Modal เป็นแบ็กเอนด์สำหรับรันงาน ลอจิกของเอเจนต์อยู่ในแอป Python ของคุณ ขณะที่พื้นที่ทำงานจริงรันอยู่ใน Modal sandbox

บล็อก finally สำคัญเพราะจะปิดและลบ sandbox แม้การรันเอเจนต์ล้มเหลว ช่วยรักษาสภาพแวดล้อม Modal ให้สะอาดและหลีกเลี่ยงการปล่อยให้เซสชันที่ไม่ใช้ค้างอยู่

9. ทดสอบแอปในเครื่อง

เมื่อสคริปต์พร้อม ให้รันในเครื่องจากเทอร์มินัลในโฟลเดอร์เดียวกับที่บันทึก main.py ไว้

python main.py

หากกำหนดค่าทุกอย่างถูกต้อง สคริปต์จะสร้าง Modal sandbox โหลด manifest เข้าไป รันเอเจนต์ของ OpenAI กับพื้นที่ทำงาน แสดงคำตอบ แล้วทำความสะอาด sandbox

คุณควรเห็นเอาต์พุตลักษณะนี้:

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.

การรันอาจใช้เวลาสองสามวินาที ระหว่างนั้นให้เปิดแดชบอร์ด Modal คลิกที่แอป openai-agents-modal-demo และตรวจสอบล็อก เป็นวิธีที่ดีในการยืนยันว่า sandbox ถูกสร้าง เริ่มต้น ใช้งานโดยเอเจนต์ และทำความสะอาดเรียบร้อย

10. สร้างเว็บแอปแบบโต้ตอบ 

สคริปต์แรกเป็นแบบสเตติก นั่นคือส่งคำขอครั้งเดียว รับคำตอบครั้งเดียว แล้วหยุด เพื่อให้ใช้งานโปรเจกต์ได้สะดวกขึ้น เราสามารถแปลงเป็นเว็บแอปแบบโต้ตอบด้วย Gradio สิ่งนี้ช่วยให้แชตกับเอเจนต์ใน sandbox ถามต่อเนื่อง สร้างหรือแก้ไขไฟล์ และรันเทสต์ได้จากอินเทอร์เฟซเบราว์เซอร์ง่าย ๆ

ก่อนอื่น ติดตั้ง Gradio เวอร์ชันล่าสุด:

pip install gradio

จากนั้นสร้างไฟล์ใหม่ชื่อ app.py แล้วคัดลอกโค้ดแอป Gradio (OpenAI-Agents-in-Modal/app.py) ลงไป แอปนี้ใช้การตั้งค่า OpenAI Agents และ Modal Sandbox แบบเดียวกัน แต่หุ้มไว้ในอินเทอร์เฟซแชต โค้ดยังนำเซสชัน sandbox กลับมาใช้ซ้ำเมื่อทำได้ จึงไม่ต้องสร้าง sandbox ใหม่ทุกข้อความ

รันแอปด้วย:

python app.py

คุณจะเห็น URL แบบโลคัลในเทอร์มินัล:

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

เปิด URL ดังกล่าวในเบราว์เซอร์เพื่อใช้งานแอปแชต สามารถขอให้เอเจนต์ตรวจโปรเจกต์ อธิบายว่าบริการทำอะไร สร้างไฟล์ช่วยเหลือใหม่ แก้ไขไฟล์เดิม หรือรันเทสต์ภายใน Modal sandbox

ตัวอย่างเช่น ฉันเริ่มจากให้มันอธิบายว่าบริการของโปรเจกต์ทำอะไร และภายในไม่กี่วินาที ก็ส่งคำตอบละเอียดโดยอิงจากไฟล์ใน sandbox

จากนั้นฉันขอให้เอเจนต์สร้างไฟล์ช่วยเหลือสำหรับการจัดเส้นทางใหม่ คำขอนี้ใช้เวลานานขึ้นเล็กน้อยเพราะเอเจนต์ต้องแก้ไขพื้นที่ทำงานใน sandbox เพิ่มเทสต์ และรันชุดเทสต์

เอเจนต์สร้าง src/routing_rules.py เพิ่มไฟล์เทสต์ใหม่ที่ tests/test_routing_rules.py และยืนยันการเปลี่ยนแปลงด้วย pytest เทสต์ทั้ง 6 รายการผ่านทั้งหมด ยืนยันว่าไฟล์ช่วยเหลือใหม่ทำงานถูกต้องและลอจิกจัดเส้นทางทิกเก็ตเดิมยังคงครบถ้วน

โดยภาพรวม แอป Gradio นี้มอบส่วนหน้าอย่างง่ายสำหรับทำงานกับเอเจนต์ OpenAI ที่รองรับโดย Modal ผู้ใช้ส่งข้อความผ่านเบราว์เซอร์ แอปส่งต่อไปยัง SandboxAgent เอเจนต์ทำงานภายใน Modal sandbox และคำตอบสุดท้ายจะแสดงกลับในอินเทอร์เฟซแชต

ข้อคิดส่งท้าย

OpenAI Agents ร่วมกับ Modal Sandboxes มอบวิธีที่สะอาดตาในการสร้างแอปแบบ agentic ที่ทำงานกับไฟล์จริง รันคำสั่ง และส่งคืนเอาต์พุตที่เป็นประโยชน์จากสภาพแวดล้อมที่แยกขาดได้ 

กระบวนการตั้งค่า Modal ราบรื่น และการสร้าง sandbox เองก็ตรงไปตรงมา เมื่อเชื่อมต่อทุกอย่างแล้ว เอเจนต์สามารถตรวจโปรเจกต์ สร้างไฟล์ช่วยเหลือการจัดเส้นทางใหม่ เพิ่มเทสต์ และยืนยันว่าเทสต์ทั้ง 6 รายการผ่าน

อย่างไรก็ดี การสร้างแอปแบบโต้ตอบและตั้งค่าโมเดลใช้เวลามากกว่าที่คาด ขั้นตอนสร้างไฟล์และการทดสอบก็ใช้เวลานานขึ้นเพราะ Modal sandbox บางครั้งหมดเวลา ต้องเพิ่ม timeout ของ sandbox จาก 300 วินาทีเป็น 600 วินาทีเพื่อให้เอเจนต์มีเวลาพอสำหรับเวิร์กโฟลว์ครบถ้วน

อีกจุดที่ติดขัดคือการบันทึกล็อกและการมองเห็น ระหว่างรอให้เอเจนต์ทำงานเสร็จ บางครั้งไม่ชัดเจนว่า Agents SDK กำลังทำอะไรอยู่เบื้องหลัง แม้แต่ล็อกของ Modal ก็ไม่ได้แสดงรายละเอียดมากพอเสมอไปว่าจะกำลังตรวจไฟล์ แก้ไขโค้ด หรือรันเทสต์

อนาคตจะเป็นประโยชน์หากมีล็อกของเอเจนต์ที่ละเอียดขึ้น คล้ายเวลาทำงานกับเครื่องมืออย่าง Claude Code ที่ติดตามแต่ละขั้นตอนได้ชัดเจนกว่า

โดยรวม นี่เป็นเวิร์กโฟลว์ที่แข็งแรงสำหรับสร้างแอปเอเจนต์ใน sandbox โดยเฉพาะเมื่ อเอเจนต์ต้องทำงานกับไฟล์ โค้ด และเอาต์พุตที่สร้างขึ้น สามารถดูโปรเจกต์เต็มบน GitHub โคลนลงเครื่อง และลองรันเองได้ที่: kingabzpro/OpenAI-Agents-in-Modal.

หากต้องการเรียนรู้เชิงลึกเกี่ยวกับการสร้างระบบ AI ขั้นก้าวหน้า ขอแนะนำคอร์ส Building Scalable Agentic Systems ของเรา