Giải mã OpenAI’s Agents SDK: Hướng dẫn

OpenAI đang giới thiệu một số sản phẩm mới: Responses API, các công cụ tích hợp cho tìm kiếm web và tệp, một công cụ sử dụng máy tính và Agents SDK nguồn mở. Trong khi Responses API cho phép nhà phát triển xây dựng tác nhân dựa trên công nghệ của hãng, Agents SDK có thể giúp họ liên kết tác nhân với các công cụ và quy trình web khác, thực hiện các “workflow” đáp ứng tự động những gì người dùng hoặc doanh nghiệp mong muốn.

Năm 2025 thường được xem là “Năm của tác nhân”, và động thái của OpenAI được nhìn nhận là bước tiến quan trọng cho ngành. Agents SDK cho phép nhà phát triển dễ dàng tận dụng các cải tiến mới nhất của OpenAI (chẳng hạn như năng lực suy luận được cải thiện, tương tác đa phương thức và các kỹ thuật an toàn mới) trong các kịch bản thực tế gồm nhiều bước. Đối với các nhà phát triển LLM và những người xây dựng tác nhân AI, Agents SDK cung cấp một tập hợp “khối dựng” để tạo và quản lý các hệ thống AI tự chủ của riêng họ.

Ý nghĩa của Agents SDK nằm ở khả năng giải quyết các thách thức khi triển khai tác nhân AI trong môi trường sản xuất. Trước đây, việc chuyển các năng lực mạnh mẽ của LLM thành những quy trình nhiều bước thường tốn công sức, đòi hỏi viết nhiều quy tắc tùy chỉnh, thiết kế chuỗi prompt tuần tự, và thử–sai trong khi thiếu công cụ quan sát phù hợp. Với Agents SDK và các công cụ API mới liên quan như Responses API, OpenAI đặt mục tiêu đơn giản hóa đáng kể quy trình này, giúp nhà phát triển xây dựng các tác nhân phức tạp và đáng tin cậy hơn với ít nỗ lực hơn.

Agents SDK là gì

OpenAI đang trở lại với nguồn mở theo cách mạnh mẽ thông qua việc phát hành Agents SDK, một bộ công cụ được thiết kế để giúp nhà phát triển quản lý, phối hợp và tối ưu hóa các workflow của tác nhân — thậm chí xây dựng tác nhân chạy bằng những mô hình không thuộc OpenAI như đối thủ Anthropic và Google, hoặc các mô hình nguồn mở từ DeepSeek, Qwen, Mistral và họ Llama của Meta.

Vì sao sử dụng Agents SDK

SDK có hai nguyên tắc thiết kế cốt lõi:

1. Tính năng đủ phong phú để đáng dùng, nhưng số lượng nguyên thủy đủ ít để học nhanh.
2. Hoạt động tốt ngay khi dùng mặc định, nhưng bạn có thể tùy chỉnh chính xác những gì sẽ diễn ra.

Các tính năng chính của SDK:

• Vòng lặp tác nhân: Vòng lặp tích hợp xử lý việc gọi công cụ, gửi kết quả cho LLM và lặp lại cho đến khi LLM hoàn tất.
• Ưu tiên Python: Dùng các tính năng ngôn ngữ dựng sẵn để điều phối và xâu chuỗi tác nhân, không cần học các trừu tượng mới.
• Chuyển giao: Tính năng mạnh để phối hợp và ủy quyền giữa nhiều tác nhân.
• Rào chắn: Chạy kiểm tra và xác thực đầu vào song song với tác nhân, dừng sớm nếu kiểm tra thất bại.
• Công cụ hàm: Biến bất kỳ hàm Python nào thành công cụ, với sinh lược đồ tự động và xác thực dựa trên Pydantic.
• Truy vết: Truy vết tích hợp cho phép bạn trực quan hóa, gỡ lỗi và giám sát workflow, cũng như dùng bộ công cụ đánh giá, tinh chỉnh và chưng cất của OpenAI.

Cách sử dụng Openai Agents SDK

1. Thiết lập môi trường Python của bạn

python -m venv env
source env/bin/activate

2. Cài đặt Agents SDK

pip install openai-agents

3. thiết lập biến môi trường OPENAI_API_KEY

Tự do thiết lập OPENAI_API_KEY API từ CometAPI

