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.

nút

Dưới đây: một phiên REST đầu tiên, các sự kiện tiến độ, công cụ MCP, subagents, và quy trình phê duyệt sử dụng máy tính. Để biết cách 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 phần còn lại 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

Tài liệu xây dựng API dựa trên bốn phần:

Agent: mô hình, hướng dẫn, công cụ và máy chủ MCP. Truyền trực tiếp, hoặc lưu và tái sử dụng agent_id của nó.
Môi trường: một môi trường 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 giữ cấu hình, cuộc trò chuyện và công việc đã lưu.
Sự kiện và item: các sự kiện báo cáo tiến độ trực tiếp; các item là tin nhắn và lệnh gọi công cụ đã lưu.

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

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

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

none: không có 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à executor MCP thì không.
openai_hosted: OpenAI quản lý một môi trường sandbox Linux với 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), và network.access thành enabled, disabled, hoặc restricted với allowed_domains. Các tệp trong /workspace/outputs trở thành artifact khi một lượt hoàn thành. Một sandbox không hoạt động mà không có keep-alive có thể bị xóa sau một giờ.
self_hosted: cơ sở hạ tầng của bạn. Bạn chạy codex exec-server trên máy tính xách tay, container hoặc sandbox từ xa, và nó kết nối ra ngoài bằng một khóa môi trường riêng biệt.

Bài đăng ra mắt liệt kê các đối tác sandbox là 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

Xuất một khóa với các quyền trên dưới dạng OPENAI_API_KEY, sau đó gửi tác vụ khởi động nhanh với một container nhỏ:

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 còn lại của vòng đời sử dụng cùng một 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 điểm cuối, 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ùng cấu trúc. Phiên bản này, được điều chỉnh từ bài đăng ra mắt, bổ sung thêm một công cụ, subagents và một 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ở GET /v1/agents/sessions/{id}/events?stream=true với Accept: text/event-stream trước khi bạn gửi đầu vào, để không bỏ lỡ các sự kiện ban đầu. Hãy theo dõi:

agent.session.turn.output_text.delta và agent.session.turn.output_text.done cho văn bản
agent.session.turn.completed, agent.session.turn.failed, hoặc agent.session.turn.cancelled cho kết quả
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 cạm bẫy: agent.session.idle không có nghĩa là lượt đã thành công, một lượt hoàn thành có thể chứa các lệnh gọi công cụ thất bại, và đóng luồng không dừng tác vụ. Luồng không phát lại các sự kiện bị bỏ lỡ, vì vậy sau khi mất kết nối, hãy mở một luồng mới và lấy lại phiên cùng các mục của nó.

Webhooks. Đăng ký nhận `agent.session.created`, `agent.session.action_required`, `agent.session.in_progress`, `agent.session.idle`, và `agent.session.failed`. Lưu ý về cách đặt tên: luồng nói `requires_action`, webhook nói `action_required`. Payload bỏ qua chi tiết cuộc gọi, vì vậy trình xử lý của bạn lấy phiên và đọc `required_actions`. Xác minh từng chữ ký (xác minh chữ ký webhook); các hoạt động API chạy dài giải thích lý do tại sao webhook phù hợp với các tác vụ kéo dài nhiều phút.

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

MCP. Thêm một máy chủ 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 (connection_origin: "service"), vì vậy máy chủ phải có thể truy cập được từ OpenAI. Sử dụng connection_origin: "environment" cho một máy chủ mạng riêng tư, hoặc stdio để khởi động một cái trong sandbox. Đối với thông tin xác thực, truyền transport.authorization cho một phiên, hoặc đính kèm một thông tin xác thực vault (static_bearer hoặc mcp_oauth) với vault_ids.

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ụ. Đối với nhiều công cụ hàm, hãy thêm {"type": "tool_search"} và đánh dấu các hàm defer_loading: true.

