Sebastian Petrus

Posted on Oct 2 Originally published at apidog.com

Cách sử dụng API OpenAI Agents?

API Agents của OpenAI chạy hệ thống Codex mã nguồn mở của OpenAI cho bạn. Bạn gửi POST https://api.openai.com/v1/agents/sessions với header OpenAI-Beta: agents=v1, một định nghĩa agent và một tác vụ; OpenAI sẽ chạy mô hình và vòng lặp công cụ, duy trì phiên, và có thể cung cấp một môi trường sandbox. Không có phí API Agents: bạn trả tiền cho token, công cụ và thời gian sử dụng container được lưu trữ (từ $0.03 đến $0.48 mỗi phiên 20 phút cho các kích thước sandbox từ 1 GB đến 16 GB). API này đã đi vào bản beta công khai vào ngày 10 tháng 9 năm 2026, và OpenAI đã thêm tính năng sử dụng máy tính tại DevDay vào ngày 29 tháng 9.

Dùng thử Apidog ngay hôm nay

Dưới đây là cách tạo phiên REST đầu tiên, theo dõi sự kiện tiến độ, cấu hình công cụ MCP, bật subagents và xử lý quy trình phê duyệt sử dụng máy tính. Để so sánh với các giao diện agent khác của OpenAI, hãy đọc Agents API so với Responses API so với Agents SDK. Đối với các nội dung khác của sự kiện, hãy xem tổng hợp DevDay 2026. Mọi lệnh gọi đều là HTTP thuần túy, vì vậy bạn có thể gửi chúng từ Apidog trước khi viết mã ứng dụng.

Tổng quan về OpenAI Agents API

Mục	Giá trị
Trạng thái	Bản beta công khai từ 10 tháng 9 năm 2026; tính năng sử dụng máy tính được thêm vào ngày 29 tháng 9
Tạo một phiên	`POST /v1/agents/sessions`
Header Beta	`OpenAI-Beta: agents=v1` (SDK của OpenAI tự thêm vào)
Quyền truy cập chính	`api.agents.read`, `api.agents.write`, `api.responses.write`
Giá cả	Không có phí API Agents; token mô hình theo giá API, công cụ theo giá tiêu chuẩn (tìm kiếm web $10 cho mỗi 1.000 lượt gọi)
Container được lưu trữ	$0.03 (`small`, 1 GB), $0.12 (`medium`, 4 GB), $0.48 (`large`, 16 GB) mỗi phiên 20 phút
Môi trường	`none`, `openai_hosted`, `self_hosted`
Mô hình trong các ví dụ của tài liệu	`gpt-6-astra`
Kiểm soát dữ liệu	Chỉ lưu trữ dữ liệu tại Hoa Kỳ; không hỗ trợ Zero Data Retention (ZDR)
Kích thước yêu cầu tối đa	4 MiB

Nguồn: Giới thiệu API Agents, tổng quan về API Agents và trang giá cả.

Bốn khái niệm

API được xây dựng quanh bốn phần:

Agent: mô hình, hướng dẫn, công cụ và máy chủ MCP. Bạn có thể truyền trực tiếp cấu hình hoặc lưu và tái sử dụng agent_id.
Môi trường: một sandbox hoặc máy tính tùy chọn, nơi agent đọc tệp và chạy lệnh.
Phiên: một phiên bản bền vững của agent lưu cấu hình, cuộc trò chuyện và công việc đã lưu.
Sự kiện và item: sự kiện báo cáo tiến độ trực tiếp; item là tin nhắn và lệnh gọi công cụ đã lưu.

Một tin nhắn gửi đến phiên không hoạt động sẽ bắt đầu lượt mới. Một tin nhắn gửi trong khi lượt đang chạy sẽ điều hướng lượt đó. Theo trang kiến trúc, hệ thống là phiên bản Codex được lưu trữ, chạy mô hình và vòng lặp công cụ. Hệ thống cũng xử lý nén ngữ cảnh, nên bạn không cần tự cấu hình.

