OpenAI Agents API: Xây dựng Agent viết và chạy mã trên đám mây

Hầu hết các ứng dụng LLM tuân theo một khuôn mẫu đơn giản: gửi một prompt, nhận phản hồi, và sử dụng phản hồi đó trong ứng dụng của bạn.

Điều đó hoạt động tốt với các tác vụ đơn giản, nhưng mọi thứ trở nên phức tạp hơn khi mô hình cần viết mã, chạy mã, kiểm tra kết quả, làm việc với tệp, sửa lỗi, và tiếp tục cho đến khi nhiệm vụ thực sự hoàn thành.

Đây là lúc Agents API của OpenAI trở nên cực kỳ hữu ích.

Thay vì tự xây dựng từng bước, bạn có thể giao cho agent nhiệm vụ, các tệp nó cần, và một môi trường để làm việc, rồi để nó xử lý phần còn lại.

Trong hướng dẫn này, tôi sẽ giữ ví dụ đơn giản. Chúng ta sẽ tạo một bộ dữ liệu doanh số nhỏ mang tính hư cấu của quán cafe và đưa cho agent. Agent sẽ viết và chạy phân tích, xác minh kết quả, và tạo ba tệp đầu ra cho chúng ta.

Khi bạn thấy toàn bộ quá trình hoạt động phía sau hậu trường, bạn sẽ bắt đầu nhận ra có bao nhiêu phần của quy trình viết mã thông thường đang được tự động hóa cho bạn. 

Nếu bạn còn mới với AI agent, tôi khuyên bạn nên xem lộ trình kỹ năng AI Agents Fundamentals của chúng tôi. 

OpenAI Agents API là gì?

OpenAI Agents API cho phép bạn giao cho một agent nhiệm vụ, các tệp cần thiết, và môi trường làm việc, rồi để nó xử lý phần còn lại.

Thay vì thủ công tạo sandbox, khởi động phiên, tải tệp lên, chạy mã, kiểm tra lỗi, và tự quản lý mọi bước, bạn có thể gửi một yêu cầu API với nhiệm vụ, cấu hình, môi trường, và các tệp đầu vào.

Sau đó, phần lớn công việc được Agents API xử lý.

Bên dưới, OpenAI quản lý bộ khung Codex, bao gồm điều phối, ngữ cảnh, sử dụng công cụ, thực thi, và các phiên chạy dài. Bạn có thể hình dung gần như là đang có OpenAI Codex chạy trên đám mây cho ứng dụng của bạn. 

Bạn không cần bận tâm nhiều về thiết lập tính toán, quản lý môi trường làm việc, theo dõi phiên, hay tự xây vòng lặp agent đầy đủ.

Điều này đặc biệt hữu ích cho các tác vụ phức tạp và chạy dài, nơi agent cần thực sự làm công việc, không chỉ trả về một câu trả lời.

Trong hướng dẫn này, chúng ta sẽ dùng sandbox do OpenAI lưu trữ:

Chúng ta gửi một yêu cầu với tệp CSV, nhiệm vụ và cấu hình agent. 

Agents API sẽ tạo và quản lý phiên và sandbox cho chúng ta.

Bên trong sandbox, agent có thể xem tệp, tìm cách tiếp cận phân tích, tạo mã Python, chạy, kiểm tra kết quả, và sửa nếu có sự cố.

Khi mọi thứ xong xuôi, các đầu ra được lưu dưới dạng hiện vật của phiên (session artifacts). 

Đó có thể là biểu đồ, bộ dữ liệu đã làm sạch, báo cáo, hoặc bất kỳ tệp nào khác mà agent tạo ra. Sau đó chúng ta có thể truy xuất các tệp đó và cho người dùng tải về để xem.

Vì vậy ý tưởng chính rất đơn giản: chúng ta gửi nhiệm vụ một lần, và từ đó agent sẽ xử lý công việc thực tế.

OpenAI Responses API vs Agents SDK vs Agents API: Nên dùng cái nào?

Sự khác nhau chính giữa ba lựa chọn này là bạn muốn tự quản lý bao nhiêu phần của quy trình làm việc.

Dùng Responses API khi bạn cần mô hình hoàn thành một tác vụ tập trung, như tóm tắt, trích xuất, phân loại, hỏi đáp, đầu ra có cấu trúc, hoặc vài lần gọi công cụ.

