วิธีใช้งาน OpenAI Agents API

OpenAI Agents API ทำงานบน Codex harness แบบโอเพนซอร์สของ OpenAI ให้คุณ คุณส่ง POST https://api.openai.com/v1/agents/sessions พร้อมด้วยเฮดเดอร์ OpenAI-Beta: agents=v1, คำจำกัดความของเอเจนต์ และงานที่ต้องการให้ทำ OpenAI จะรันโมเดลและวงจรเครื่องมือ จัดการเซสชัน และสามารถจัดเตรียมแซนด์บ็อกซ์ได้ ไม่มีค่าธรรมเนียม Agents API: คุณจะจ่ายเฉพาะค่าโทเค็น ค่าเครื่องมือ และเวลาของคอนเทนเนอร์โฮสต์ (0.03 ถึง 0.48 ดอลลาร์ต่อเซสชัน 20 นาที สำหรับแซนด์บ็อกซ์ขนาด 1 GB ถึง 16 GB) เข้าสู่ช่วงเบต้าสาธารณะเมื่อวันที่ 10 กันยายน 2026 และ OpenAI ได้เพิ่มฟังก์ชันการใช้งานคอมพิวเตอร์ในงาน DevDay เมื่อวันที่ 29 กันยายน

ด้านล่าง: เซสชัน REST ครั้งแรก, เหตุการณ์ความคืบหน้า, เครื่องมือ MCP, ซับเอเจนต์ และขั้นตอนการอนุมัติการใช้งานคอมพิวเตอร์ หากต้องการทราบว่าแตกต่างจาก Agent Surface อื่นๆ ของ OpenAI อย่างไร โปรดอ่าน Agents API vs Responses API vs Agents SDK; สำหรับรายละเอียดส่วนที่เหลือของงาน โปรดดูที่ DevDay 2026 roundup ทุกการเรียกใช้งานเป็น HTTP ธรรมดา ดังนั้นคุณสามารถส่งได้จาก Apidog ก่อนที่จะเขียนโค้ดแอปพลิเคชัน

OpenAI Agents API โดยสรุป

แหล่งที่มา: Introducing the Agents API, ภาพรวม Agents API และ หน้าราคา

สี่แนวคิดหลัก

เอกสารประกอบ API สร้างขึ้นจากสี่ส่วนหลัก ได้แก่:

• เอเจนต์ (Agent): โมเดล, คำสั่ง, เครื่องมือ และเซิร์ฟเวอร์ MCP คุณสามารถส่งข้อมูลแบบอินไลน์ หรือบันทึกและนำ agent_id กลับมาใช้ใหม่ได้
• สภาพแวดล้อม (Environment): แซนด์บ็อกซ์หรือคอมพิวเตอร์เสริมที่เอเจนต์ใช้อ่านไฟล์และรันคำสั่ง
• เซสชัน (Session): อินสแตนซ์ถาวรของเอเจนต์ที่เก็บการกำหนดค่า บทสนทนา และงานที่บันทึกไว้
• เหตุการณ์และรายการ (Events and items): เหตุการณ์จะรายงานความคืบหน้าแบบเรียลไทม์; รายการคือข้อความที่บันทึกไว้และการเรียกใช้เครื่องมือ

ข้อความที่ส่งไปยังเซสชันที่ไม่ได้ใช้งานจะเริ่มต้นเทิร์นใหม่; ข้อความที่ส่งระหว่างเทิร์นจะใช้เพื่อควบคุมการทำงาน Harness (ตามที่ระบุใน หน้าสถาปัตยกรรม ซึ่งเป็นอินสแตนซ์ Codex ที่โฮสต์อยู่และรันโมเดลและวงจรเครื่องมือ) ยังจัดการการบีบอัดบริบท ดังนั้นคุณจึงไม่จำเป็นต้องกำหนดค่าเอง

เลือกสภาพแวดล้อม

environment.type กำหนดว่าจะให้คำสั่งทำงานที่ใด:

• none: ไม่มีการประมวลผล เซิร์ฟเวอร์ MCP ระยะไกลและเครื่องมือฟังก์ชันของคุณยังคงทำงานได้; แต่ Bash ในตัว, apply-patch, ไฟล์ในพื้นที่ทำงาน และ executor MCPs จะไม่ทำงาน
• openai_hosted: OpenAI จัดการแซนด์บ็อกซ์ Linux ที่มี Python และ Node.js ใน /workspace กำหนด container_size เป็น small (1 GB), medium (ค่าเริ่มต้น, 4 GB), หรือ large (16 GB) และ network.access เป็น enabled, disabled, หรือ restricted พร้อม allowed_domains ไฟล์ใน /workspace/outputs จะกลายเป็นสิ่งประดิษฐ์เมื่อเทิร์นเสร็จสมบูรณ์ แซนด์บ็อกซ์ที่ไม่ได้ใช้งานโดยไม่มี keep-alives อาจถูกลบหลังจากหนึ่งชั่วโมง
• self_hosted: โครงสร้างพื้นฐานของคุณ คุณรัน codex exec-server บนแล็ปท็อป, คอนเทนเนอร์ หรือแซนด์บ็อกซ์ระยะไกล และมันจะเชื่อมต่อขาออกด้วยคีย์สภาพแวดล้อมแยกต่างหาก