Chọn một môi trường

environment.type quyết định nơi agent chạy lệnh.

none: Không có môi trường tính toán. Máy chủ MCP từ xa và công cụ hàm của bạn vẫn hoạt động; Bash tích hợp, apply-patch, tệp không gian làm việc và MCP executor thì không.
openai_hosted: OpenAI quản lý sandbox Linux có Python và Node.js trong /workspace. Đặt container_size thành small (1 GB), medium (mặc định, 4 GB) hoặc large (16 GB). Cấu hình network.access là enabled, disabled hoặc restricted cùng allowed_domains. Các tệp trong /workspace/outputs trở thành artifact khi lượt hoàn thành. Sandbox không hoạt động và không có keep-alive có thể bị xóa sau một giờ.
self_hosted: Bạn tự vận hành hạ tầng. Chạy codex exec-server trên máy tính xách tay, container hoặc sandbox từ xa; server này kết nối ra ngoài bằng một khóa môi trường riêng.

Bài đăng ra mắt liệt kê các đối tác sandbox gồm Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop và Vercel. Hướng dẫn tự lưu trữ bổ sung AWS Lambda MicroVMs.

Phiên REST đầu tiên của bạn

Trước hết, tạo OPENAI_API_KEY với các quyền cần thiết. Sau đó tạo một phiên có container nhỏ và bật streaming:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

Với stream: true, phản hồi là luồng sự kiện của lượt đầu tiên. Lưu ID phiên từ phản hồi này vì các bước tiếp theo đều dùng cùng tài nguyên.

Hành động	Yêu cầu
Theo dõi hoặc điều hướng	`POST /v1/agents/sessions/{id}/events` với sự kiện `agent.session.input.message`
Hủy lượt hiện tại	Cùng endpoint, dùng loại sự kiện `agent.session.input.cancel`
Đọc công việc đã lưu	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
Dọn dẹp	`DELETE /v1/agents/sessions/{id}`

SDK JavaScript có cấu trúc tương tự. Ví dụ sau thêm tìm kiếm web, subagents và vault:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});

console.log(session.id);

Theo dõi tiến độ: luồng hoặc webhook

Streaming

Mở luồng sự kiện trước khi gửi đầu vào để không bỏ lỡ các sự kiện đầu tiên:

GET /v1/agents/sessions/{id}/events?stream=true
Accept: text/event-stream

Theo dõi các loại sự kiện sau:

agent.session.turn.output_text.delta và agent.session.turn.output_text.done cho văn bản sinh ra.
agent.session.turn.completed, agent.session.turn.failed hoặc agent.session.turn.cancelled cho trạng thái lượt.
agent.session.requires_action khi agent cần kết quả hàm, kết nối môi trường hoặc phê duyệt sử dụng máy tính.

Ba điểm cần lưu ý:

agent.session.idle không đồng nghĩa lượt đã thành công.
Một lượt hoàn thành vẫn có thể chứa lệnh gọi công cụ thất bại.
Đóng luồng không dừng tác vụ.

Luồng không phát lại sự kiện đã bỏ lỡ. Sau khi mất kết nối, hãy mở luồng mới, lấy lại phiên và đọc các item đã lưu.

Webhooks

Đăng ký các webhook:

agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed

Lưu ý cách đặt tên: streaming dùng requires_action, trong khi webhook dùng action_required.

Payload webhook không bao gồm chi tiết lệnh gọi. Trình xử lý của bạn cần lấy phiên và đọc required_actions. Hãy xác minh chữ ký cho mọi webhook; xem xác minh chữ ký webhook. Với các tác vụ kéo dài nhiều phút, các hoạt động API chạy dài giải thích vì sao webhook phù hợp hơn việc giữ kết nối chờ.

Công cụ MCP, tìm kiếm công cụ, gọi công cụ theo chương trình và subagents

Thêm máy chủ MCP