• Đăng nhập vào cometapi.com. Nếu bạn chưa là người dùng, vui lòng đăng ký trước
• Lấy khóa API thông tin xác thực của giao diện. Nhấp “Add Token” tại mục API token trong trung tâm cá nhân, lấy khóa token: sk-xxxxx và gửi.
• Lấy url của trang này: https://api.cometapi.com/
• Chọn endpoint OPENAI_API_KEY để gửi yêu cầu API và thiết lập nội dung yêu cầu. Phương thức và phần thân yêu cầu được lấy từ tài liệu API trên trang web của chúng tôi. Trang web của chúng tôi cũng cung cấp Apifox để bạn thuận tiện thử nghiệm.

4. Thiết lập tác nhân của bạn

Xác định các công cụ AI có thể sử dụng. Giả sử chúng ta muốn bật tìm kiếm web và truy xuất tệp:

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=)

Giờ đây tác nhân của bạn biết cách tìm kiếm web và lấy tài liệu.

5. chạy

Không giống chatbot truyền thống, AI này quyết định công cụ nào sẽ dùng dựa trên đầu vào của người dùng:

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

Không cần can thiệp thủ công — chỉ thực thi tự động.

Vòng lặp tác nhân

Khi bạn gọi Runner.run(), SDK sẽ chạy một vòng lặp cho đến khi nhận được đầu ra cuối cùng:

1. LLM được gọi bằng mô hình và thiết lập trên tác nhân, cùng với lịch sử cuộc hội thoại.
2. LLM trả về phản hồi, có thể bao gồm lời gọi công cụ.
3. Nếu phản hồi có kết quả cuối cùng, vòng lặp kết thúc và trả về kết quả đó.
4. Nếu phản hồi có chuyển giao, tác nhân được đặt thành tác nhân mới và vòng lặp tiếp tục từ bước 1.
5. Các lời gọi công cụ (nếu có) được xử lý và thông điệp phản hồi công cụ được thêm vào. Sau đó vòng lặp tiếp tục từ bước 1.

Bạn có thể dùng tham số max_turns để giới hạn số lần lặp.

​Kết quả cuối cùng

Kết quả cuối cùng là điều cuối cùng tác nhân tạo ra trong vòng lặp:

• Nếu bạn đặt output_type cho tác nhân, đầu ra cuối cùng là khi LLM trả về nội dung thuộc kiểu đó bằng cấu trúc đầu ra.
• Nếu không có output_type (tức phản hồi văn bản thuần), phản hồi LLM đầu tiên không có lời gọi công cụ hoặc chuyển giao sẽ được coi là kết quả cuối cùng.

Ví dụ Hello world

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)

# Code within the code,

# Functions calling themselves,
# Infinite loop's dance.

Cấu trúc kỹ thuật

“OpenAI Agents SDK nhằm là một khung khái niệm minh họa cách các tác nhân khác nhau, như ‘Triage Agent’ hoặc ‘CRM Agent’, có thể hợp tác để hoàn thành nhiệm vụ thông qua tương tác công cụ và cơ chế ủy quyền.”

Thành phần cốt lõi và kiến trúc của Agents SDK

OpenAI Agents SDK được xây dựng trên một tập nguyên tắc gọn nhưng vững chắc. Ở trung tâm là khái niệm Agent, đại diện cho một phiên bản mô hình ngôn ngữ được điều chỉnh với hướng dẫn cụ thể và trang bị để dùng nhiều công cụ khác nhau. Tác nhân bắt đầu bằng cách nhận yêu cầu người dùng — như câu hỏi hoặc định nghĩa nhiệm vụ — sau đó phân rã các nhiệm vụ thành những tiểu nhiệm vụ có thể liên quan đến việc dùng các công cụ được định nghĩa trước, và cuối cùng cung cấp phản hồi hoàn chỉnh. Các Công cụ được mô tả về mặt chức năng như những hàm có thể gọi; tận dụng Agents SDK, bất kỳ hàm Python nào cũng có thể trở thành một công cụ, với xác thực lược đồ đầu vào và đầu ra tự động thông qua Pydantic. Ví dụ, các hàm Python đại diện cho công cụ truy vấn cơ sở dữ liệu hoặc công cụ tìm kiếm web có thể được tích hợp trực tiếp vào bộ công cụ của tác nhân.