โพสต์เปิดตัวระบุพาร์ทเนอร์แซนด์บ็อกซ์ได้แก่ Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop และ Vercel; ส่วน คู่มือ self-hosted ได้เพิ่ม AWS Lambda MicroVMs

เซสชัน REST แรกของคุณ

ส่งออกคีย์ที่มีสิทธิ์ข้างต้นเป็น OPENAI_API_KEY จากนั้นส่งงาน quickstart ด้วยคอนเทนเนอร์ขนาดเล็ก:

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
  }'

เมื่อตั้งค่า stream: true การตอบกลับจะเป็นสตรีมเหตุการณ์ของเทิร์นแรก บันทึก Session ID จากนั้น; ส่วนที่เหลือของวงจรชีวิตจะใช้ทรัพยากรเดียวกัน:

JavaScript SDK มีรูปแบบเดียวกัน เวอร์ชันนี้ดัดแปลงจากโพสต์เปิดตัว เพิ่มเครื่องมือ ซับเอเจนต์ และ 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);

ติดตามความคืบหน้า: สตรีมหรือเว็บฮุค

การสตรีม (Streaming). เปิด GET /v1/agents/sessions/{id}/events?stream=true ด้วย Accept: text/event-stream ก่อนที่คุณจะส่งข้อมูล เพื่อไม่ให้พลาดเหตุการณ์แรกๆ สังเกตดูสิ่งเหล่านี้:

• agent.session.turn.output_text.delta และ agent.session.turn.output_text.done สำหรับข้อความ
• agent.session.turn.completed, agent.session.turn.failed, หรือ agent.session.turn.cancelled สำหรับผลลัพธ์
• agent.session.requires_action เมื่อเอเจนต์ต้องการผลลัพธ์ของฟังก์ชัน, การเชื่อมต่อสภาพแวดล้อม หรือการอนุมัติการใช้งานคอมพิวเตอร์

ข้อควรระวังสามประการ: agent.session.idle ไม่ได้หมายความว่าเทิร์นสำเร็จ, เทิร์นที่เสร็จสมบูรณ์อาจมีการเรียกใช้เครื่องมือที่ล้มเหลว, และการปิดสตรีมไม่ได้หยุดงาน สตรีมจะไม่เล่นซ้ำเหตุการณ์ที่พลาดไป ดังนั้นหลังจากการตัดการเชื่อมต่อ ให้เปิดสตรีมใหม่และเรียกเซสชันและรายการต่างๆ ของมันกลับคืนมา

เว็บฮุค (Webhooks). สมัครรับ agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle, และ agent.session.failed โปรดสังเกตชื่อเรียก: สตรีมใช้คำว่า requires_action ส่วนเว็บฮุคใช้คำว่า action_required Payload จะละเว้นรายละเอียดการเรียกใช้งาน ดังนั้นตัวจัดการของคุณจะต้องเรียกเซสชันและอ่าน required_actions ตรวจสอบลายเซ็นแต่ละรายการ (การตรวจสอบลายเซ็นเว็บฮุค); การดำเนินการ API ที่ใช้เวลานาน อธิบายว่าเหตุใดเว็บฮุคจึงเหมาะกับงานที่ใช้เวลาหลายนาที

เครื่องมือ MCP, การค้นหาเครื่องมือ, การเรียกใช้เครื่องมือด้วยโปรแกรม และซับเอเจนต์

MCP. เพิ่มเซิร์ฟเวอร์ไปยัง agent.tools:

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

โดยค่าเริ่มต้น OpenAI จะทำการเชื่อมต่อ (connection_origin: "service") ดังนั้นเซิร์ฟเวอร์จะต้องเข้าถึงได้จาก OpenAI ใช้ connection_origin: "environment" สำหรับเซิร์ฟเวอร์เครือข่ายส่วนตัว หรือ stdio เพื่อเริ่มต้นในแซนด์บ็อกซ์ สำหรับข้อมูลประจำตัว ให้ส่ง transport.authorization สำหรับหนึ่งเซสชัน หรือแนบข้อมูลประจำตัว vault (static_bearer หรือ mcp_oauth) ด้วย vault_ids

