OpenAI Agents SDK là thư viện mã nguồn mở Python (phiên bản v0.24.0, yêu cầu Python 3.10+) nhẹ nhưng mạnh mẽ, kế thừa và nâng cấp từ dự án thử nghiệm Swarm. Thư viện này được thiết kế để điều phối các luồng công việc đa agent ( workflows), tự động quản lý lượt thoại (turns), công cụ (tools), rào chắn an toàn () và phiên làm việc (sessions).
Bằng cách bọc các lời gọi (LLM) trong một runtime cấp cao, thư viện giúp bạn triển khai luồng xử lý phức tạp mà không cần tự viết các vòng lặp điều phối thủ công. SDK hoạt động theo triết lý ưu tiên Python (Python-first), cho phép bạn sử dụng cú pháp mã nguồn chuẩn của Python để kết nối và điều phối các agent.

Triết lý thiết kế và sự khác biệt với Responses API
Triết lý thiết kế của OpenAI Agents SDK tập trung vào hai yếu tố cốt lõi: thứ nhất, cung cấp đầy đủ các tính năng thiết yếu với một tập hợp các thành phần cơ bản (primitives) tối giản nhằm giúp bạn nhanh chóng nắm bắt và triển khai; thứ hai, đảm bảo hệ thống hoạt động hiệu quả ngay khi cài đặt (out-of-the-box) nhưng vẫn cho phép tùy biến sâu bằng mã nguồn Python thuần túy. Thay vì bắt buộc người dùng học các cơ chế đóng gói phức tạp, SDK tận dụng trực tiếp các cấu trúc lệnh và hàm của Python để chuỗi hóa cũng như điều phối các agent.
Về bản chất, OpenAI Agents SDK mặc định sử dụng Responses API để tương tác với các mô hình của OpenAI, nhưng hai cách tiếp cận này giải quyết các bài toán ở cấp độ khác nhau. Việc lựa chọn giữa Responses API trực tiếp và Agents SDK phụ thuộc vào mức độ kiểm soát luồng thực thi mà ứng dụng yêu cầu:
- Responses API trực tiếp: Phù hợp cho các luồng xử lý ngắn hạn, đơn lẻ, nơi nhà phát triển muốn tự quản lý vòng lặp execution loop, tự thực thi công cụ (tool dispatch) và tự xử lý trạng thái hội thoại.
- OpenAI Agents SDK: Được thiết kế cho các luồng công việc phức tạp, đa bước hoặc tạo ra các sản phẩm đầu ra (artifacts). SDK bọc mô hình trong một runtime cấp cao để tự động quản lý lượt tương tác, gọi công cụ, áp dụng rào chắn an toàn (guardrails), chuyển giao nhiệm vụ (handoffs) và duy trì bộ nhớ phiên (sessions).
Mặc định SDK tích hợp sâu với Responses API của OpenAI, nhưng thư viện hoàn toàn độc lập với nhà cung cấp (provider-agnostic). Thông qua các bộ thích ứng phụ trợ như any-llm và LiteLLM, SDK hỗ trợ kết nối và vận hành với hơn 100 mô hình ngôn ngữ lớn khác nhau ngoài OpenAI.
| Tiêu chí | Responses API trực tiếp | OpenAI Agents SDK |
|---|---|---|
| Quản lý vòng lặp (Execution loop) | Tự phát triển vòng lặp thủ công để gửi/nhận dữ liệu | Runtime tự động điều phối lượt thoại và thực thi công cụ |
| Xử lý trạng thái (Session/State) | Tự quản lý mảng tin nhắn và trạng thái ngữ cảnh | Tự động lưu trữ và phục hồi ngữ cảnh qua cơ chế Sessions |
| Điều phối đa agent | Tự lập trình logic chuyển đổi và định tuyến thủ công | Hỗ trợ sẵn mô hình Manager (Agents as tools) và Handoffs |
| Trường hợp sử dụng tối ưu | Luồng tương tác đơn lẻ, xử lý phản hồi mô hình tức thì | Luồng công việc đa bước, ứng dụng Sandbox, Voice và đa Agent |

