บทช่วยสอน OpenAI Agents API: สร้างเอเจนต์ที่เขียนและรันโค้ดบนคลาวด์

แอป LLM ส่วนใหญ่ทำตามรูปแบบง่ายๆ: ส่งพรอมต์ รับคำตอบ แล้วนำคำตอบไปใช้ในแอปพลิเคชัน

วิธีนั้นใช้ได้ดีกับงานง่ายๆ แต่จะซับซ้อนขึ้นเมื่อโมเดลต้องเขียนโค้ด รันโค้ด ตรวจผลลัพธ์ จัดการไฟล์ แก้ข้อผิดพลาด และทำงานต่อไปจนงานเสร็จจริง.

ตรงนี้แหละที่ Agents API ของ OpenAI มีประโยชน์มาก

แทนที่จะต้องสร้างทุกขั้นตอนเอง สามารถมอบหมายงานให้เอเจนต์ พร้อมไฟล์ที่ต้องใช้ และสภาพแวดล้อมสำหรับทำงาน แล้วปล่อยให้เอเจนต์จัดการส่วนที่เหลือ

ในบทช่วยสอนนี้ จะยกตัวอย่างที่เรียบง่าย เราจะสร้างชุดข้อมูลยอดขายคาเฟ่จำลองขนาดเล็กแล้วส่งให้เอเจนต์ เอเจนต์จะเขียนและรันการวิเคราะห์ ตรวจสอบผลลัพธ์ และสร้างไฟล์ผลลัพธ์ 3 ไฟล์ให้เรา

เมื่อเห็นทุกอย่างทำงานเบื้องหลังแล้ว จะเริ่มมองออกว่ากระบวนการทำโค้ดปกติถูกทำให้อัตโนมัติมากแค่ไหน 

ถ้าเพิ่งเริ่มต้นกับเอเจนต์ AI แนะนำให้ดู เส้นทางทักษะพื้นฐาน AI Agentsของเรา 

OpenAI Agents API คืออะไร?

OpenAI Agents API ช่วยให้มอบหมายงานให้เอเจนต์ พร้อมไฟล์ที่ต้องใช้ และสภาพแวดล้อมที่ควรทำงาน แล้วปล่อยให้เอเจนต์จัดการส่วนที่เหลือ

แทนที่จะต้องสร้างแซนด์บ็อกซ์ เปิดเซสชัน อัปโหลดไฟล์ รันโค้ด เช็กข้อผิดพลาด และจัดการทุกขั้นตอนเอง สามารถส่งคำขอ API ครั้งเดียวพร้อมงาน การตั้งค่า สภาพแวดล้อม และไฟล์อินพุต

หลังจากนั้น งานส่วนใหญ่จะถูกจัดการโดย Agents API

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

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

เหมาะอย่างยิ่งสำหรับงานที่ซับซ้อนและใช้เวลานาน ซึ่งเอเจนต์ต้องลงมือทำงานจริง ไม่ใช่แค่ส่งคำตอบกลับมา

สำหรับบทช่วยสอนนี้ เราจะใช้แซนด์บ็อกซ์ที่โฮสต์โดย OpenAI:

เราส่งคำขอครั้งเดียวพร้อมไฟล์ CSV งาน และการตั้งค่าเอเจนต์ 

จากนั้น Agents API จะสร้างและจัดการเซสชันและแซนด์บ็อกซ์ให้เรา

ภายในแซนด์บ็อกซ์ เอเจนต์สามารถดูไฟล์ คิดวิธีการวิเคราะห์ สร้างโค้ด Python รันโค้ด ตรวจผลลัพธ์ และแก้ไขหากมีปัญหา

เมื่อทุกอย่างเสร็จ ผลลัพธ์จะถูกบันทึกเป็นสิ่งประดิษฐ์ของเซสชัน (session artifacts) 

สิ่งเหล่านี้อาจเป็นแผนภูมิ ชุดข้อมูลที่ทำความสะอาดแล้ว รายงาน หรือไฟล์อื่นๆ ที่เอเจนต์สร้างขึ้น จากนั้นสามารถดึงไฟล์เหล่านั้นมาให้ผู้ใช้ดาวน์โหลดและตรวจสอบได้