การค้นหาเครื่องมือ (Tool search). เครื่องมือ MCP จะถูกค้นพบโดยอัตโนมัติเมื่อโมเดลรองรับการค้นหาเครื่องมือ สำหรับเครื่องมือฟังก์ชันหลายรายการ ให้เพิ่ม {"type": "tool_search"} และทำเครื่องหมายฟังก์ชัน defer_loading: true

การเรียกใช้เครื่องมือด้วยโปรแกรม (Programmatic tool calling). เปิดใช้งานโดยค่าเริ่มต้น: เอเจนต์จะได้รับเครื่องมือ exec ที่รัน JavaScript ในรันไทม์ V8 แบบแยกส่วน เพื่อให้สามารถวนรอบการเรียกใช้เครื่องมือและตัดผลลัพธ์ขนาดใหญ่ก่อนที่จะเข้าสู่บริบท ปิดใช้งานด้วย {"type": "programmatic_tool_calling", "enabled": false}

ซับเอเจนต์ (Subagents). ตั้งค่า multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (ขีดจำกัดเริ่มต้นคือ 6) ซับเอเจนต์จะใช้ระบบไฟล์ของสภาพแวดล้อมร่วมกันและรับมรดกเครื่องมือ MCP และการค้นหาเว็บ แต่ไม่สามารถใช้เครื่องมือฟังก์ชันได้ subagent_id ของเทิร์นจะเป็น null สำหรับเอเจนต์หลัก

การใช้งานคอมพิวเตอร์: สิ่งที่เพิ่มเข้ามาใน DevDay

การใช้งานคอมพิวเตอร์ช่วยให้เอเจนต์มีเบราว์เซอร์ที่โฮสต์อยู่ เพิ่มเครื่องมือและเดสก์ท็อปไปยังสภาพแวดล้อมที่โฮสต์:

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

เบราว์เซอร์ต้องการการอนุมัติจากผู้ใช้ก่อนที่จะเข้าชมเว็บไซต์ใหม่แต่ละแหล่ง รวมถึงเว็บไซต์สาธารณะ เมื่อ agent.session.requires_action ให้เรียกเซสชันและค้นหารายการ computer_use_approval_request request.type ที่ซ้อนอยู่มีสองประเภทดังนี้:

• browser_origin_access: แสดง origin และ reason จากนั้นส่ง approve, deny หรือ cancel
• browser_authentication: แบบฟอร์มเข้าสู่ระบบที่มี fields, options การเข้าสู่ระบบเสริม และ credential_origin ส่ง action: "submit" พร้อมค่าของผู้ใช้ หรือ action: "cancel"

คำตอบทั้งสองจะกลับไปผ่านเอนด์พอยต์เหตุการณ์:

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" }
  }]}'

งานของเบราว์เซอร์จะปรากฏเป็นรายการ computer_use_call พร้อมด้วย id, turn_id, title, status, และ output ซึ่งจะประกอบด้วยภาพหน้าจอ JPEG แบบ base64 เมื่อเปิด include_screenshots และมีภาพหน้าจออยู่ เก็บภาพหน้าจอออกจากบันทึก; เนื่องจากอาจแสดงข้อมูลบัญชีได้

คู่มือการใช้งานคอมพิวเตอร์ ระบุข้อควรระวังดังต่อไปนี้:

• การอนุมัติแหล่งที่มาไม่ใช่การยืนยันการกระทำ การอนุมัติเว็บไซต์ไม่ได้หมายความว่าเอเจนต์จะถามก่อนการซื้อหรือลบทุกครั้ง หากคุณต้องการสิ่งนั้น ให้จำกัดเบราว์เซอร์ให้เข้าถึงทรัพยากรที่ไม่สามารถดำเนินการดังกล่าวได้ หรือใช้รันไทม์เบราว์เซอร์ที่คุณควบคุม
• การเข้าสู่ระบบครอบคลุมอีเมล, รหัสผ่าน และรหัสยืนยัน ไม่รองรับ Passkeys และการเข้าสู่ระบบด้วยรหัส QR
• เฉพาะเอเจนต์หลักเท่านั้นที่สามารถร้องขอการรับรองความถูกต้องได้ ซับเอเจนต์ไม่สามารถทำได้
• ปิดใช้งานการลองใหม่โดยอัตโนมัติในการส่งข้อมูลประจำตัว (`maxRetries: 0` ใน SDK, `--retry 0` ใน curl)
• รหัส 202 หมายถึงยอมรับแล้ว ไม่ใช่ว่าการนำทางหรือการเข้าสู่ระบบสำเร็จ คำขอการรับรองความถูกต้องจะหมดอายุหลังจากห้านาที
• การอนุมัติแหล่งที่มาไม่ได้แทนที่นโยบายเครือข่าย อนุญาตเว็บไซต์และโดเมนเปลี่ยนเส้นทางใน network ด้วยเช่นกัน

