Tutorial OpenAI Agents API: Bangun Agen yang Menulis dan Menjalankan Kode di Cloud

Sebagian besar aplikasi LLM mengikuti pola sederhana: kirim prompt, dapatkan respons, lalu gunakan respons itu di aplikasi Anda.

Itu berjalan baik untuk tugas sederhana, tetapi menjadi lebih rumit ketika model perlu menulis kode, menjalankannya, memeriksa hasilnya, bekerja dengan file, memperbaiki error, dan terus berjalan hingga tugas benar-benar selesai.

Di sinilah Agents API dari OpenAI menjadi sangat berguna.

Alih-alih membangun setiap langkah sendiri, Anda dapat memberikan tugas, file yang dibutuhkan, dan lingkungan kerja kepada agen, lalu biarkan ia menangani sisanya.

Dalam tutorial ini, saya akan menjaga contohnya sederhana. Kita akan membuat dataset penjualan kafe fiksi kecil dan memberikannya kepada agen. Agen akan menulis dan menjalankan analisis, memverifikasi hasil, dan membuat tiga file keluaran untuk kita.

Setelah Anda melihat seluruh proses berjalan di balik layar, Anda akan mulai menyadari betapa banyak alur kerja pemrograman biasa yang diotomatisasi untuk Anda. 

Jika Anda baru dengan agen AI, saya sarankan melihat AI Agents Fundamentals Skill track kami. 

Apa itu OpenAI Agents API?

OpenAI Agents API memungkinkan Anda memberi agen sebuah tugas, file yang dibutuhkan, dan lingkungan kerja, lalu membiarkannya menangani sisanya.

Alih-alih secara manual membuat sandbox, memulai sesi, mengunggah file, menjalankan kode, memeriksa error, dan mengelola setiap langkah sendiri, Anda dapat mengirim satu permintaan API berisi tugas, konfigurasi, lingkungan, dan file input.

Setelah itu, sebagian besar pekerjaan ditangani oleh Agents API.

Di balik layar, OpenAI mengelola Codex harness, termasuk orkestrasi, konteks, penggunaan alat, eksekusi, dan sesi berdurasi panjang. Anda bisa membayangkannya hampir seperti memiliki OpenAI Codex yang berjalan di cloud untuk aplikasi Anda. 

Anda tidak perlu terlalu mengkhawatirkan penyiapan komputasi, pengelolaan lingkungan kerja, pelacakan sesi, atau membangun loop agen penuh sendiri.

Ini sangat berguna untuk tugas yang lebih kompleks dan berdurasi lama di mana agen perlu benar-benar mengerjakan tugasnya, bukan hanya mengembalikan jawaban.

Untuk tutorial ini, kita akan menggunakan sandbox yang di-host OpenAI:

Kita mengirim satu permintaan dengan file CSV, tugas, dan konfigurasi agen. 

Agents API kemudian membuat dan mengelola sesi serta sandbox untuk kita.

Di dalam sandbox, agen bisa melihat file, menentukan pendekatan analisis, menghasilkan kode Python, menjalankannya, memeriksa hasil, dan memperbaiki jika ada yang salah.

Setelah semuanya selesai, output disimpan sebagai artefak sesi. 

Ini bisa berupa bagan, dataset yang dibersihkan, laporan, atau file lain apa pun yang dibuat agen. Kita kemudian dapat mengambil file tersebut dan memungkinkan pengguna mengunduh serta meninjaunya.

Jadi idenya sederhana: kita mengirim tugas sekali, dan agen menangani pekerjaan sebenarnya setelahnya.

OpenAI Responses API vs Agents SDK vs Agents API: Mana yang Harus Anda Gunakan?

Perbedaan utama ketiganya adalah seberapa banyak alur kerja yang ingin Anda kelola sendiri.

Gunakan Responses API saat Anda memerlukan model untuk menyelesaikan tugas terfokus, seperti peringkasan, ekstraksi, klasifikasi, tanya jawab, output terstruktur, atau beberapa pemanggilan alat.