Dùng Agents SDK khi bạn tự xây ứng dụng agent và muốn kiểm soát nhiều hơn đối với agent, công cụ, handoff, guardrail, và quy trình đa agent.

Dùng Agents API khi tác vụ phức tạp hơn và cần môi trường làm việc riêng. Điều này hữu ích khi agent cần làm việc với tệp, chạy mã, kiểm tra kết quả, sửa lỗi, và tiếp tục qua nhiều bước.

Hướng dẫn từng bước: Xây dựng một agent phân tích dữ liệu với OpenAI

Trong hướng dẫn này, chúng ta dùng Agents API vì agent cần làm việc với một tệp, suy luận về phân tích, chạy mã, kiểm tra kết quả, và lưu các hiện vật cuối cùng cho người dùng.

Bắt đầu thôi

1. Thiết lập môi trường Python cho Agents API

Trong hướng dẫn này, chúng ta sẽ dùng Jupyter Notebook để kiểm thử Agents API từng bước và hiểu cách mỗi phần hoạt động. 

Chúng ta sẽ bắt đầu bằng cách cài đặt gói OpenAI và import các thư viện cần cho phần còn lại của hướng dẫn.

Đầu tiên, cài đặt hoặc nâng cấp gói OpenAI cho Python:

%pip install -q --upgrade openai

Sau đó import các thư viện sẽ dùng:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Bây giờ tạo client OpenAI:

client = OpenAI()

Đảm bảo biến OPENAI_API_KEY đã được đặt trong môi trường của bạn. Client OpenAI sẽ tự động nhận khóa.

2. Tạo dữ liệu mẫu cho AI agent

Chúng ta sẽ tạo một bộ dữ liệu doanh số giả nhỏ để có thứ đơn giản đưa cho agent.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Đoạn này tạo 50 đơn hàng giả của quán cafe trên các sản phẩm, địa điểm, ngày tháng và mức giảm giá khác nhau. Chúng ta dùng seed ngẫu nhiên cố định để mỗi lần chạy notebook sẽ tạo cùng một bộ dữ liệu.

3. Tạo và mã hóa tệp CSV cho sandbox của agent

Tiếp theo, chúng ta sẽ chuyển dữ liệu đã tạo thành tệp CSV có thể truyền cho agent.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Kết quả:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Chúng ta cũng mã hóa Base64 cho CSV vì sẽ gửi tệp trực tiếp kèm yêu cầu tới agent.

4. Xác định nhiệm vụ của agent và các đầu ra kỳ vọng

Giờ chúng ta sẽ mô tả điều muốn agent làm với tệp CSV.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

Điều quan trọng là chúng ta mô tả mục tiêu và các đầu ra mong đợi, thay vì tự viết mã phân tích.

Agent có thể tự quyết cách thực hiện, chạy mã, và xác minh kết quả trước khi kết thúc.

5. Thực thi agent trong sandbox do OpenAI lưu trữ

Bây giờ chúng ta sẽ gửi mọi thứ tới Agents API trong một yêu cầu và để agent làm việc thực sự trên đám mây.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

Đây là nơi hầu hết công việc diễn ra.

Chúng ta gửi một yêu cầu chứa cấu hình agent, môi trường lưu trữ, tệp CSV, và nhiệm vụ. 

OpenAI tạo phiên được quản lý và chạy agent bên trong sandbox lưu trữ. Agent có thể kiểm tra tệp, viết analyze_sales.py, thực thi, kiểm tra kết quả, sửa bất kỳ lỗi nào, và tạo các tệp đầu ra cuối cùng. 

Điểm cuối tạo phiên hỗ trợ cả môi trường và đầu vào ban đầu trong cùng một yêu cầu.

Có ba phần chính trong yêu cầu:

• agent cho OpenAI biết nên dùng mô hình nào và agent nên hành xử thế nào.
• environment cung cấp không gian làm việc lưu trữ cho agent và đặt tệp CSV của chúng ta vào đó.
• input cung cấp cho agent nhiệm vụ mà chúng ta đã xác định ở phần trước.

Chúng ta cũng đặt stream=True. 

