OpenAI Agents SDK là gì: hướng dẫn dựng hệ thống multi-agent

Thử hình dung anh chị gọi tổng đài một hãng điện máy. Người nghe máy đầu tiên vừa phải báo giá, vừa nhận bảo hành, vừa xử lý khiếu nại. Hỏi câu nào cũng "anh chờ em xíu", rồi trả lời sai một nửa. Lần sau gọi, anh chị chỉ mong có ai đó bấm nút chuyển máy sang đúng người.

Chatbot một agent ôm mọi việc cũng y như vậy. OpenAI Agents SDK là cách OpenAI đưa cho lập trình viên cái nút chuyển máy đó, kèm luôn bảo vệ ở cửa và cuốn sổ ghi chép.

Đọc nhanh trong 30 giây

• OpenAI Agents SDK là thư viện Python mã nguồn mở (giấy phép MIT) của OpenAI, công bố ngày 11/03/2025, dùng để dựng nhiều agent phối hợp với nhau.
• Bốn khái niệm cốt lõi: Agent, Handoff (chuyển việc), Guardrail (kiểm tra an toàn), Tracing (ghi vết).
• Cài bằng pip install openai-agents, cần Python 3.9 trở lên và một khóa API.
• Hợp với đội kỹ thuật quen Python muốn đi từ một chatbot lên vài agent chia việc.

OpenAI Agents SDK là gì?

OpenAI Agents SDK là bộ khung nhẹ của OpenAI để viết agent bằng Python, giấy phép MIT. Theo OpenAI, SDK này kế thừa Swarm, bản thử nghiệm họ phát hành năm trước. Hiện SDK chỉ có cho Python, bản Node.js sẽ ra sau.

Cùng ngày 11/03/2025, OpenAI ra mắt Responses API và các công cụ dựng sẵn: tìm kiếm web, tìm trong file, điều khiển máy tính. Agents SDK là phần điều phối đứng trên các mảnh đó.

Một chi tiết dễ bỏ qua: README ghi SDK chạy được với mọi nhà cung cấp mô hình hỗ trợ định dạng Chat Completions API của OpenAI. Nghĩa là anh chị không bị trói vào mô hình của OpenAI.

Bốn mảnh ghép: agent, handoff, guardrail, tracing

Agents SDK chỉ có bốn khái niệm. Cứ hình dung một văn phòng có quầy lễ tân.

Bốn khái niệm cốt lõi, ví như một văn phòng có người tiếp khách.

1. Agent là một nhân viên: một mô hình ngôn ngữ được giao hướng dẫn, công cụ, guardrail và danh sách đồng nghiệp có thể chuyển việc.
2. Handoff là nút chuyển máy. Lễ tân gặp câu hỏi hóa đơn thì chuyển kế toán, gặp chuyện máy lạnh hỏng thì chuyển kỹ thuật.
3. Guardrail là bảo vệ ở cửa. Nó kiểm tra đầu vào và đầu ra, chặn yêu cầu lạc đề hoặc câu trả lời sai định dạng.
4. Tracing là sổ giao ca. Mọi lượt chạy đều được ghi lại để xem ai đã làm gì, gọi công cụ nào, lúc nào.

Vòng lặp agent chạy thế nào?

Khi gọi Runner.run(), OpenAI Agents SDK chạy một vòng lặp cho tới khi có kết quả cuối. Theo README, mỗi vòng gồm các bước sau.

Runner lặp tới khi có kết quả cuối hoặc chạm giới hạn max_turns.

1. Gọi mô hình với cấu hình của agent hiện tại và lịch sử tin nhắn.
2. Mô hình trả lời, có thể kèm yêu cầu gọi công cụ.
3. Nếu đã có kết quả cuối thì dừng và trả về.
4. Nếu có handoff, đổi sang agent mới rồi quay lại bước 1.
5. Nếu có lời gọi công cụ, chạy công cụ, thêm kết quả vào lịch sử rồi quay lại bước 1.

Tham số max_turns giới hạn số vòng, giống hẹn giờ trên lò vi sóng: tới giờ là ngắt, agent không thể chạy mãi đốt tiền.

Còn output_type là cái khuôn đổ bánh. Khai báo kiểu dữ liệu, ví dụ phiếu yêu cầu có đủ tên khách, số điện thoại, nội dung, thì vòng lặp chỉ dừng khi mô hình trả về đúng khuôn đó. SDK dùng structured outputs để ép mô hình vào khuôn.

Mẹo

Dùng output_type ngay từ agent đầu tiên. Khi đầu ra luôn có cùng các trường, anh chị đẩy thẳng vào bảng tính hay phần mềm CRM được, khỏi viết thêm code bóc tách câu chữ.

Cài OpenAI Agents SDK và chạy agent đầu tiên

Yêu cầu: Python 3.9 trở lên (theo file pyproject.toml của bản đầu) và một khóa API OpenAI.

Bốn bước từ máy trống tới agent đầu tiên biết làm thơ.

1. Tạo môi trường Python riêng:

python -m venv env
source env/bin/activate

2. Cài SDK:

pip install openai-agents

3. Đặt biến môi trường OPENAI_API_KEY bằng khóa API của anh chị.

4. Chạy thử ví dụ "hello world" trong README:

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

Thử với việc thật: tổng đài chia email khách