Gunakan Agents SDK saat Anda membangun aplikasi agen sendiri dan menginginkan kontrol lebih atas agen, alat, handoff, guardrail, dan alur kerja multi-agen.

Gunakan Agents API saat tugas lebih kompleks dan memerlukan lingkungan kerja sendiri. Ini berguna saat agen perlu bekerja dengan file, menjalankan kode, memeriksa hasil, memperbaiki error, dan terus berjalan di banyak langkah.

Panduan Langkah demi Langkah: Membangun Agen Analisis Data dengan OpenAI

Untuk tutorial ini, kita menggunakan Agents API karena agen perlu bekerja dengan sebuah file, mempertimbangkan analisis, menjalankan kode, memeriksa hasil, dan menyimpan artefak akhir untuk pengguna.

Mari kita mulai

1. Siapkan lingkungan Python Anda untuk Agents API

Untuk tutorial ini, kita akan menggunakan Jupyter Notebook untuk menguji Agents API selangkah demi selangkah dan memahami cara kerja setiap bagiannya. 

Kita akan mulai dengan memasang paket OpenAI dan mengimpor pustaka yang dibutuhkan untuk sisa tutorial.

Pertama, pasang atau tingkatkan paket OpenAI untuk Python:

%pip install -q --upgrade openai

Lalu impor pustaka yang akan kita gunakan:

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

Sekarang buat klien OpenAI:

client = OpenAI()

Pastikan OPENAI_API_KEY Anda sudah disetel di lingkungan Anda. Klien OpenAI akan mengambilnya secara otomatis.

2. Hasilkan data contoh untuk agen AI

Kita akan membuat dataset penjualan palsu kecil agar kita punya sesuatu yang sederhana untuk diberikan ke agen.

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

Ini membuat 50 pesanan kafe palsu di berbagai produk, lokasi, tanggal, dan diskon. Kami menggunakan seed acak tetap agar dataset yang sama dihasilkan setiap kali kami menjalankan notebook.

3. Buat dan enkode file CSV untuk sandbox agen

Selanjutnya, kita akan mengubah data yang dihasilkan menjadi file CSV yang dapat diteruskan ke agen.

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

Keluaran:

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

Kita juga melakukan pengodean Base64 pada CSV karena kita akan mengirim file tersebut langsung bersama permintaan agen.

4. Tentukan tugas agen dan output yang diharapkan

Sekarang kita akan menjelaskan apa yang kita ingin agen lakukan dengan file 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()

Bagian pentingnya adalah kita menjelaskan tujuan dan output yang diharapkan, alih-alih menulis kode analisis sendiri.

Agen dapat memutuskan cara melakukan pekerjaan, menjalankan kode, dan memverifikasi hasil sebelum selesai.

5. Jalankan agen di sandbox yang di-host OpenAI

Sekarang kita akan mengirim semuanya ke Agents API dalam satu permintaan dan membiarkan agen melakukan pekerjaan sebenarnya di cloud.

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

Di sinilah sebagian besar pekerjaan terjadi.

Kita membuat satu permintaan yang berisi konfigurasi agen, lingkungan yang di-host, file CSV, dan tugas. 

OpenAI membuat sesi terkelola dan menjalankan agen di dalam sandbox yang di-host. Agen kemudian dapat memeriksa file, menulis analyze_sales.py, mengeksekusinya, memeriksa hasil, memperbaiki apa pun yang salah, dan membuat file output akhir. 

Endpoint pembuatan sesi mendukung baik lingkungan maupun input awal dalam satu permintaan.

Ada tiga bagian utama pada permintaan:

• agent memberi tahu OpenAI model mana yang digunakan dan bagaimana perilaku agen.
• environment memberi agen ruang kerja yang di-host dan menempatkan file CSV kita di dalamnya.
• input memberikan tugas yang kita definisikan pada bagian sebelumnya.

Kita juga menyetel stream=True. 

Ini tidak mengubah bagaimana tugas diselesaikan. Ini hanya memungkinkan kita menerima event saat agen bekerja alih-alih menunggu seluruh giliran selesai sebelum melihat apa pun.