Một thành phần trung tâm khác của Agents SDK là Vòng lặp tác nhân, định nghĩa quy trình lặp để giải quyết nhiệm vụ. Bắt đầu bằng nỗ lực ban đầu để trả lời truy vấn, tác nhân đánh giá liệu đã có đủ thông tin hay cần thực hiện hành động bên ngoài. Khi cần, tác nhân gọi công cụ phù hợp, xử lý đầu ra và đánh giá lại nhiệm vụ. Chu trình này lặp lại cho đến khi tác nhân báo hoàn thành với phản hồi “Tôi đã xong”. Agents SDK quản lý quá trình này một cách tự động, đơn giản hóa phát triển bằng cách tự động hóa các tác vụ lặp lại như gọi công cụ, xử lý kết quả và thử lại theo vòng. Điều này giúp nhà phát triển tập trung nhiều hơn vào việc xác định workflow và năng lực của tác nhân mà không phải lo về cơ chế nền tảng. OpenAI mô tả cách tiếp cận này là Python-first, nhấn mạnh sử dụng các cấu trúc Python quen thuộc — như vòng lặp, điều kiện và lời gọi hàm — thay vì các ngôn ngữ miền chuyên biệt (DSL). Với sự linh hoạt này, nhà phát triển có thể điều phối các tác nhân liên kết với nhau trong khi dựa vào cú pháp Python thuần.

Handoff và kiến trúc đa tác nhân

Khả năng của SDK vượt ra ngoài từng tác nhân riêng lẻ. Thông qua tính năng gọi là Handoff, nhiệm vụ có thể được chuyển giữa nhiều tác nhân, cho phép họ cộng tác liền mạch. Ví dụ, “Triage Agent” có thể xác định bản chất của một yêu cầu đến, rồi ủy quyền cho một tác nhân chuyên môn khác, hoặc đầu ra của một tác nhân có thể là đầu vào cho tác nhân khác. Hệ thống này hỗ trợ các workflow trong đó các tác nhân chuyên trách thực hiện từng phần riêng của một nhiệm vụ lớn hơn, trao quyền cho kiến trúc đa tác nhân phức tạp. OpenAI thiết kế bộ công cụ cho các ứng dụng có khả năng mở rộng, như tự động hóa hỗ trợ khách hàng, quy trình nghiên cứu, dự án nhiều bước, tạo nội dung, hoạt động bán hàng, hoặc thậm chí rà soát mã. Ngoài ra, Guardrails tăng độ tin cậy bằng cách áp đặt các quy tắc xác thực với đầu vào hoặc đầu ra của tác nhân. Ví dụ, rào chắn có thể buộc tuân thủ định dạng tham số hoặc kết thúc vòng lặp sớm khi phát hiện bất thường, giảm rủi ro như thực thi kém hiệu quả hay hành vi không mong muốn trong hoạt động thực tế.

Điều phối và giám sát

Vượt qua việc thực thi nhiệm vụ, Agents SDK bao gồm các tính năng điều phối vững mạnh, chịu trách nhiệm thực thi công cụ, luồng dữ liệu và quản lý vòng lặp. Dù mức độ tự động hóa cao, OpenAI vẫn ưu tiên tính minh bạch, trang bị cho nhà phát triển công cụ để giám sát hoạt động của tác nhân theo thời gian thực. Thông qua tính năng Tracing tích hợp có thể truy cập trong bảng điều khiển OpenAI, nhà phát triển có thể trực quan hóa workflow từng bước, quan sát khi nào công cụ được gọi, đầu vào sử dụng và đầu ra trả về. Nền tảng sử dụng hạ tầng giám sát của OpenAI để chia nhỏ việc thực thi logic tác nhân thành các trace và span, cung cấp góc nhìn chi tiết về hành vi của tác nhân. Điều này giúp nhà phát triển chẩn đoán nút thắt, gỡ lỗi, tối ưu hóa workflow và theo dõi hiệu năng. Hơn nữa, kiến trúc truy vết hỗ trợ các đánh giá tinh vi, cho phép tinh chỉnh và cải thiện hiệu suất tác nhân theo thời gian.

Ưu điểm