Việc 1: agent tiếp nhận chuyển việc cho agent chuyên môn. README có ví dụ handoff theo ngôn ngữ: agent tiếp nhận đọc câu hỏi rồi chuyển cho agent nói tiếng Tây Ban Nha hoặc tiếng Anh. Đổi sang bối cảnh doanh nghiệp Việt, ta dựng một agent tiếp nhận email, chuyển sang agent "báo giá" hoặc agent "khiếu nại":

from agents import Agent, Runner
import asyncio

bao_gia = Agent(name="Agent báo giá", instructions="Chỉ trả lời câu hỏi về giá và gói dịch vụ.")
khieu_nai = Agent(name="Agent khiếu nại", instructions="Tiếp nhận khiếu nại, tóm tắt vấn đề, xin lỗi lịch sự.")

tiep_nhan = Agent(
    name="Agent tiếp nhận",
    instructions="Đọc yêu cầu của khách và chuyển cho agent phù hợp.",
    handoffs=[bao_gia, khieu_nai],
)

async def main():
    result = await Runner.run(tiep_nhan, input="Bên mình báo giá gói thuê văn phòng 6 tháng giúp em.")
    print(result.final_output)

asyncio.run(main())

Việc 2: cho agent gọi hàm của công ty. Decorator @function_tool biến một hàm Python thành công cụ cho agent. Ví dụ trong README là hàm tra thời tiết. Ngoài đời, đó có thể là hàm tra tồn kho hay tra trạng thái đơn hàng trong cơ sở dữ liệu nội bộ. Agent tự quyết lúc nào cần gọi, anh chị chỉ cần viết hàm và mô tả rõ nó làm gì.

Cần dè chừng điều gì?

Lưu ý

• Mới ra, đổi nhanh. Bản phát hành đầu là 0.0.2 ngày 11/03/2025. Dùng cho dự án thật thì khóa phiên bản.
• Chi phí API. Mỗi vòng lặp là một lần gọi mô hình. Ba agent chuyển việc qua lại có thể tốn gấp mấy lần một câu hỏi đơn. Đặt max_turns và theo dõi qua tracing.
• Tracing bật sẵn. Tài liệu có hướng dẫn tùy chỉnh hoặc tắt, và hỗ trợ gửi tới Logfire, AgentOps, Braintrust. Với dữ liệu khách hàng, xem kỹ phần này trước khi chạy thật.
• Chỉ có Python. Đội dùng JavaScript phải chờ bản Node.js.
• Guardrail không thay quy trình duyệt. Guardrail là một lớp lọc do mô hình hoặc code thực hiện, vẫn có thể lọt.

Nhận xét của chuyên gia

Khi tư vấn dựng chatbot cho doanh nghiệp, câu sếp hay hỏi nhất sau khi chạy thật là: "Sao nó lại trả lời khách như thế?". Với một chatbot tự viết, đội kỹ thuật thường không có câu trả lời. OpenAI Agents SDK có tracing bật sẵn, nên ít nhất đã có cuốn sổ để mở ra xem từng bước.

Hợp với ai: đội kỹ thuật nhỏ đã quen Python, muốn chia một chatbot ôm đồm thành vài agent chuyên môn; doanh nghiệp có việc thật sự nhiều nhánh như chăm sóc khách hàng, phân loại yêu cầu nội bộ.

Chưa hợp với ai: doanh nghiệp chưa có người viết code; luồng tự động cố định kiểu "nhận form, gửi email", vì công cụ kéo thả hoặc một script đơn giản rẻ và dễ bảo trì hơn. Rủi ro tôi luôn nhắc: chi phí phình vì agent gọi nhau nhiều vòng, dữ liệu khách đi qua API và hệ thống tracing bên ngoài, thư viện còn ở giai đoạn rất sớm.

Cách bắt đầu của tôi: chọn một việc lặp lại có quy tắc rõ, ví dụ phân loại email đến. Dựng một agent tiếp nhận và hai agent chuyên môn. Chạy song song với người làm thật trong hai tuần, so kết quả rồi mới tính mở rộng.

Muốn so với một hướng dựng agent khác, anh chị đọc bài OpenManus là gì, hoặc xem bức tranh chung trên dòng thời gian AI.

Một câu để nhớ: nhiều agent không phải để trông xịn hơn, mà để mỗi việc có đúng một người chịu trách nhiệm.

Câu hỏi thường gặp

OpenAI Agents SDK có miễn phí không?

Thư viện miễn phí theo giấy phép MIT. Phần tốn tiền là lượt gọi mô hình qua API, tính theo bảng giá của nhà cung cấp mô hình anh chị dùng.

OpenAI Agents SDK khác gì Swarm?

OpenAI cho biết Agents SDK là bản kế thừa Swarm, bộ khung thử nghiệm trước đó. Agents SDK thêm guardrail, tracing và được OpenAI định hướng dùng cho sản phẩm thật.

Có dùng được mô hình không phải của OpenAI không?

Có. README ghi SDK tương thích với mọi nhà cung cấp hỗ trợ định dạng Chat Completions API của OpenAI.

Cần biết lập trình để dùng OpenAI Agents SDK không?

Cần. Đây là thư viện Python, người dùng phải viết code để khai báo agent, công cụ và chạy vòng lặp.

Nguồn: openai/openai-agents-python trên GitHub, 11/03/2025.