แนวคิดหลักเรียบง่ายมาก: เราส่งงานครั้งเดียว แล้วเอเจนต์จัดการทำงานจริงต่อจากนั้น

OpenAI Responses API เทียบกับ Agents SDK เทียบกับ Agents API: ควรใช้แบบไหน?

ความแตกต่างหลักของทั้งสามคืออยากจัดการเวิร์กโฟลว์ด้วยตัวเองมากน้อยแค่ไหน.

ใช้ Responses API เมื่อต้องการให้โมเดลทำงานที่มีขอบเขตชัดเจน เช่น สรุปข้อมูล ดึงข้อมูล จัดหมวดหมู่ ตอบคำถาม เอาต์พุตแบบมีโครงสร้าง หรือเรียกเครื่องมือไม่กี่ครั้ง

ใช้ Agents SDK เมื่อต้องการสร้างแอปเอเจนต์เองและอยากควบคุมเอเจนต์ เครื่องมือ การส่งต่อ Guardrails และเวิร์กโฟลว์หลายเอเจนต์มากขึ้น

ใช้ Agents API เมื่องานซับซ้อนและต้องการสภาพแวดล้อมการทำงานของตัวเอง เหมาะเมื่อเอเจนต์ต้องทำงานกับไฟล์ รันโค้ด ตรวจผลลัพธ์ แก้ข้อผิดพลาด และทำงานต่อหลายขั้นตอน

ไกด์ทีละขั้น: สร้างเอเจนต์วิเคราะห์ข้อมูลด้วย OpenAI

สำหรับบทช่วยสอนนี้ เราใช้Agents API เพราะเอเจนต์ต้องทำงานกับไฟล์ ให้เหตุผลด้านการวิเคราะห์ รันโค้ด ตรวจผลลัพธ์ และบันทึกสิ่งประดิษฐ์สุดท้ายให้ผู้ใช้

มาเริ่มกันเลย

1. ตั้งค่าสภาพแวดล้อม Python สำหรับ Agents API

ในบทช่วยสอนนี้ เราจะใช้ Jupyter Notebook เพื่อทดสอบ Agents API ทีละขั้นและเข้าใจการทำงานของแต่ละส่วน 

เริ่มจากติดตั้งแพ็กเกจ OpenAI และนำเข้าไลบรารีที่ต้องใช้สำหรับส่วนถัดไปของบทช่วยสอน

ก่อนอื่น ติดตั้งหรืออัปเกรดแพ็กเกจ OpenAI สำหรับ Python:

%pip install -q --upgrade openai

จากนั้นนำเข้าไลบรารีที่เราจะใช้:

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

ตอนนี้ให้สร้างไคลเอนต์ OpenAI:

client = OpenAI()

ตรวจสอบให้แน่ใจว่าได้ตั้งค่า OPENAI_API_KEY ไว้ในสภาพแวดล้อมแล้ว ไคลเอนต์ OpenAI จะตรวจจับได้อัตโนมัติ

2. สร้างข้อมูลตัวอย่างสำหรับเอเจนต์ AI

เราจะสร้างชุดข้อมูลยอดขายจำลองขนาดเล็กเพื่อใช้ส่งให้ง่ายๆ แก่เอเจนต์

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]),
        }
    )

โค้ดนี้สร้างออเดอร์คาเฟ่จำลอง 50 ออเดอร์ ครอบคลุมผลิตภัณฑ์ สาขา วันที่ และส่วนลดที่ต่างกัน เราตั้งค่า seed แบบตายตัวเพื่อให้ได้ชุดข้อมูลเดิมทุกครั้งที่รันโน้ตบุ๊ก

3. สร้างและเข้ารหัสไฟล์ CSV สำหรับแซนด์บ็อกซ์ของเอเจนต์

