Tracks
Cơ bản về Trợ lý Trí tuệ Nhân tạo
6 giờ
Quy trình sandbox mới của OpenAI Agents thay đổi cách tổ chức việc thực thi agent. Thay vì để agent, tệp, công cụ và runtime trong một vòng lặp lộn xộn, framework tách lớp điều phối đáng tin cậy khỏi môi trường thực thi.
Điều này có nghĩa là ứng dụng của bạn có thể xử lý logic của agent, gọi mô hình và ra quyết định, trong khi công việc thực tế diễn ra bên trong không gian làm việc sandbox với quyền truy cập vào tệp, lệnh và đầu ra được tạo.
Thiết lập này đặc biệt hữu ích khi agent của bạn cần làm nhiều hơn là chỉ phản hồi từ ngữ cảnh prompt. Ví dụ, nó có thể kiểm tra một dự án, viết hoặc chỉnh sửa tệp, chạy mã, kiểm thử đầu ra và tạo artifact trong một môi trường được kiểm soát.
Trong hướng dẫn này, chúng ta sẽ học cách kết hợp OpenAI Agents framework với Modal Sandboxes để xây dựng một ứng dụng agent thực tiễn. Agent sẽ có thể chạy bên trong môi trường Modal cách ly, thực thi lệnh an toàn, làm việc với tệp và trả kết quả hữu ích về ứng dụng chính.
Để nhập môn mà không dùng sandbox, tôi cũng khuyến nghị đọc Hướng dẫn OpenAI Agents SDK của chúng tôi.
Có gì mới trong OpenAI Agents SDK?
Phiên bản OpenAI Agents SDK mới bổ sung cách gọn gàng hơn để xây dựng agent có thể làm việc với tệp thực, công cụ và môi trường thực thi. Thay vì nhét mọi thứ vào một vòng lặp prompt, SDK nay tách lớp điều phối agent khỏi sandbox nơi công việc diễn ra.
Cập nhật chính gồm:
- Hỗ trợ sandbox gốc để chạy agent trong môi trường cách ly
- Manifest để định nghĩa tệp, thư mục và đầu ra mà agent có thể truy cập
- SandboxAgent để kết nối agent với không gian làm việc sandbox
- SandboxRunConfig để kiểm soát nơi và cách chạy sandbox
- Công cụ kiểu Codex để chỉnh sửa tệp, lệnh shell và kiểm tra dự án
- Hỗ trợ MCP giúp agent kết nối với công cụ và dịch vụ bên ngoài
- Skills và hỗ trợ AGENTS.md để cung cấp hướng dẫn dự án rõ ràng hơn cho agent
- Hỗ trợ nhiều nhà cung cấp sandbox, gồm Modal, E2B, Cloudflare, Daytona, Blaxel, Runloop và Vercel
Tổng hợp lại, các cập nhật này giúp dễ dàng xây dựng ứng dụng agent có thể kiểm tra dự án, chạy mã, chỉnh sửa tệp và trả về đầu ra tạo sinh từ một không gian làm việc được kiểm soát.
1. Thiết lập dự án
Trong dự án demo này, chúng ta sẽ xây dựng ví dụ phân loại phiếu hỗ trợ (support ticket triage) nhỏ bằng OpenAI Agents SDK và Modal Sandboxes. Ứng dụng sẽ tạo không gian làm việc sandbox, thêm vài tệp dự án vào đó, rồi yêu cầu agent GPT-5.4-mini kiểm tra các tệp trước khi trả lời.
Bắt đầu bằng cách cài đặt các gói cần thiết trong môi trường của bạn:
pip install "openai-agents[modal]" modalTrước khi chạy dự án, bạn cần hai tài khoản:
- Tài khoản OpenAI: Tạo tài khoản tại OpenAI Platform và nạp tín dụng API bằng thẻ tín dụng. Hãy đảm bảo tài khoản của bạn đã được xác minh để truy cập các mô hình được hỗ trợ mới nhất.
- Tài khoản Modal: Đăng ký Modal. Gói miễn phí có tín dụng hàng tháng, đủ để thử hướng dẫn này.
Tiếp theo, thêm khóa API OpenAI vào môi trường cục bộ của bạn.
- Trên macOS hoặc Linux:
export OPENAI_API_KEY="your_openai_api_key" - Trên Windows PowerShell:
$env:OPENAI_API_KEY="your_openai_api_key"
Sau đó xác thực Modal tại máy bạn:
modal setupThao tác này sẽ mở cửa sổ trình duyệt và yêu cầu bạn đăng nhập Modal. Sau khi đăng nhập, hãy chấp thuận yêu cầu tạo token. Modal sẽ tự động thêm thông tin xác thực vào môi trường cục bộ của bạn.
Khi mọi thứ được thiết lập xong, bạn sẽ thấy thông báo thành công trong terminal xác nhận việc xác thực Modal đã hoàn tất.
2. Định nghĩa không gian làm việc Sandbox
Tiếp theo, tạo tệp Python như main.py và thêm các import cần thiết. Những import này mang vào OpenAI Agents SDK, các lớp cấu hình sandbox và client sandbox của 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, ModalSandboxClientOptionsGiờ chúng ta cần định nghĩa không gian làm việc sandbox. Trong ví dụ này, workspace gồm một dự án phân loại phiếu hỗ trợ nhỏ với README.md, một tệp ứng dụng và danh sách kiểm tra phát hành.
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 cho agent biết những tệp nào tồn tại bên trong sandbox. Điều này cung cấp cho agent một cấu trúc dự án thực để kiểm tra, chỉnh sửa và suy luận, thay vì chỉ dựa vào văn bản trong prompt.
Trong trường hợp này, agent sẽ có thể xem lại logic định tuyến phiếu hỗ trợ, kiểm tra tài liệu và thực hiện thay đổi bên trong không gian làm việc sandbox.
3. Tạo Sandbox Agent
Khi workspace đã được định nghĩa, hãy tạo agent chạy trên sandbox. SandboxAgent được thiết kế để làm việc với một workspace thực, nghĩa là nó có thể kiểm tra tệp, hiểu cấu trúc dự án và phản hồi dựa trên những gì có trong 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"),
)Ở đây, chúng ta đặt tên agent là Modal Sandbox Assistant và dùng mô hình gpt-5.4-mini để phản hồi nhanh hơn. Phần hướng dẫn yêu cầu agent kiểm tra không gian làm việc sandbox trước khi trả lời, điều này quan trọng khi câu trả lời phụ thuộc vào các tệp thực trong dự án.
Tham số default_manifest=manifest kết nối agent với workspace đã tạo trước đó. Thiết lập tool_choice="required" khuyến khích agent sử dụng các công cụ sandbox sẵn có thay vì chỉ trả lời dựa trên trí nhớ hoặc ngữ cảnh prompt.
4. Tạo Modal Sandbox Client
Tiếp theo, tạo client sandbox của Modal. Đây là kết nối giữa quy trình OpenAI Agents và sandbox của Modal, nơi việc truy cập tệp và thực thi lệnh thực sự diễn ra.
client = ModalSandboxClient()
options = ModalSandboxClientOptions(
app_name="openai-agents-modal-demo",
workspace_persistence="tar",
)ModalSandboxClient() cho agent biết sẽ sử dụng Modal làm nhà cung cấp sandbox. Điều này có nghĩa agent có thể chạy bên trong môi trường Modal cách ly thay vì chạy trực tiếp trên máy cục bộ của bạn.
ModalSandboxClientOptions kiểm soát cách cấu hình Modal sandbox. Ở đây, app_name đặt tên rõ ràng cho ứng dụng Modal, còn workspace_persistence="tar" cho Modal biết cách đóng gói và lưu trữ workspace trong quá trình chạy.
5. Khởi động phiên Sandbox
Khi client và tùy chọn đã sẵn sàng, tạo sandbox từ manifest và khởi động phiên.
sandbox = await client.create(
manifest=manifest,
options=options,
)
await sandbox.start()Lời gọi client.create() tạo một Modal sandbox mới bằng những tệp đã định nghĩa trong Manifest. Nghĩa là sandbox khởi chạy với cùng cấu trúc dự án, bao gồm README.md, src/app.py và docs/release-checks.md.
Sau đó, await sandbox.start() khởi động phiên sandbox. Tại thời điểm này, bạn có một workspace cách ly đang chạy trên Modal, sẵn sàng cho agent kiểm tra tệp, chạy lệnh và làm việc với dự án.
6. Chạy Agent trong Sandbox
Khi sandbox đã hoạt động, hãy chạy agent với sandbox đó bằng cách truyền phiên sandbox trực tiếp qua SandboxRunConfig. Điều này cho OpenAI Agents SDK biết rằng agent nên sử dụng workspace của Modal trong lần chạy.
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)Đây là lúc mọi thứ kết nối với nhau. Mô hình xử lý suy luận, còn sandbox cung cấp quyền truy cập vào các tệp trong workspace thực.
Trong ví dụ này, agent có thể kiểm tra dự án phân loại phiếu hỗ trợ, hiểu dịch vụ làm gì, xem ghi chú phát hành và trả lời ngắn gọn dựa trên các tệp trong Modal sandbox.
7. Dọn dẹp Sandbox
Sau khi agent chạy xong, hãy xóa sandbox để tránh để phiên không dùng tới chạy trên Modal.
await client.aclose(sandbox)Thao tác này loại bỏ phiên sandbox sau khi hoàn tất công việc. Đây là thói quen tốt vì các phiên sandbox có thể tiêu tốn tài nguyên tính toán khi còn hoạt động.
Trong dự án thực, bạn nên đặt thao tác này trong khối finally. Như vậy, việc dọn dẹp vẫn diễn ra ngay cả khi lời gọi agent thất bại hoặc script gặp lỗi.
8. Ví dụ mã hoàn chỉnh
Dưới đây là toàn bộ script ở một nơi. Script tạo workspace, khởi chạy Modal sandbox, chạy agent bên trong, in đầu ra cuối cùng, rồi dọn dẹp phiên 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())Script này tuân theo cấu trúc sandbox hiện tại của OpenAI và dùng Modal làm backend thực thi. Logic agent nằm trong ứng dụng Python của bạn, còn workspace thực chạy bên trong Modal sandbox.
Khối finally quan trọng vì nó đóng và xóa sandbox ngay cả khi lần chạy agent thất bại. Điều này giúp giữ môi trường Modal của bạn sạch sẽ và tránh phiên dư thừa.
9. Kiểm thử ứng dụng tại máy
Khi script đã sẵn sàng, hãy chạy cục bộ từ terminal trong cùng thư mục nơi lưu main.py:
python main.pyNếu mọi thứ được cấu hình đúng, script sẽ tạo Modal sandbox, nạp manifest vào đó, chạy OpenAI agent với workspace, in phản hồi rồi dọn dẹp sandbox.
Bạn sẽ thấy đầu ra tương tự như sau:
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.Lần chạy có thể mất vài giây để hoàn tất. Trong lúc chạy, hãy mở bảng điều khiển Modal của bạn, nhấp vào ứng dụng openai-agents-modal-demo và kiểm tra log. Đây là cách hữu ích để xác nhận sandbox đã được tạo, khởi động, được agent sử dụng và dọn dẹp thành công.
10. Tạo ứng dụng web tương tác
Script đầu tiên là tĩnh, nghĩa là chúng ta chỉ có thể gửi một yêu cầu, nhận một phản hồi rồi dừng. Để dự án dễ dùng hơn, ta có thể biến nó thành ứng dụng web tương tác bằng Gradio. Điều này cho phép chúng ta trò chuyện với sandbox agent, hỏi tiếp, tạo hoặc chỉnh sửa tệp và chạy kiểm thử từ giao diện trình duyệt đơn giản.
Đầu tiên, cài đặt phiên bản Gradio mới nhất:
pip install gradioSau đó tạo tệp mới tên app.py và sao chép mã ứng dụng Gradio (OpenAI-Agents-in-Modal/app.py) vào đó. Ứng dụng này dùng cùng thiết lập OpenAI Agents và Modal Sandbox, nhưng bọc trong giao diện chat. Mã cũng tái sử dụng phiên sandbox khi có thể, nên mỗi tin nhắn không cần tạo sandbox hoàn toàn mới từ đầu.
Chạy ứng dụng bằng:
python app.pyBạn sẽ thấy URL cục bộ trong terminal:
* Running on local URL: http://127.0.0.1:7860
* To create a public link, set share=True in launch().Mở URL cục bộ trong trình duyệt để dùng ứng dụng chat. Bạn có thể yêu cầu agent kiểm tra dự án, giải thích dịch vụ làm gì, tạo tệp trợ giúp mới, chỉnh sửa tệp hiện có hoặc chạy kiểm thử bên trong Modal sandbox.
Ví dụ, đầu tiên tôi yêu cầu giải thích dịch vụ của dự án làm gì, và sau vài giây, nó trả về phản hồi chi tiết dựa trên các tệp trong sandbox.
Sau đó tôi yêu cầu agent tạo tệp trợ giúp định tuyến mới. Yêu cầu này mất lâu hơn một chút vì agent phải chỉnh sửa workspace sandbox, thêm kiểm thử và chạy bộ kiểm thử.
Agent đã tạo src/routing_rules.py, thêm tệp kiểm thử mới tại tests/test_routing_rules.py, và xác minh thay đổi bằng pytest. Cả 6 kiểm thử đều vượt qua, xác nhận trình trợ giúp mới hoạt động đúng và logic định tuyến phiếu hiện có vẫn nguyên vẹn.
Ở mức tổng quan, ứng dụng Gradio này cung cấp một frontend đơn giản để làm việc với agent OpenAI chạy bằng Modal. Người dùng gửi tin nhắn qua trình duyệt, ứng dụng chuyển đến SandboxAgent, agent làm việc bên trong Modal sandbox, và phản hồi cuối cùng được hiển thị lại trong giao diện chat.
Lời kết
OpenAI Agents cùng Modal Sandboxes mang đến cách gọn gàng để xây dựng ứng dụng agent có thể làm việc với tệp thực, chạy lệnh và trả về đầu ra hữu ích từ môi trường cách ly.
Quy trình thiết lập Modal khá mượt, và việc tạo sandbox cũng đơn giản. Khi mọi thứ đã kết nối, agent có thể kiểm tra dự án, tạo tệp trợ giúp định tuyến mới, thêm kiểm thử và xác nhận cả 6 kiểm thử đều vượt qua.
Tuy vậy, xây dựng ứng dụng tương tác và cấu hình mô hình tốn nhiều công sức hơn dự kiến. Các bước tạo tệp và kiểm thử cũng mất thời gian hơn vì sandbox của Modal đôi khi hết thời gian chờ. Tôi đã phải tăng timeout sandbox từ 300 giây lên 600 giây để cho agent đủ thời gian hoàn tất toàn bộ quy trình.
Một điểm khó nữa là logging và khả năng quan sát. Trong khi chờ agent hoàn thành, không phải lúc nào cũng rõ SDK Agents đang làm gì ở hậu trường. Ngay cả log của Modal đôi khi cũng không đủ chi tiết để hiểu liệu agent đang kiểm tra tệp, chỉnh sửa mã hay chạy kiểm thử.
Trong tương lai, sẽ hữu ích nếu có log agent chi tiết hơn, tương tự như khi làm việc với các công cụ như Claude Code, nơi bạn có thể theo dõi từng bước rõ ràng hơn.
Tổng thể, đây là quy trình mạnh mẽ để xây dựng ứng dụng agent trong sandbox, đặc biệt nếu agent của bạn cần làm việc với tệp, mã và đầu ra tạo sinh. Bạn có thể tìm toàn bộ dự án trên GitHub, clone về máy và tự chạy: kingabzpro/OpenAI-Agents-in-Modal.
Nếu bạn muốn học tường tận cách xây dựng hệ thống AI nâng cao, tôi khuyến nghị khóa học Building Scalable Agentic Systems của chúng tôi.