Primitives cốt lõi: Agent, Runner và vòng lặp thực thi
Khối xây dựng cơ bản nhất trong SDK là Agent. Một Agent đại diện cho một mô hình ngôn ngữ lớn (LLM) được cấu hình kèm theo hướng dẫn hệ thống (instructions), danh sách công cụ (tools), các rào chắn an toàn (guardrails), cơ chế chuyển giao (handoffs) và cấu hình kiểu dữ liệu đầu ra (output_type).
Các thuộc tính cấu hình quan trọng của một Agent bao gồm:
name: Tên định danh của agent.instructions: Lời gọi hệ thống (), hỗ trợ cả chuỗi tĩnh lẫn hàm tạo hướng dẫn động (dynamic_instructions).model: Mô hình LLM được chỉ định sử dụng.tools: Danh sách các công cụ mà agent có quyền gọi.handoffs: Danh sách các agent chuyên biệt mà agent hiện tại có thể chuyển giao quyền xử lý.input_guardrails/output_guardrails: Các rào chắn kiểm tra dữ liệu đầu vào và đầu ra.output_type: Định dạng dữ liệu cấu trúc đầu ra (sử dụng các lớp PydanticBaseModelhoặc các kiểu dữ liệu tương thíchTypeAdapter).tool_use_behavior: Quy định hành vi sau khi gọi công cụ, bao gồmrun_llm_again(mặc định gửi kết quả về lại LLM),stop_on_first_tool(lấy kết quả của công cụ đầu tiên làm đầu ra cuối),StopAtTools(dừng khi gặp các công cụ chỉ định), hoặc hàm tùy biến kiểuToolsToFinalOutputFunctionnhận danh sáchList[FunctionToolResult]và trả về đối tượngToolsToFinalOutputResult(is_final_output=..., final_output=...).reset_tool_choice: Mặc định đặt làTrue. Khi cấu hình mô hình ép buộc gọi công cụ (ModelSettings(tool_choice="my_tool")hoặc"required"), nếu không resettool_choicevề"auto"sau lần gọi công cụ đầu tiên, LLM sẽ tiếp tục phát lệnh gọi chính công cụ đó trong lượt sau, tạo ra vòng lặp vô tận.
Để vận hành Agent, SDK cung cấp thành phần Runner. Khi gọi Runner.run() (bất đồng bộ) hoặc Runner.run_sync() (đồng bộ), Runner sẽ khởi chạy một vòng lặp thực thi tự động. Vòng lặp này gửi prompt ban đầu đến LLM và giải mã phản hồi; nếu LLM yêu cầu gọi công cụ, Runner sẽ thực thi hàm Python tương ứng, gửi lại kết quả cho LLM và tiếp tục tiến trình cho đến khi hoàn thành công việc và trả về đối tượng RunResult.

from agents import Agent, Runner
from agents.decorators import tool
@tool
def get_weather(city: str) -> str:
"""Trả về thông tin thời tiết cho thành phố được chỉ định."""
return f"Thời tiết tại {city} có nắng và nhiệt độ thuận lợi."
# Khởi tạo Agent với công cụ đã định nghĩa
weather_agent = Agent(
name="Weather Assistant",
instructions="Bạn là trợ lý thời tiết. Hãy trả lời ngắn gọn.",
model="gpt-5-nano",
tools=[get_weather],
)
# Thực thi agent bằng Runner.run_sync
result = Runner.run_sync(weather_agent, "Thời tiết ở Hà Nội hiện tại như thế nào?")
print(result.final_output)Cơ chế Handoffs và điều phối đa agent