ต่อไป เราจะเปลี่ยนข้อมูลที่สร้างขึ้นให้เป็นไฟล์ CSV เพื่อส่งต่อให้เอเจนต์ได้

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]))

ผลลัพธ์:

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

เรายังคงเข้ารหัส CSV เป็น Base64 เพราะจะส่งไฟล์ไปพร้อมคำขอของเอเจนต์โดยตรง

4. กำหนดงานของเอเจนต์และผลลัพธ์ที่คาดหวัง

ตอนนี้จะอธิบายว่าอยากให้เอเจนต์ทำอะไรกับไฟล์ 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()

ส่วนสำคัญคือการอธิบายเป้าหมายและผลลัพธ์ที่คาดหวัง แทนที่จะเขียนโค้ดวิเคราะห์เอง

เอเจนต์สามารถตัดสินใจวิธีทำงาน รันโค้ด และตรวจสอบผลลัพธ์ก่อนจบงาน

5. รันเอเจนต์ในแซนด์บ็อกซ์ที่โฮสต์โดย OpenAI

ตอนนี้จะส่งทุกอย่างไปยัง Agents API ในคำขอเดียว แล้วให้เอเจนต์ทำงานจริงบนคลาวด์

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}")

ตรงนี้เองที่งานส่วนใหญ่เกิดขึ้น

เราส่งคำขอเดียวที่มีการตั้งค่าเอเจนต์ สภาพแวดล้อมที่โฮสต์ ไฟล์ CSV และงาน 

OpenAI สร้างเซสชันที่มีการจัดการและรันเอเจนต์ภายในแซนด์บ็อกซ์ที่โฮสต์ เอเจนต์สามารถตรวจไฟล์ เขียน analyze_sales.py รันโค้ด ตรวจผลลัพธ์ แก้ไขสิ่งที่ผิดพลาด และสร้างไฟล์ผลลัพธ์สุดท้ายได้ 

เอ็นด์พอยต์สร้างเซสชันรองรับทั้งสภาพแวดล้อมและอินพุตเริ่มต้นในคำขอเดียว

มี 3 ส่วนหลักของคำขอ:

• agent ระบุให้ OpenAI ทราบว่าจะใช้โมเดลใดและเอเจนต์ควรปฏิบัติตัวอย่างไร
• environment ให้พื้นที่ทำงานที่โฮสต์แก่เอเจนต์และวางไฟล์ CSV ของเราไว้ภายใน
• input มอบงานที่เรากำหนดไว้ในส่วนก่อนหน้าให้เอเจนต์

เรายังกำหนด stream=True ไว้ด้วย 

สิ่งนี้ไม่เปลี่ยนวิธีการทำงานของงาน เพียงแค่ให้เรารับอีเวนต์ระหว่างที่เอเจนต์ทำงาน แทนที่จะต้องรอให้ทั้งเทิร์นเสร็จก่อนจึงจะเห็นอะไรบางอย่าง

ในตัวอย่างนี้ เราฟังอีเวนต์ agent.session.turn.output_text.delta และอัปเดตโน้ตบุ๊กด้วยข้อความล่าสุดอย่างต่อเนื่อง

ดังนั้น ข้อความที่ค่อยๆ ปรากฏด้านบนคือเอเจนต์รายงานความคืบหน้าและคำตอบสุดท้ายของมัน 

ตัวงานจริงจะทำต่อในสภาพแวดล้อมที่โฮสต์จนกว่าเราจะได้รับอีเวนต์ agent.session.turn.completed

ในการรันของฉัน เอเจนต์ได้สร้างและรัน analyze_sales.py ตรวจสอบไฟล์ที่สร้างขึ้น และยืนยันยอดขายสุทธิรวมที่ 600.55.

สิ่งสำคัญคือโมเดลไม่ได้แค่บอกให้เราไปรันโค้ด Python อะไร เอเจนต์ลงมือเขียนโค้ด รัน ตรวจผลลัพธ์ และยืนยันเอาต์พุตด้วยตัวเอง

6. ดึงและดาวน์โหลดไฟล์สิ่งประดิษฐ์ของเอเจนต์