Gọi công cụ theo chương trình. Mặc định bật: agent nhận được một công cụ exec chạy JavaScript trong môi trường V8 runtime biệt lập, vì vậy nó có thể lặp qua các lệnh gọi công cụ và cắt bớt các kết quả lớn trước khi chúng đến ngữ cảnh. Tắt nó bằng {"type": "programmatic_tool_calling", "enabled": false}.

Subagents. Đặt multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (giới hạn mặc định là 6). Subagents chia sẻ hệ thống tệp của môi trường và kế thừa công cụ MCP cũng như tìm kiếm web, nhưng không thể sử dụng công cụ hàm. subagent_id của một lượt là null đối với tác nhân 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ụ và một desktop vào môi trường được lưu trữ:

{
  "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 sự chấp thuận của người dùng trước khi truy cập mỗi nguồn gốc trang web mới, bao gồm các trang công khai. Khi agent.session.requires_action, lấy phiên và tìm các mục computer_use_approval_request. request.type lồng nhau là một trong hai loại:

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

Cả hai câu trả lời đều được gửi lại thông qua điểm cuối sự kiện:

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 của trình duyệt xuất hiện dưới dạng các mục computer_use_call với id, turn_id, title, status, và output, mang theo một ảnh chụp màn hình JPEG base64 khi include_screenshots được bật và có ảnh chụp. Giữ ảnh chụp màn hình khỏi nhật ký; chúng có thể hiển thị dữ liệu tài khoản.

Hướng dẫn sử dụng máy tính chỉ ra những lưu ý sau:

Phê duyệt nguồn gốc không phải là xác nhận hành động. Việc phê duyệt một trang web không khiến agent hỏi trước mỗi lần mua hoặc xóa. Nếu bạn cần điều đó, hãy hạn chế trình duyệt đối với các tài nguyên không thể thực hiện các hành động đó, hoặc sử dụng môi trường chạy trình duyệt mà bạn kiểm soát.
Đăng nhập bao gồm email, mật khẩu và mã xác minh. Khóa truy cập và đăng nhập bằng mã QR không được hỗ trợ.
Chỉ agent chính mới có thể yêu cầu xác thực. Subagents thì không.
Tắt tính năng tự động thử lại khi gửi thông tin xác thực (maxRetries: 0 trong SDK, --retry 0 trong curl).
Mã `202` có nghĩa là đã chấp nhận, không có nghĩa là đ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. Cũng cho phép trang web và các miền chuyển hướng của nó 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ột 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ó trong một máy chủ MCP: công cụ có kiểu, không có lời nhắc nguồn gốc, kết quả có thể kiểm tra. Sử dụng máy tính so với API có cấu trúc bao gồm sự đánh đổi, và Máy chủ MCP của Apidog 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 mỗi 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}} và 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 trạng thái 2xx và id không rỗng, và trích xuất id vào SESSION_ID.
Mở luồng sự kiện dưới dạng yêu cầu SSE, gửi đầu vào từ một yêu cầu thứ hai và theo dõi các sự kiện đến.
Lưu các payload phê duyệt và hủy làm các yêu cầu để phát lại từng trường hợp required_actions.
Xâu chuỗi chúng thành một kịch bản kiểm thử và chạy nó trong CI bằng Apidog CLI.

Hướng dẫn kiểm thử API agent AI có các mẫu khẳng định 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 phải 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, bao gồm mọi ví dụ về sử dụng máy tính, đều sử dụng gpt-6-astra. Các trang không liệt kê các 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. Nó chỉ hỗ trợ lưu trữ dữ liệu tại Hoa Kỳ và không đủ điều kiện ZDR, ngay cả với một sandbox tự lưu trữ.

Nó khác với SDK Agents hay Responses API như thế nào? SDK chạy vòng lặp bên trong ứng dụng của bạn; Responses API là lệnh gọi mô hình mà bạn xây dựng một 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 với một phiên chỉ đọc, thêm một máy chủ MCP, sau đó thêm tính năng sử dụng máy tính đằng sau một trình xử lý phê duyệt mặc định từ chối. Khi ChatGPT nên phản ứng với các sự kiện từ máy chủ của riêng bạn thay vào đó, MCP Events là phần phù hợp.