Khi xây dựng các hệ thống đa agent, OpenAI Agents SDK hỗ trợ hai mô hình thiết kế chính:
- Manager Pattern (Agents as tools): Một agent trung tâm đóng vai trò quản lý, gọi các agent chuyên biệt cấp dưới như các công cụ thông qua phương thức
agent.as_tool(). Agent quản lý giữ quyền kiểm soát xuyên suốt hội thoại. - Handoffs Pattern: Các agent ngang hàng chuyển giao toàn bộ quyền điều khiển hội thoại cho một agent khác. Đây là mô hình phân tán, giúp các agent tập trung vào nhiệm vụ chuyên môn duy nhất.
Cơ chế Handoffs được hiển thị dưới dạng một công cụ đối với LLM. Ví dụ, nếu có một handoff hướng đến agent có tên Refund Agent, SDK sẽ tạo ra một công cụ tương ứng tên là transfer_to_refund_agent. Khi LLM quyết định kích hoạt công cụ này, agent nhận chuyển giao sẽ thừa hưởng toàn bộ lịch sử hội thoại và tiếp quản lượt phản hồi tiếp theo.
Bạn có thể tùy biến chi tiết hành vi chuyển giao thông qua hàm handoff() với các tham số điều khiển:
tool_name_override/tool_description_override: Ghi đè tên và mô tả của công cụ chuyển giao.on_handoff: Hàm callback được kích hoạt ngay khi quá trình handoff xảy ra, giúp thực thi các tác vụ chuẩn bị dữ liệu.input_type: Định nghĩa schema Pydantic cho dữ liệu trích xuất từ LLM khi chuyển giao (ví dụ: lý do chuyển giao, độ ưu tiên).input_filter: Hàm lọc lịch sử hội thoại trước khi truyền cho agent tiếp theo (ví dụ:handoff_filters.remove_all_toolsgiúp loại bỏ toàn bộ các item gọi công cụ trước đó).nest_handoff_history: Cấu hình đóng gói tóm tắt lịch sử hội thoại khi chuyển giao.
from pydantic import BaseModel
from agents import Agent, handoff, RunContextWrapper
class EscalationData(BaseModel):
reason: str
priority: str
def log_escalation(ctx: RunContextWrapper[None], input_data: EscalationData):
print(f"[Handoff] Chuyển giao cấp cao. Lý do: {input_data.reason}, Độ ưu tiên: {input_data.priority}")
billing_agent = Agent(name="Billing Agent", instructions="Xử lý thanh toán.")
refund_agent = Agent(name="Refund Agent", instructions="Xử lý yêu cầu hoàn tiền.")
# Handoff có sử dụng input_type và callback on_handoff
custom_refund_handoff = handoff(
agent=refund_agent,
on_handoff=log_escalation,
input_type=EscalationData,
tool_name_override="transfer_to_refund_expert",
)
triage_agent = Agent(
name="Triage Agent",
instructions="Tiếp nhận thông tin và chuyển giao cho đúng bộ phận.",
handoffs=[billing_agent, custom_refund_handoff],
)Thiết lập rào chắn an toàn với Guardrails