Agents SDK của OpenAI không chỉ dành cho các nhà phát triển cá nhân, mà còn mang lại lợi thế đáng kể cho các công ty xây dựng sản phẩm dựa trên tác nhân AI. Hãy bắt đầu với các ưu điểm:

Tạo mẫu nhanh và đưa vào sản xuất: Agents SDK triển khai hành vi tác nhân phức tạp với tối thiểu mã và cấu hình, rút ngắn vòng đời từ ý tưởng đến sản phẩm. Ví dụ, nền tảng crypto phổ biến Coinbase dùng SDK để nhanh chóng tạo mẫu và triển khai hệ thống hỗ trợ đa tác nhân. Tương tự, trong các lĩnh vực như trợ lý tìm kiếm doanh nghiệp, công ty có thể tích hợp công cụ tìm kiếm web và tệp của SDK để nhanh chóng mang lại giá trị. Bằng cách gánh vác chi tiết điều phối, nhà phát triển có thể tập trung vào tính năng đặc thù sản phẩm.

Giảm chi phí phát triển: Xây dựng một hệ thống tác nhân từ đầu đòi hỏi đầu tư kỹ thuật đáng kể. Agents SDK giảm chi phí bằng cách cung cấp sẵn các giải pháp cho nhu cầu phổ biến — quản lý vòng lặp, đồng bộ lời gọi API, xử lý lỗi, và định dạng đầu ra công cụ cho LLM. Là nguồn mở, nó cũng cho phép tùy biến để đáp ứng nhu cầu của công ty. Đây là món quà cho startup, cho phép họ tạo sản phẩm mạnh mẽ dựa trên tác nhân với nguồn lực hạn chế.

Khả năng truy xuất và gỡ lỗi: Bảng điều khiển theo dõi tích hợp của SDK thay đổi cách làm ứng dụng doanh nghiệp. Mối lo AI là “hộp đen” nay cho phép ghi lại và kiểm toán từng bước của tác nhân. Nếu một tác nhân hỗ trợ khách hàng đưa câu trả lời sai, trace sẽ cho thấy lời gọi công cụ hay bước nào thất bại. Màn hình log/trace của OpenAI Platform cải thiện khả năng kiểm toán tác nhân — điều then chốt trong các ngành chịu quy định hoặc kiểm toán nội bộ. Điều này cho phép công ty tích hợp AI với sự tự tin cao hơn, biết rằng họ có thể giải thích kết quả khi cần.

Tiếp cận các mô hình và công cụ mới nhất của OpenAI: Sử dụng Agents SDK đồng nghĩa tận dụng những mô hình hàng đầu của OpenAI (ví dụ GPT-4) và các công cụ hiện có (tìm kiếm web, thực thi mã). Điều này tạo lợi thế chất lượng so với việc tự xây giải pháp có thể phụ thuộc vào các mô hình yếu hơn. Với những ứng dụng đòi hỏi độ chính xác cao hoặc thông tin cập nhật (ví dụ trợ lý nghiên cứu, tác nhân phân tích tài chính), hiệu năng của các mô hình OpenAI là lợi thế lớn. Khi OpenAI bổ sung công cụ (ám chỉ sẽ có thêm tích hợp), người dùng SDK có thể dễ dàng đón nhận.

CometAPI tương thích hoàn toàn với giao thức giao diện của OpenAI để đảm bảo tích hợp liền mạch. Bạn có thể tránh phụ thuộc vào mô hình và dịch vụ (rủi ro khóa chặt), giảm lo ngại về quyền riêng tư và an ninh dữ liệu, và giảm chi phí. Việc tận dụng các mô hình và công cụ mạnh mẽ của OpenAI có thể tốn kém và đôi khi hạn chế hiệu năng. CometAPI cung cấp mức giá rẻ hơn.

Kết luận

OpenAI tận tâm thúc đẩy năng lực AI với những sản phẩm sáng tạo như Responses API. Bằng cách giới thiệu các công cụ này, doanh nghiệp và nhà phát triển có cơ hội xây dựng giải pháp AI thông minh hơn, linh hoạt hơn và đáng tin cậy hơn. Những phát triển này báo hiệu tương lai nơi trí tuệ nhân tạo tiếp tục mang lại thay đổi có tác động và mở khóa các khả năng mới trên nhiều ngành.