Thêm máy chủ MCP vào agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "required": true
}

Theo mặc định, OpenAI thực hiện kết nối bằng connection_origin: "service", nên máy chủ phải truy cập được từ hạ tầng OpenAI.

Dùng các lựa chọn sau theo vị trí máy chủ:

connection_origin: "environment" cho máy chủ trong mạng riêng.
stdio để khởi động máy chủ MCP bên trong sandbox.
transport.authorization cho thông tin xác thực chỉ dùng trong một phiên.
vault_ids để gắn thông tin xác thực vault như static_bearer hoặc mcp_oauth.

Bật tìm kiếm công cụ

Công cụ MCP được tự động phát hiện khi mô hình hỗ trợ tìm kiếm công cụ. Nếu bạn có nhiều công cụ hàm, thêm tool_search và đánh dấu những công cụ chỉ tải khi cần bằng defer_loading: true:

{
  "type": "tool_search"
}

Gọi công cụ theo chương trình

Tính năng này được bật mặc định. Agent nhận một công cụ exec chạy JavaScript trong V8 runtime biệt lập, cho phép nó lặp qua lệnh gọi công cụ và cắt bớt kết quả lớn trước khi đưa vào context.

Tắt khi cần kiểm soát chặt hơn:

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Bật subagents

Cấu hình subagents như sau:

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

Giới hạn mặc định là 6 subagents đồng thời. Subagents chia sẻ hệ thống tệp của môi trường và kế thừa MCP cùng tìm kiếm web, nhưng không thể sử dụng công cụ hàm. Trong một lượt, subagent_id là null đối với agent chính.

Sử dụng máy tính: bổ sung từ DevDay

Tính năng sử dụng máy tính cung cấp cho agent một trình duyệt được lưu trữ. Thêm công cụ computer_use và bật desktop trong môi trường:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "computer_use",
        "include_screenshots": true
      }
    ]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

Trình duyệt cần người dùng phê duyệt trước khi truy cập từng nguồn gốc website mới, kể cả trang công khai.

Khi nhận agent.session.requires_action:

Lấy phiên hiện tại.
Tìm item computer_use_approval_request.
Kiểm tra request.type.
Gửi phản hồi về endpoint sự kiện.

Có hai loại yêu cầu:

browser_origin_access: Hiển thị origin và reason, sau đó gửi approve, deny hoặc cancel.
browser_authentication: Hiển thị biểu mẫu đăng nhập từ fields, các options đăng nhập tùy chọn và credential_origin. Gửi action: "submit" cùng giá trị do người dùng nhập, hoặc action: "cancel".

Ví dụ phê duyệt quyền truy cập nguồn gốc:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "agent.session.input.computer_use_approval_request_result",
      "request_id": "REQUEST_ID",
      "response": {
        "type": "browser_origin_access",
        "decision": "approve"
      }
    }]
  }'

Công việc trình duyệt xuất hiện dưới dạng item computer_use_call, gồm id, turn_id, title, status và output. Khi bật include_screenshots, output có thể chứa ảnh chụp màn hình JPEG base64.

Không ghi ảnh chụp màn hình vào log vì chúng có thể chứa dữ liệu tài khoản.

Hướng dẫn sử dụng máy tính nêu các lưu ý quan trọng:

Phê duyệt nguồn gốc không phải xác nhận hành động. Phê duyệt website không khiến agent hỏi lại trước mỗi thao tác mua hoặc xóa. Nếu cần kiểm soát này, chỉ cho phép agent truy cập tài nguyên không thể thực hiện các hành động đó hoặc dùng môi trường trình duyệt do bạn kiểm soát.
Đăng nhập gồm email, mật khẩu và mã xác minh. Khóa truy cập và đăng nhập QR không được hỗ trợ.
Chỉ agent chính mới có thể yêu cầu xác thực. Subagents không thể.
Tắt tự động thử lại khi gửi thông tin xác thực: dùng maxRetries: 0 trong SDK hoặc --retry 0 trong curl.
Mã 202 chỉ có nghĩa là yêu cầu được chấp nhận. Nó không xác nhận điều hướng hoặc đăng nhập đã thành công.
Yêu cầu xác thực hết hạn sau năm phút.
Phê duyệt nguồn gốc không ghi đè chính sách mạng. Bạn vẫn cần cho phép website và các miền chuyển hướng trong network.