สรุปกล่าวว่าการใช้งานคอมพิวเตอร์จัดส่ง “ผ่าน API และใน Codex และ ChatGPT Work บน Pro 500 และ Enterprise” สำหรับการทดสอบที่ขับเคลื่อนด้วย UI ด้วยโมเดลเดียวกัน โปรดดู การใช้งานคอมพิวเตอร์ของ GPT-6 Astra สำหรับการทดสอบ API

ให้ API ของคุณแก่เอเจนต์ ไม่ใช่ UI ของคุณ

เบราว์เซอร์เป็นทางเลือกสำรองสำหรับซอฟต์แวร์ที่ไม่มี API หากระบบเป็นของคุณ ให้ห่อหุ้มด้วยเซิร์ฟเวอร์ MCP: เครื่องมือที่กำหนดประเภท, ไม่มีข้อความแจ้งแหล่งที่มา, ผลลัพธ์ที่ตรวจสอบได้ การใช้งานคอมพิวเตอร์ vs Structured APIs ครอบคลุมข้อดีข้อเสีย และ Apidog MCP Server จะป้อนข้อมูล API ของคุณไปยังผู้ช่วยเขียนโค้ดที่สร้าง wrapper

ทดสอบ Agents API ใน Apidog ก่อนเขียนโค้ด

API ยังอยู่ในช่วงเบต้า ดังนั้นควรยืนยันรูปแบบการเรียกแต่ละครั้งด้วยตนเองใน Apidog ก่อน:

1. สร้าง Apidog environment ด้วย OPENAI_API_KEY, VAULT_ID และ SESSION_ID ส่ง Bearer {{OPENAI_API_KEY}} และ OpenAI-Beta: agents=v1 ในทุกคำขอ
2. ส่งคำขอสร้างเซสชันโดยไม่มี stream ยืนยันสถานะ 2xx และ id ที่ไม่ว่างเปล่า และดึง id ไปยัง SESSION_ID
3. เปิดสตรีมเหตุการณ์เป็นคำขอ SSE ส่งข้อมูลจากคำขอที่สอง และดูเหตุการณ์ที่เข้ามา
4. บันทึก payloads สำหรับการอนุมัติและการยกเลิกเป็นคำขอเพื่อเล่นซ้ำแต่ละกรณีของ required_actions
5. เชื่อมโยงเข้าด้วยกันเป็นสถานการณ์การทดสอบและรันใน CI ด้วย Apidog CLI

คู่มือการทดสอบ AI agent API มีรูปแบบการยืนยันสำหรับเอาต์พุตที่ไม่แน่นอน ดาวน์โหลด Apidog เพื่อทำตาม

คำถามที่พบบ่อย

OpenAI Agents API ฟรีหรือไม่? ไม่มีค่าธรรมเนียมแพลตฟอร์ม แต่คุณจะต้องจ่ายสำหรับโทเค็นโมเดล, การเรียกใช้เครื่องมือ และเวลาคอนเทนเนอร์ที่โฮสต์

โมเดลใดบ้างที่ทำงานร่วมกับ Agents API ได้? ตัวอย่างในเอกสารประกอบ รวมถึงตัวอย่างการใช้งานคอมพิวเตอร์ทั้งหมด ใช้ gpt-6-astra เอกสารไม่ได้ระบุโมเดลอื่นๆ ที่รองรับ ดังนั้นควรทดสอบของคุณก่อน

Agents API รองรับ Zero Data Retention หรือไม่? ไม่รองรับ รองรับเฉพาะข้อมูลที่อยู่ในสหรัฐอเมริกาเท่านั้น และไม่มีสิทธิ์ ZDR แม้จะใช้แซนด์บ็อกซ์แบบ self-hosted ก็ตาม

แตกต่างจาก Agents SDK หรือ Responses API อย่างไร? SDK รันวงจรภายในแอปของคุณ; Responses API คือการเรียกโมเดลที่คุณสร้างวงจรครอบคลุม ดู การเปรียบเทียบฉบับเต็ม

เริ่มต้นด้วยเซสชันแบบอ่านอย่างเดียวหนึ่งเซสชัน

เริ่มต้นด้วยเซสชันแบบอ่านอย่างเดียว เพิ่มเซิร์ฟเวอร์ MCP หนึ่งเครื่อง จากนั้นเพิ่มการใช้งานคอมพิวเตอร์หลังตัวจัดการการอนุมัติที่ปฏิเสธโดยค่าเริ่มต้น เมื่อ ChatGPT ควรตอบสนองต่อเหตุการณ์จากเซิร์ฟเวอร์ของคุณเองแทน เหตุการณ์ MCP คือส่วนที่เหมาะสม