# OpenAI Agents SDK là gì? Khung điều phối đa agent bằng mã nguồn

> OpenAI Agents SDK là thư viện Python mã nguồn mở giúp xây dựng, điều phối luồng công việc đa agent, công cụ, guardrails và session hội thoại.

Nguồn: https://camnangai.com/ky-thuat/openai-agents-sdk-la-gi  
Xuất bản: 2026-11-17

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 (multi-agent workflows), tự động quản lý lượt thoại (turns),
  công cụ (tools), rào chắn an toàn (guardrails) và phiên làm việc (sessions).


Bằng cách bọc các lời gọi mô hình ngôn ngữ lớn (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.

![Khung phát triển OpenAI Agents SDK điều phối hệ thống đa agent bằng mã nguồn](https://camnangai.com/articles/openai-agents-sdk-la-gi/01-infographic-vn.webp)

## 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 |

![So sánh kiến trúc giữa gọi Responses API trực tiếp và runtime điều phối tự động của Agents SDK](https://camnangai.com/articles/openai-agents-sdk-la-gi/02-vn.webp)

## 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 (system prompt), 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 Pydantic `BaseModel` hoặc các kiểu dữ liệu tương thích `TypeAdapter`).
- `tool_use_behavior`: Quy định hành vi sau khi gọi công cụ, bao gồm `run_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ểu `ToolsToFinalOutputFunction` nhận danh sách `List[FunctionToolResult]` và trả về đối tượng `ToolsToFinalOutputResult(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 reset `tool_choice` về `"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`.

![Bộ ba thành phần cốt lõi: cấu hình Agent, vòng lặp điều phối của Runner và kết quả thực thi RunResult](https://camnangai.com/articles/openai-agents-sdk-la-gi/03-vn.webp)

```python
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

![Mô hình Handoff: chuyển giao quyền điều khiển và ngữ cảnh từ agent tiếp nhận sang agent chuyên trách](https://camnangai.com/articles/openai-agents-sdk-la-gi/04-vn.webp)

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:

1.  **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.
2.  **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_tools` giú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.

```python
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

![Hệ thống Guardrails kiểm tra song song dữ liệu đầu vào, đầu ra và can thiệp kịp thời trước khi gọi công cụ](https://camnangai.com/articles/openai-agents-sdk-la-gi/05-vn.webp)

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í token 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.
- **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 qua `RunConfig.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_guardrail` kiểm tra tham số trước khi chạy và `tool_output_guardrail` kiể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.

```python
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:

1.  **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.
2.  **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).

![Vòng tuần hoàn quản lý bộ nhớ phiên: tự động khôi phục lịch sử hội thoại và lưu trữ dữ liệu vào cơ sở dữ liệu](https://camnangai.com/articles/openai-agents-sdk-la-gi/06-vn.webp)

Đá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`.

```python
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 (fine-tuning) 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.

![Cấu trúc phân cấp Tracing ghi lại chi tiết các span từ lời gọi LLM, thực thi công cụ đến sự kiện handoff](https://camnangai.com/articles/openai-agents-sdk-la-gi/07-vn.webp)

## 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).

## Tài liệu tham khảo

- [openai/openai-agents-python: A lightweight, powerful framework for multi-agent workflows](https://github.com/openai/openai-agents-python)
- [OpenAI Agents SDK Documentation](https://openai.github.io/openai-agents-python/)
- [Quickstart - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/quickstart/)
- [Agents - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/agents/)
- [Handoffs - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/handoffs/)
- [Guardrails - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/guardrails/)
- [Sessions - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/sessions/)
- [Tracing - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/tracing/)