Điều này không thay đổi cách tác vụ được hoàn thành. Nó chỉ cho phép chúng ta nhận sự kiện trong khi agent làm việc thay vì đợi đến khi toàn bộ lượt hoàn tất mới thấy kết quả.

Trong ví dụ này, chúng ta lắng nghe các sự kiện agent.session.turn.output_text.delta và liên tục cập nhật notebook với phần văn bản mới nhất.

Vậy nên phần văn bản xuất hiện phía trên là agent đang báo cáo tiến độ và phản hồi cuối cùng. 

Tác vụ thực tế tiếp tục chạy trong môi trường lưu trữ cho đến khi chúng ta nhận sự kiện agent.session.turn.completed.

Trong lần chạy của tôi, agent đã tạo và chạy analyze_sales.py, kiểm tra các tệp sinh ra, và xác minh tổng doanh thu ròng là 600.55.

Điều quan trọng là mô hình không chỉ nói cho chúng ta biết nên chạy mã Python nào. Agent thực sự đã viết mã, thực thi, kiểm tra kết quả và tự xác minh đầu ra.

6. Truy xuất và tải xuống các hiện vật tệp của agent

Bây giờ agent đã hoàn tất, chúng ta có thể tải xuống các tệp mà nó tạo trong lượt đó.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Kết quả:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Ở đây, chúng ta liệt kê các hiện vật từ phiên, giữ lại những tệp được tạo bởi lượt đã hoàn tất, và tải chúng về thư mục cục bộ cloud_bean_results.

7. Xóa phiên để tiết kiệm chi phí tính toán của sandbox

Khi đã xong với các tệp, chúng ta nên xóa phiên để không giữ môi trường được quản lý lâu hơn mức cần thiết.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Kết quả:

Session deleted: True

Bước này loại bỏ phiên được quản lý khỏi API. 

OpenAI lưu ý rằng việc dọn dẹp tài nguyên nền tảng có thể tiếp tục bất đồng bộ sau khi yêu cầu xóa trả về.

Bước này đặc biệt quan trọng khi dùng sandbox do OpenAI lưu trữ. 

Sandbox là môi trường tính toán nơi agent chạy mã và làm việc với tệp, và sandbox lưu trữ sử dụng tài nguyên container được tính phí tách biệt với chi phí dùng mô hình. 

Vì vậy nếu bạn giữ phiên và môi trường chạy lâu hơn cần thiết, bạn có thể tiếp tục phát sinh chi phí tính toán.

Tổng kết: OpenAI Agents API có xứng đáng với chi phí?

Điều khiến tôi ấn tượng về Agents API là nó có thể làm được rất nhiều chỉ từ một lệnh gọi API đơn giản.

Chúng ta đưa cho nó tệp, nhiệm vụ, cấu hình mô hình, và môi trường lưu trữ. 

Từ đó, nó xử lý phần còn lại: tạo workspace, kiểm tra dữ liệu, viết mã Python, chạy, kiểm tra đầu ra, sửa nếu cần, và tạo các hiện vật cuối cùng.

Cảm giác thực sự giống như đang có Codex chạy trên đám mây cho ứng dụng của bạn. 

Tôi không phải lo thiết lập tính toán, quản lý vòng lặp thực thi, xử lý tệp trung gian, hay theo dõi từng bước. Tôi chủ yếu chỉ cần định nghĩa nhiệm vụ rõ ràng rồi xem kết quả.

Bản chạy mất khoảng hai phút, nhưng trong thời gian đó, agent làm khá nhiều việc ở hậu trường.

Đó là điều làm nó khác với một yêu cầu API thông thường. 

Bạn không chỉ chờ mô hình sinh văn bản. Bạn đang chờ một agent thực sự hoàn thành một phần công việc.

Trong quá trình thử nghiệm của tôi, ba lần chạy ví dụ này tốn khoảng 1,52 USD tổng cộng, bao gồm chi phí mô hình và môi trường lưu trữ. 

Với một tác vụ nhỏ như vậy, con số đó không rẻ, nên cho môi trường sản xuất, tôi chắc chắn sẽ thử các mô hình nhỏ hơn hoặc rẻ hơn trước.

Nhưng với các công việc phức tạp hơn liên quan đến viết mã, gỡ lỗi, tệp, suy luận, và nhiều bước phụ thuộc, chi phí tăng thêm có thể hợp lý hơn nhiều.