Tóm tắt cho biết tính năng sử dụng máy tính được phát hành “thông qua API và trong Codex cùng ChatGPT Work trên Pro 500 và Enterprise.” Để kiểm thử dựa trên giao diện người dùng với cùng mô hình, xem GPT-6 Astra sử dụng máy tính để kiểm thử API.

Cung cấp API của bạn cho agent, không phải giao diện người dùng của bạn

Trình duyệt là phương án dự phòng cho phần mềm không có API. Nếu hệ thống là của bạn, hãy đóng gói nó thành máy chủ MCP để agent dùng công cụ có kiểu dữ liệu, không cần lời nhắc phê duyệt nguồn gốc và có kết quả kiểm thử được.

Sử dụng máy tính so với API có cấu trúc trình bày các đánh đổi. Máy chủ MCP của Apidog có thể cung cấp đặc tả API của bạn cho trợ lý lập trình để viết wrapper.

Kiểm thử API Agents trong Apidog trước khi viết mã

API đang ở bản beta, vì vậy hãy xác nhận cấu trúc của từng lệnh gọi thủ công trong Apidog trước.

Tạo môi trường Apidog với OPENAI_API_KEY, VAULT_ID và SESSION_ID. Gửi Bearer {{OPENAI_API_KEY}} cùng OpenAI-Beta: agents=v1 trong mọi yêu cầu.
Gửi yêu cầu tạo phiên không có stream. Khẳng định mã trạng thái 2xx, kiểm tra id không rỗng, rồi trích xuất id vào biến SESSION_ID.
Mở luồng sự kiện dưới dạng yêu cầu SSE. Gửi input từ yêu cầu thứ hai và quan sát các sự kiện đến.
Lưu payload phê duyệt và hủy dưới dạng yêu cầu riêng để phát lại từng trường hợp required_actions.
Xâu chuỗi các yêu cầu thành kịch bản kiểm thử và chạy trong CI bằng Apidog CLI.

Hướng dẫn kiểm thử API agent AI có các mẫu assertion cho đầu ra không xác định. Tải xuống Apidog để làm theo.

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

API Agents của OpenAI có miễn phí không?

Không có phí nền tảng, nhưng bạn vẫn trả tiền cho token mô hình, lệnh gọi công cụ và thời gian sử dụng container được lưu trữ.

Những mô hình nào hoạt động với API Agents?

Các ví dụ trong tài liệu, gồm mọi ví dụ về sử dụng máy tính, đều dùng gpt-6-astra. Các trang không liệt kê mô hình được hỗ trợ khác, vì vậy hãy kiểm tra mô hình của bạn trước.

API Agents có hỗ trợ Zero Data Retention không?

Không. API chỉ hỗ trợ lưu trữ dữ liệu tại Hoa Kỳ và không đủ điều kiện ZDR, kể cả khi dùng sandbox tự lưu trữ.

Nó khác với Agents SDK hoặc Responses API như thế nào?

SDK chạy vòng lặp agent trong ứng dụng của bạn. Responses API là lệnh gọi mô hình mà bạn tự xây vòng lặp xung quanh. Xem bảng so sánh đầy đủ.

Bắt đầu với một phiên chỉ đọc

Bắt đầu bằng phiên chỉ đọc, thêm một máy chủ MCP, sau đó mới thêm tính năng sử dụng máy tính phía sau trình xử lý phê duyệt mặc định từ chối.

Khi ChatGPT cần phản ứng với sự kiện từ máy chủ của chính bạn, MCP Events là phần phù hợp.

DEV Community