เมื่อเอเจนต์ทำเสร็จแล้ว เราสามารถดาวน์โหลดไฟล์ที่มันสร้างไว้ในเทิร์นนั้นได้

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}")

ผลลัพธ์:

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

ในส่วนนี้ เราลิสต์สิ่งประดิษฐ์จากเซสชัน เก็บเฉพาะที่สร้างโดยเทิร์นที่เสร็จแล้ว และดาวน์โหลดลงโฟลเดอร์ cloud_bean_results ในเครื่องของเรา

7. ลบเซสชันเพื่อลดค่าใช้จ่ายคอมพิวต์ของแซนด์บ็อกซ์

เมื่อจัดการไฟล์เสร็จ ควรลบเซสชันเพื่อไม่ให้คงสภาพแวดล้อมที่จัดการไว้นานเกินจำเป็น

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

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

ผลลัพธ์:

Session deleted: True

คำสั่งนี้จะลบเซสชันที่มีการจัดการออกจาก API 

OpenAI ระบุว่าการทำความสะอาดทรัพยากรจริงเบื้องหลังอาจดำเนินต่อแบบอะซิงก์หลังคำขอลบเสร็จแล้ว

ขั้นตอนนี้สำคัญเป็นพิเศษเมื่อใช้แซนด์บ็อกซ์ที่โฮสต์โดย OpenAI 

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

ดังนั้น ถ้ายังคงให้เซสชันและสภาพแวดล้อมทำงานอยู่นานเกินจำเป็น ก็อาจเพิ่มค่าใช้จ่ายคอมพิวต์ได้

ข้อคิดส่งท้าย: OpenAI Agents API คุ้มค่ากับต้นทุนหรือไม่?

สิ่งที่สะดุดตาเกี่ยวกับ Agents API คือทำอะไรได้มากจากการเรียก API แบบง่ายครั้งเดียว.

เราให้ไฟล์ งาน การตั้งค่าโมเดล และสภาพแวดล้อมที่โฮสต์แก่เอเจนต์ 

จากนั้นมันจัดการส่วนที่เหลือ: สร้างพื้นที่ทำงาน ตรวจข้อมูล เขียนโค้ด Python รันโค้ด เช็กเอาต์พุต แก้ไขหากจำเป็น และผลิตสิ่งประดิษฐ์สุดท้าย

ความรู้สึกเหมือนมี Codex รันอยู่บนคลาวด์สำหรับแอปของคุณ 

ไม่ต้องกังวลกับการตั้งค่าคอมพิวต์ จัดการลูปการรันงาน จัดการไฟล์กลางทาง หรือคอยติดตามทุกขั้นตอน ส่วนใหญ่แค่กำหนดงานให้ชัดแล้วดูผลลัพธ์

การรันหนึ่งครั้งใช้เวลาประมาณสองนาที แต่ในช่วงนั้นเอเจนต์ทำงานเบื้องหลังค่อนข้างมาก

นี่แหละที่ทำให้ต่างจากคำขอ API ปกติ 

ไม่ได้แค่รอให้โมเดลสร้างข้อความ แต่รอให้เอเจนต์ทำงานชิ้นหนึ่งให้เสร็จจริง

จากการทดสอบของฉัน การรันตัวอย่างนี้สามครั้งมีค่าใช้จ่ายรวมประมาณ $1.52 รวมทั้งค่าใช้โมเดลและสภาพแวดล้อมที่โฮสต์ 

สำหรับงานเล็กๆ นี่ไม่ถูก ดังนั้นสำหรับงานจริง แนะนำให้ทดสอบโมเดลที่เล็กกว่าหรือถูกกว่าก่อนแน่นอน

แต่สำหรับงานที่ซับซ้อนกว่านี้ซึ่งเกี่ยวกับการเขียนโค้ด ดีบัก ไฟล์ การให้เหตุผล และหลายขั้นตอนที่พึ่งพากัน ต้นทุนที่เพิ่มขึ้นอาจสมเหตุสมผลมากขึ้น