Thanawat Wongchai

Posted on Oct 2 Originally published at apidog.com

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

#openai #ai #api #agents

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) API เข้าสู่ช่วงเบต้าสาธารณะเมื่อวันที่ 10 กันยายน 2026 และ OpenAI เพิ่มฟังก์ชันการใช้งานคอมพิวเตอร์ในงาน DevDay เมื่อวันที่ 29 กันยายน

ลองใช้ Apidog วันนี้

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

OpenAI Agents API โดยสรุป

รายการ	ค่า
สถานะ	เบต้าสาธารณะตั้งแต่วันที่ 10 ก.ย. 2026; เพิ่มการใช้งานคอมพิวเตอร์เมื่อวันที่ 29 ก.ย.
สร้างเซสชัน	`POST /v1/agents/sessions`
เฮดเดอร์เบต้า	`OpenAI-Beta: agents=v1` (OpenAI SDKs จะเพิ่มให้)
สิทธิ์การเข้าถึงหลัก	`api.agents.read`, `api.agents.write`, `api.responses.write`
ราคา	ไม่มีค่าธรรมเนียม Agents API; โทเค็นโมเดลคิดตามอัตรา API, เครื่องมือคิดตามอัตรามาตรฐาน (การค้นหาเว็บ 10 ดอลลาร์ต่อ 1,000 การเรียกใช้งาน)
คอนเทนเนอร์โฮสต์	0.03 ดอลลาร์ (`small`, 1 GB), 0.12 ดอลลาร์ (`medium`, 4 GB), 0.48 ดอลลาร์ (`large`, 16 GB) ต่อเซสชัน 20 นาที
สภาพแวดล้อม	`none`, `openai_hosted`, `self_hosted`
โมเดลในตัวอย่างเอกสาร	`gpt-6-astra`
การควบคุมข้อมูล	รองรับเฉพาะข้อมูลที่อยู่ในสหรัฐอเมริกาเท่านั้น; ไม่มี Zero Data Retention (ZDR)
ขนาดคำขอสูงสุด	4 MiB

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

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

Agents API มีองค์ประกอบหลัก 4 ส่วน:

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

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

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

กำหนดตำแหน่งรันคำสั่งด้วย environment.type:

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

การกระทำ	คำขอ
ติดตามหรือควบคุม	`POST /v1/agents/sessions/{id}/events` พร้อมเหตุการณ์ `agent.session.input.message`
ยกเลิกเทิร์นที่กำลังทำงาน	เอนด์พอยต์เดียวกัน พร้อมประเภทเหตุการณ์ `agent.session.input.cancel`
อ่านงานที่บันทึกไว้	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
ล้างข้อมูล	`DELETE /v1/agents/sessions/{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);

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

การสตรีม

เปิด 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 ไม่ได้หมายความว่าเทิร์นสำเร็จ
เทิร์นที่เสร็จสมบูรณ์อาจมีการเรียกใช้เครื่องมือที่ล้มเหลว
การปิดสตรีมไม่ได้หยุดงาน
สตรีมจะไม่เล่นซ้ำเหตุการณ์ที่พลาดไป หลังการตัดการเชื่อมต่อ ให้เปิดสตรีมใหม่ แล้วเรียกข้อมูลเซสชันและรายการกลับมา

เว็บฮุค

สมัครรับเหตุการณ์เหล่านี้:

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

ชื่อเหตุการณ์แตกต่างกันเล็กน้อย: สตรีมใช้ requires_action แต่เว็บฮุคใช้ action_required

Payload ของเว็บฮุคจะละเว้นรายละเอียดการเรียกใช้งาน ดังนั้น handler ต้องเรียกข้อมูลเซสชันและอ่าน required_actions เอง ตรวจสอบลายเซ็นทุกคำขอด้วยแนวทางจากการตรวจสอบลายเซ็นเว็บฮุค และใช้เว็บฮุคกับงานที่รันนานตามแนวทางในการดำเนินการ API ที่ใช้เวลานาน

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

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

การค้นหาเครื่องมือ

เครื่องมือ MCP จะถูกค้นพบโดยอัตโนมัติเมื่อโมเดลรองรับ tool search หากมีเครื่องมือฟังก์ชันจำนวนมาก ให้เพิ่ม:

{ "type": "tool_search" }

และกำหนดฟังก์ชันที่ไม่ต้องโหลดทันทีด้วย:

{
  "defer_loading": true
}

การเรียกใช้เครื่องมือด้วยโปรแกรม

Programmatic tool calling เปิดใช้งานโดยค่าเริ่มต้น เอเจนต์จะได้รับเครื่องมือ exec สำหรับรัน JavaScript ใน V8 runtime แบบแยกส่วน ทำให้สามารถวนลูปเรียกเครื่องมือและตัดผลลัพธ์ขนาดใหญ่ก่อนนำเข้าสู่บริบทได้

หากต้องการปิด ให้เพิ่ม:

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

ซับเอเจนต์

เปิดใช้งานซับเอเจนต์ด้วย:

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

ขีดจำกัดเริ่มต้นคือ 6 ซับเอเจนต์จะใช้ระบบไฟล์ของ environment ร่วมกัน และรับมรดกเครื่องมือ MCP กับการค้นหาเว็บ แต่ไม่สามารถใช้เครื่องมือฟังก์ชันได้

ค่า subagent_id ของเทิร์นจากเอเจนต์หลักจะเป็น null

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

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

{
  "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 ที่ซ้อนอยู่มี 2 แบบ:

browser_origin_access: แสดง origin และ reason จากนั้นส่ง approve, deny หรือ cancel
browser_authentication: ฟอร์มเข้าสู่ระบบที่มี fields, ตัวเลือกการเข้าสู่ระบบ และ 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 เมื่อเปิด include_screenshots และมีภาพหน้าจอ output จะมี JPEG แบบ base64

อย่าเก็บภาพหน้าจอไว้ใน log เพราะอาจมีข้อมูลบัญชีของผู้ใช้

คู่มือการใช้งานคอมพิวเตอร์ระบุข้อควรระวังสำคัญ:

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

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

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

เบราว์เซอร์ควรเป็นทางเลือกสำรองสำหรับซอฟต์แวร์ที่ไม่มี API หากคุณควบคุมระบบเอง ให้ห่อหุ้มระบบด้วยเซิร์ฟเวอร์ MCP ที่มีลักษณะดังนี้:

เครื่องมือมี type ชัดเจน
ไม่มีข้อความแจ้งแหล่งที่มา
ผลลัพธ์ตรวจสอบได้

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

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

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

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

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

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

OpenAI Agents API ฟรีหรือไม่?

ไม่มีค่าธรรมเนียมแพลตฟอร์ม แต่คุณต้องจ่ายค่าโทเค็นโมเดล การเรียกใช้เครื่องมือ และเวลาคอนเทนเนอร์ที่โฮสต์

โมเดลใดบ้างที่ทำงานร่วมกับ Agents API ได้?

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

Agents API รองรับ Zero Data Retention หรือไม่?

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

แตกต่างจาก Agents SDK หรือ Responses API อย่างไร?

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

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

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

เมื่อ ChatGPT ควรตอบสนองต่อเหตุการณ์จากเซิร์ฟเวอร์ของคุณเองแทน ให้ใช้เหตุการณ์ MCPเป็นจุดเริ่มต้น

DEV Community