Guardrails trong OpenAI Agents SDK là cơ chế chạy kiểm tra và xác thực dữ liệu đầu vào của người dùng hoặc dữ liệu đầu ra của agent. Mục đích của guardrail là phát hiện các nội dung không phù hợp, chặn các yêu cầu vi phạm chính sách bằng các mô hình nhỏ/rẻ tiền trước khi kích hoạt các mô hình lớn, từ đó tối ưu chi phí và đảm bảo an toàn hệ thống.
SDK phân chia Guardrails theo ranh giới quy trình (Workflow boundaries):
- Input guardrails: Áp dụng cho dữ liệu đầu vào ban đầu của người dùng và chỉ chạy trên agent đầu tiên trong chuỗi thực thi. Input guardrails hỗ trợ 2 chế độ:
- Parallel execution (
run_in_parallel=True, mặc định): Guardrail và agent chạy song song để tối ưu độ trễ. Nếu vi phạm, agent sẽ bị hủy nhưng có thể đã tiêu tốn một số token trước đó. - Blocking execution (
run_in_parallel=False): Guardrail chạy hoàn tất trước khi agent bắt đầu. Nếu vi phạm, agent không được khởi chạy, giúp tiết kiệm chi phí tuyệt đối.
- Parallel execution (
- Output guardrails: Áp dụng cho kết quả đầu ra cuối cùng của agent cuối cùng trong chuỗi. Khi kích hoạt rào chắn (tripwire), hệ thống loại bỏ kết quả bị từ chối nhưng duy trì lịch sử các công cụ đã thực thi xong. Khi kết quả của một công cụ (terminal function-tool output) bị Output Guardrail chặn, SDK sẽ thay thế phần nội dung đó bằng văn bản mặc định
"Output withheld by an output guardrail."trước khi cho phép bạn tùy biến thông báo quaRunConfig.output_guardrail_blocked_message. - Tool guardrails: Áp dụng trực tiếp trên từng lượt gọi công cụ hàm (
tool_input_guardrailkiểm tra tham số trước khi chạy vàtool_output_guardrailkiểm tra kết quả trả về của công cụ).
Khi kiểm tra phát hiện vi phạm, hệ thống sẽ ném các ngoại lệ bẫy tín hiệu (Tripwire) tương ứng tùy theo ranh giới xảy ra vi phạm: InputGuardrailTripwireTriggered cho đầu vào, OutputGuardrailTripwireTriggered cho đầu ra, hoặc ToolInputGuardrailTripwireTriggered và ToolOutputGuardrailTripwireTriggered cho công cụ hàm để dừng luồng thực thi ngay lập tức.
from pydantic import BaseModel
from agents import Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered, RunContextWrapper, Runner
from agents.decorators import input_guardrail
class ContentModerationOutput(BaseModel):
is_violation: bool
reasoning: str
guardrail_agent = Agent(
name="Moderator",
instructions="Kiểm tra xem đầu vào có chứa nội dung gian lận không.",
output_type=ContentModerationOutput,
)
@input_guardrail(run_in_parallel=False) # Sử dụng chế độ Blocking để tiết kiệm chi phí
async def check_content_safety(
ctx: RunContextWrapper[None], agent: Agent, input: str
) -> GuardrailFunctionOutput:
res = await Runner.run(guardrail_agent, input, context=ctx.context)
return GuardrailFunctionOutput(
output_info=res.final_output,
tripwire_triggered=res.final_output.is_violation,
)
main_agent = Agent(
name="Main Assistant",
instructions="Giải đáp câu hỏi khách hàng.",
input_guardrails=[check_content_safety],
)Quản lý trạng thái và phiên hội thoại với Sessions
Cơ chế Session trong OpenAI Agents SDK đảm nhận nhiệm vụ lưu trữ và duy trì lịch sử hội thoại xuyên suốt nhiều lượt chạy (Runner.run), loại bỏ hoàn toàn việc nhà phát triển phải thủ công trích xuất và nối mảng dữ liệu đầu vào (không cần gọi .to_input_list()).
Vòng lặp hoạt động của Session diễn ra qua các bước:
- Trước lượt chạy: Runner tự động lấy lịch sử hội thoại từ Session thông qua
session.get_items()và chèn vào đầu chuỗi dữ liệu đầu vào. - Sau lượt chạy: Toàn bộ các item mới phát sinh trong lượt (câu hỏi người dùng, phản hồi của assistant, các lượt gọi công cụ và kết quả công cụ) tự động được ghi lưu lại vào Session.
SDK tích hợp sẵn nhiều backend lưu trữ phiên làm việc đáp ứng các môi trường triển khai khác nhau:
SQLiteSession/AsyncSQLiteSession: Bộ lưu trữ nhẹ, hỗ trợ file cục bộ hoặc in-memory, tối ưu cho phát triển thử nghiệm.RedisSession: Lưu trữ phân tán, độ trễ thấp, phù hợp cho hạ tầng chia sẻ bộ nhớ giữa nhiều microservices/workers.SQLAlchemySession: Chuẩn kết nối production cho các cơ sở dữ liệu quan hệ (PostgreSQL, MySQL, SQLite...).MongoDBSession: Lưu trữ tài liệu cho ứng dụng quy mô lớn, hỗ trợ MongoDB Atlas.DaprSession: Tích hợp hạ tầng cloud-native thông qua Dapr sidecar, hỗ trợ hơn 30 state store backend.OpenAIConversationsSession: Lưu trữ lịch sử trực tiếp trên máy chủ OpenAI Conversations API.OpenAIResponsesCompactionSession: Bộ bọc tự động nén lịch sử hội thoại dài bằng Responses API (responses.compact).EncryptedSession: Bộ bọc mã hóa dữ liệu phiên transparent đi kèm cấu hình thời gian sống (TTL).

Đáng chú ý, đối với OpenAIResponsesCompactionSession, tiến trình nén tự động (auto-compaction) diễn ra đồng bộ ở cuối lượt chạy. Việc này có thể khiến luồng phát dữ liệu streaming (run.stream_events()) tiếp tục giữ kết nối mở thêm vài giây sau khi token cuối cùng đã xuất ra. Đối với các ứng dụng giao tiếp thời gian thực đòi hỏi tối ưu độ trễ (latency), giải pháp tốt nhất là tắt chế độ tự động nén (should_trigger_compaction=lambda _: False) và thực hiện gọi session.run_compaction() thủ công bất đồng bộ giữa các lượt chạy.
Bạn có thể thực hiện các thao tác quản lý bộ nhớ trực tiếp thông qua các phương thức get_items(), add_items(), pop_item() (hữu ích khi cần xóa/sửa lượt hội thoại lỗi trước đó) và clear_session(). Để giới hạn lượng lịch sử tải vào mỗi lượt, bạn có thể thiết lập SessionSettings(limit=N) hoặc tùy biến logic hợp nhất lịch sử thông qua callback RunConfig.session_input_callback.
import asyncio
from agents import Agent, Runner, SQLiteSession
async def main():
agent = Agent(name="Assistant", instructions="Trả lời thật ngắn gọn.")
# Khởi tạo phiên lưu trữ SQLite duy trì dữ liệu vào file conversations.db
session = SQLiteSession("user_session_999", "conversations.db")
# Lượt tương tác 1
res1 = await Runner.run(agent, "Tòa nhà Empire State ở thành phố nào?", session=session)
print(f"Lượt 1: {res1.final_output}") # "New York"
# Lượt tương tác 2 - Agent tự động khôi phục ngữ cảnh từ session
res2 = await Runner.run(agent, "Tòa nhà đó cao bao nhiêu mét?", session=session)
print(f"Lượt 2: {res2.final_output}") # Trả lời về chiều cao của tòa nhà Empire State
if __name__ == "__main__":
asyncio.run(main())Khả năng quan sát và gỡ lỗi bằng Tracing
Khả năng quan sát (Observability) là yếu tố bắt buộc đối với hạ tầng AI trong môi trường sản xuất. OpenAI Agents SDK tích hợp sẵn hệ thống Tracing chuẩn hóa, tự động ghi lại toàn bộ tiến trình thực thi dưới dạng một phân cấp gồm các traces và spans chi tiết đến từng mắt xích vận hành.
Ở cấp độ hạ tầng, SDK tạo ra các khoảng thời gian thực thi (spans) riêng biệt cho từng lời gọi API tới LLM, từng lượt thực thi công cụ cục bộ (function tool dispatch), các quyết định đánh giá guardrail và từng sự kiện chuyển giao nhiệm vụ (handoff). Toàn bộ dữ liệu này có thể được truy xuất và xuất ra (export) theo chuẩn OpenTelemetry hoặc đẩy trực tiếp lên hệ thống quản trị của OpenAI Platform.
Việc tích hợp Tracing mang lại ba lợi ích kỹ thuật quan trọng:
- Gỡ lỗi và trực quan hóa luồng công việc phức tạp: Cho phép kỹ sư xem xét lại chính xác chuỗi suy luận (chain-of-thought), tham số công cụ và nguyên nhân khiến một agent đưa ra quyết định sai hoặc vi phạm guardrail.
- Giám sát hiệu năng và chi phí: Phân tích độ trễ (latency) của từng span và theo dõi chính xác lượng token tiêu thụ trên từng agent chuyên biệt trong các hệ thống đa agent.
- Thu thập dữ liệu cho vòng đời LLM (Dataset Distillation & Fine-tuning): Dữ liệu vết thực thi thu được từ môi trường thực tế là nguồn nguyên liệu chuẩn xác để thực hiện đánh giá (evaluation), tinh chỉnh () hoặc chắt lọc mô hình (distillation) nhằm tối ưu hóa chi phí vận hành lâu dài.

Khi nào nên dùng OpenAI Agents SDK?
OpenAI Agents SDK mang lại giá trị cao nhất khi ứng dụng của bạn vượt quá giới hạn của một lượt gọi LLM đơn lẻ. Bạn nên triển khai SDK khi hệ thống đòi hỏi quy trình xử lý đa bước dài hạn, cần phân chia nhiệm vụ cho nhiều agent chuyên biệt hợp tác qua cơ chế Handoffs hoặc Manager, hoặc cần tích hợp các rào chắn an toàn (guardrails) để kiểm soát chi phí và rủi ro dữ liệu.
Ngoài ra, SDK là lựa chọn tối ưu khi ứng dụng cần quản lý bộ nhớ phiên (sessions) bền vững trên các cơ sở dữ liệu doanh nghiệp (PostgreSQL, Redis, MongoDB), vận hành agent trong môi trường mã/tệp cô lập (Sandbox agents), hoặc xây dựng các đường ống thoại thời gian thực độ trễ thấp (Realtime/Voice agents).