Dalam contoh ini, kita mendengarkan event agent.session.turn.output_text.delta dan terus memperbarui notebook dengan teks terbaru.

Jadi teks yang muncul di atas adalah laporan kemajuan dan respons akhir dari agen. 

Tugas sebenarnya terus berjalan di lingkungan yang di-host hingga kita menerima event agent.session.turn.completed.

Dalam percobaan saya, agen membuat dan menjalankan analyze_sales.py, memeriksa file yang dihasilkan, dan memverifikasi total penjualan bersih sebesar 600,55.

Bagian pentingnya adalah model tidak hanya memberi tahu kita kode Python apa yang harus dijalankan. Agen benar-benar menulis kode, mengeksekusinya, memeriksa hasil, dan memverifikasi output sendiri.

6. Ambil dan unduh artefak file milik agen

Sekarang agen sudah selesai, kita dapat mengunduh file yang dibuatnya selama giliran tersebut.

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

Keluaran:

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

Di sini, kita membuat daftar artefak dari sesi, menyimpan yang dibuat oleh giliran yang telah selesai, dan mengunduhnya ke folder lokal cloud_bean_results.

7. Hapus sesi untuk menghemat biaya komputasi sandbox

Setelah selesai dengan file, kita harus menghapus sesi agar tidak mempertahankan lingkungan terkelola lebih lama dari yang diperlukan.

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

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

Keluaran:

Session deleted: True

Ini menghapus sesi terkelola dari API. 

OpenAI mencatat bahwa pembersihan fisik sumber daya dasar dapat berlanjut secara asinkron setelah permintaan penghapusan dikembalikan.

Langkah ini sangat penting saat menggunakan sandbox yang di-host OpenAI. 

Sandbox adalah lingkungan komputasi tempat agen menjalankan kode dan bekerja dengan file, dan sandbox yang di-host menggunakan komputasi kontainer yang ditagihkan terpisah dari penggunaan model. 

Jadi jika Anda membiarkan sesi dan lingkungan tetap berjalan lebih lama dari yang diperlukan, Anda dapat terus menambah biaya komputasi.

Pemikiran Akhir: Apakah OpenAI Agents API Layak Biayanya?

Yang paling menonjol bagi saya tentang Agents API adalah seberapa banyak yang dapat dilakukan dari satu panggilan API sederhana.

Kita memberikannya file, tugas, konfigurasi model, dan lingkungan yang di-host. 

Dari sana, ia menangani sisanya: membuat ruang kerja, memeriksa data, menulis kode Python, menjalankannya, memeriksa output, memperbaiki jika diperlukan, dan menghasilkan artefak akhir.

Rasanya benar-benar seperti memiliki Codex yang berjalan di cloud untuk aplikasi Anda. 

Saya tidak perlu khawatir menyiapkan komputasi, mengelola loop eksekusi, menangani file perantara, atau melacak setiap langkah. Saya terutama hanya perlu mendefinisikan tugas dengan baik, lalu melihat hasilnya.

Prosesnya sendiri memakan waktu sekitar dua menit, tetapi selama itu, agen melakukan cukup banyak hal di balik layar.

Itulah yang membuat ini berbeda dari permintaan API biasa. 

Anda bukan hanya menunggu model menghasilkan teks. Anda menunggu agen benar-benar menyelesaikan sebuah pekerjaan.

Dalam pengujian saya, tiga kali menjalankan contoh ini menelan biaya sekitar $1,52 secara total, termasuk penggunaan model dan lingkungan yang di-host. 

Untuk tugas sekecil ini, itu tidak murah, jadi untuk produksi, saya pasti akan menguji model yang lebih kecil atau lebih murah terlebih dahulu.

Namun untuk pekerjaan yang lebih kompleks yang melibatkan pengodean, debugging, file, penalaran, dan banyak langkah yang saling bergantung, biaya ekstra tersebut bisa jauh lebih masuk akal.