Skip to main content
BlogAI

OpenAI Agents API vs Agents SDK vs Responses API: Pilih Mana?

OpenAI kini mendokumentasikan empat cara membangun agent. Panduan memilih Agents API, Agents SDK, Responses API dan ChatKit: siapa pemilik loop, di mana state disimpan, ZDR, data residency, biaya dan lock-in.

Matthews Wong

Software Engineer

Oktober 202611 menit baca
OpenAI Agents API vs Agents SDK vs Responses API: Pilih Mana?

Ringkasan Utama

OpenAI mendokumentasikan empat cara membangun agent. Agents API menjalankan Codex harness terkelola untuk Anda, tetapi hanya mendukung data residency di Amerika Serikat dan tanpa Zero Data Retention. Agents SDK menjalankan loop di dalam proses Anda sendiri dengan storage Anda sendiri. Responses API adalah panggilan model mentah. ChatKit hanyalah UI chat yang bisa di-embed.

Bayangkan asisten accounts-payable untuk tim ERP: ia membaca invoice yang masih terbuka, menjelaskan selisih kepada staf, dan tidak pernah mem-posting apa pun sendiri. OpenAI kini menawarkan empat titik awal untuk membangunnya, dan pertanyaan pertama klien finance jarang soal model, melainkan di mana data invoice akan disimpan. Satu pertanyaan itu bisa menggugurkan satu opsi sebelum sebaris kode pun ditulis.

Panduan ini membandingkan Agents API, Agents SDK, Responses API mentah dan ChatKit pada sumbu yang benar-benar menentukan pilihan: siapa pemilik agent loop, di mana state disimpan, kelayakan Zero Data Retention, data residency, biaya dan lock-in. Setiap klaim kapabilitas berasal dari dokumentasi resmi OpenAI per Oktober 2026, dengan tautan di bagian akhir, dan setiap opsi dipetakan ke pekerjaan nyata seperti job back-office ERP, chat pelanggan, atau task CI.

OpenAI Agents API vs Agents SDK: siapa pemilik loop

Setiap agent adalah sebuah loop: panggil model, jalankan tool yang dimintanya, kembalikan hasilnya, lalu putuskan apakah berhenti. Empat opsi yang didokumentasikan OpenAI terutama berbeda dalam hal siapa yang menulis dan meng-host loop itu, dan sisa perbandingan mengikuti dari fakta tersebut.

  • Agents API: OpenAI menjalankan Codex harness terkelola. Anda membuat session, mengirim pekerjaan sebagai event, dan OpenAI menangani orkestrasi, context compaction, recovery, dan subagent.
  • Agents SDK: library yang runner-nya mengeksekusi loop di dalam aplikasi Anda. Deployment, storage, approval, dan integrasi runtime tetap di tangan Anda.
  • Responses API: panggilan model langsung. Loop apa pun yang ada adalah loop yang Anda tulis sendiri, dengan hosted tool opsional di sampingnya.
  • ChatKit: antarmuka chat yang bisa di-embed. Ia tercantum bersama tiga opsi lain karena merupakan titik awal, tetapi tidak menjalankan agent dengan sendirinya.

Perbandingan resmi OpenAI menilai upaya integrasi rendah untuk Agents API, sedang untuk SDK, dan tinggi untuk Responses API. Penilaian itu jujur, dan sekaligus menunjukkan trade-off-nya: makin sedikit yang Anda integrasikan, makin sedikit kendali Anda atas ke mana data pergi dan bagaimana loop berperilaku saat terjadi kegagalan.

Tabel perbandingan, baris demi baris

Tabel di bawah menggabungkan perbandingan runtime OpenAI dengan halaman data controls, sumber baris ZDR dan residency. Dua baris itulah yang paling sering dilewatkan artikel perbandingan, padahal untuk data ERP yang diatur regulasi, dua baris itu biasanya yang menentukan pilihan.

DimensiAgents APIAgents SDKResponses APIChatKit
Pemilik loopOpenAI, lewat Codex harness terkelolaRunner SDK, di dalam proses AndaAnda tulis dari nolTidak ada: ini UI di atas backend pilihan Anda
State antar taskKonfigurasi session, turn, dan item tersimpan di OpenAIStorage Anda lewat SDK session, atau conversation state ResponsesHistory manual, response chaining, atau ConversationsApa pun yang disimpan backend di belakangnya
Lingkungan eksekusiSandbox yang di-host OpenAI, sandbox self-hosted, atau tanpa sandboxRuntime Anda plus integrasi penyedia sandboxLingkungan eksekusi Anda sendiriFront end di browser plus server Anda
Upaya integrasi, menurut OpenAIRendahSedangTinggiTidak dinilai: ini lapisan UI
Zero Data RetentionTidak didukung, bahkan dengan sandbox self-hostedMengikuti endpoint yang dipanggil: Responses layak dengan batasan, state berbasis Conversations tidak/v1/responses layak dengan batasan, store dipaksa false; /v1/conversations tidak layakMengikuti backend yang dihubunginya
Data residencyHanya Amerika SerikatMengikuti endpoint yang dipanggil, jadi regional storage dimungkinkan/v1/responses tercantum untuk regional storage di sepuluh region, termasuk SingapuraMengikuti backend yang dihubunginya
Biaya di luar token modelTanpa biaya platform; tool OpenAI dengan tarif standar, sandbox hosted dengan tarif containerCompute Anda, storage Anda, tagihan penyedia sandbox AndaCompute Anda, plus setiap hosted tool yang Anda aktifkanHosting server yang dihubunginya
Lock-inPaling tinggi: objek session dan perilaku harness berada di OpenAISedang: kodenya milik Anda, dan history manual bisa dipakai dengan provider mana punPaling rendah di level API, tetapi Anda membangun ulang semua yang diberikan opsi lainRendah: UI bisa diarahkan ke backend lain
Cocok untukTask panjang di mana OpenAI mengelola agent dan menyimpan progresnyaTool, approval, dan workflow kustom di dalam aplikasi AndaKendali model langsung atau agent yang dibangun dari nolMenambahkan pengalaman chat yang di-embed

Dua baris memikul sebagian besar bobot keputusan. Baris ZDR bersifat mutlak untuk Agents API: OpenAI menyatakan dengan jelas bahwa Agents API tidak mendukung Zero Data Retention dan memilih sandbox self-hosted tidak membuatnya layak. Baris residency pun sama. Tiga opsi lainnya mewarisi kontrol dari endpoint mana pun yang mereka panggil, itulah sebabnya selnya bertuliskan mengikuti, bukan ya atau tidak.

Agents API: OpenAI menjalankan harness, Anda mengirim event

Agents API dibangun di atas empat objek: agent (model, instruksi, tool, MCP server), environment opsional, session yang durable, serta event dan item yang mengalir masuk dan keluar. Turn berjalan secara asinkron. Pesan yang dikirim ke session yang idle memulai turn baru, sedangkan tipe pesan yang sama yang dikirim saat turn aktif justru mengarahkan ulang turn tersebut. Seluruh lifecycle-nya muat dalam satu blok, ditulis dengan permukaan SDK beta yang dipakai dokumentasi.

import OpenAI from "openai";

const client = new OpenAI();

// 1. Create the session AND start the first turn in one request.
//    OpenAI provisions the sandbox; you never see the agent loop.
const events = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Reconcile yesterday's goods receipts against open purchase orders. " +
      "Report mismatches; never post anything.",
  },
  environment: { type: "openai_hosted" },
  input: "Run the reconciliation for warehouse JKT-01.",
  stream: true,
});

for await (const event of events) {
  // An idle session is NOT success. Wait for the turn outcome:
  // agent.session.turn.completed | .failed | .cancelled
  console.log(event.type);
}

// 2. The same call steers a running turn or starts a new one on an idle
//    session. Persist the session id next to your own job record.
const sessionId = job.agentSessionId; // saved from the session's events
await client.beta.agents.sessions.events.create(sessionId, {
  events: [
    {
      type: "agent.session.input.message",
      input: [
        {
          role: "user",
          content: [{ type: "input_text", text: "Skip JKT-02, it is mid-stocktake." }],
        },
      ],
    },
  ],
});

// 3. Stop the turn; the session and its earlier work survive.
await client.beta.agents.sessions.events.create(sessionId, {
  events: [{ type: "agent.session.input.cancel" }],
});

Tiga detail dalam kode itu mudah terlewat. Pertama, session yang idle tidak berarti turn berhasil; dokumentasi menyuruh Anda memeriksa event turn completed, failed, atau cancelled dan memeriksa output-nya, karena turn yang completed tidak menjamin setiap tool call berhasil. Kedua, function tool tetap berjalan di kode Anda: saat session membutuhkan hasil function, ia memunculkan required_actions, dan tidak ada yang berlanjut sampai Anda menjawab. Ketiga, runtime menerima request hingga 4 MiB, input ditambah output schema, jadi dokumen besar diunggah ke environment, bukan disisipkan langsung.

Baca baris data controls sebelum daftar fitur. Agents API saat ini hanya mendukung data residency di Amerika Serikat dan tidak mendukung Zero Data Retention, dan sandbox self-hosted tidak mengubah kedua fakta itu. State session disimpan agar pekerjaan bisa berlanjut antar turn sampai Anda menghapus session-nya. Jika kontrak klien menyatakan data invoice atau payroll tidak boleh keluar dari suatu region, opsi ini gugur, senyaman apa pun harness-nya.

Agents SDK: loop berjalan di proses Anda

Agents SDK adalah library, tersedia dalam Python dan TypeScript, yang runner-nya menangani loop dan handoff di dalam aplikasi Anda. Bagian yang penting untuk perbandingan ini adalah state. Dokumentasi Python mencantumkan empat strategi: menyusun ulang input sendiri dengan to_input_list, memakai SDK session yang didukung store Anda sendiri, menunjuk conversation_id di sisi server, atau berantai dengan previous_response_id. Hanya dua yang pertama yang menjaga percakapan tetap di luar server OpenAI.

from agents import Agent, Runner, SQLiteSession, function_tool

@function_tool
def open_invoices(vendor_code: str) -> list[dict]:
    """Read-only lookup against the ERP database you already run."""
    return erp.query_open_invoices(vendor_code)

agent = Agent(
    name="AP clerk",
    instructions="Answer accounts-payable questions. Never approve payments.",
    tools=[open_invoices],
)

# Option A: history lives in YOUR storage (SQLite here; swap the class for
# your own store). Works with any provider the SDK can call.
session = SQLiteSession("vendor-V0042")
result = await Runner.run(agent, "What is open for V0042?", session=session, max_turns=8)
result = await Runner.run(agent, "Which of those are overdue?", session=session, max_turns=8)

# Option B: history lives on OpenAI as a Conversation object.
conversation = await client.conversations.create()
result = await Runner.run(agent, "What is open for V0042?", conversation_id=conversation.id)

# Wrong: session= together with conversation_id / previous_response_id.
# The SDK does not allow both state strategies in the same run.

Dua aturan dari dokumentasi running agents menyelamatkan saya dari satu sesi debugging. Session tidak bisa digabung dengan conversation_id, previous_response_id, atau auto_previous_response_id dalam run yang sama, jadi pilih satu strategi per agent dan konsisten. Lalu max_turns adalah jaring pengaman sungguhan: run yang melampauinya melempar MaxTurnsExceeded alih-alih terus berputar sampai tagihan yang memberi tahu. Set secara eksplisit di setiap job back-office; memberi nilai None mematikan batasnya, dan itu persis yang tidak boleh dilakukan job ERP tanpa pengawasan.

Responses API: ketika tanpa framework justru pilihan yang tepat

OpenAI menilai Responses API sebagai opsi dengan upaya tinggi, dan untuk agent multi-langkah yang sesungguhnya memang begitu. Namun banyak pekerjaan yang disebut agentic sebenarnya hanya satu panggilan model dengan schema: mengekstrak purchase order, mengklasifikasi tiket, merangkum dokumen. Untuk pekerjaan seperti itu, runtime agent menambahkan session, batas turn, dan state yang harus Anda bersihkan, tanpa memberi apa-apa.

from openai import OpenAI

client = OpenAI()

# You own everything: the loop, the tool dispatch, the history list.
history = [{"role": "user", "content": "Summarise PO-2026-0917 for the buyer."}]

response = client.responses.create(
    model="gpt-6-astra",
    input=history,
    tools=TOOLS,     # your function definitions
    store=False,     # forced to False anyway under ZDR
)

# Not stored server-side, so the next turn cannot lean on OpenAI state:
# append response.output plus your tool results to history and call again,
# and decide yourself when to stop.

Data controls-nya juga paling jelas di sini. Secara default, Responses menyimpan application state selama 30 hari; di bawah Zero Data Retention parameter store selalu diperlakukan sebagai false, bahkan jika request mengaturnya true. Sebaliknya, Conversations disimpan sampai Anda menghapusnya dan tidak layak ZDR. Jika Anda butuh ZDR sekaligus history di sisi server, OpenAI tidak bisa memberikan keduanya, jadi history harus tinggal di database Anda sendiri.

Tidak ada region Indonesia di tabel data residency OpenAI. Singapura yang terdekat, dan /v1/responses tercantum untuk regional storage di sana, tetapi tidak untuk regional processing, dan region itu mensyaratkan Modified Abuse Monitoring atau ZDR. Residency dikonfigurasi per project melalui tim sales OpenAI, dan ada kenaikan harga 10% untuk model yang memenuhi syarat dan dirilis pada atau setelah 5 Maret 2026. Anggarkan itu sebelum menjanjikannya ke klien.

ChatKit adalah front end, bukan runtime keempat

ChatKit berada di tabel titik awal yang sama, sehingga mengundang perbandingan yang keliru. Ia adalah antarmuka chat yang bisa di-embed dengan tool invocation, lampiran file, dan visualisasi, tersedia sebagai React bindings, JS SDK, dan Python server SDK. ChatKit menjawab bagaimana pengguna berbicara dengan agent, bukan bagaimana agent berjalan. Dalam praktiknya ia dipasangkan dengan salah satu dari tiga opsi lain, paling wajar dengan Agents SDK di belakang server Anda sendiri.

Saran deployment-nya berubah tahun ini. Dokumentasi ChatKit kini merekomendasikan menghubungkannya ke layanan agentic Anda sendiri melalui Python SDK, dan memperlakukan integrasi yang di-host Agent Builder sebagai jalur legacy, karena Agent Builder dijadwalkan berhenti pada 30 November 2026. Jika sebuah tutorial menyuruh Anda mem-publish workflow di Agent Builder lalu meng-embed-nya dengan ChatKit, tutorial itu menjelaskan jalur yang akan berakhir.

Mencocokkan setiap opsi dengan pekerjaan nyata

Perbandingan abstrak hanya berguna sampai titik tertentu. Berikut empat pekerjaan yang benar-benar akan saya ajukan ke tim, dengan opsi yang saya pilih dan alasan penentunya.

PekerjaanPilihanAlasan penentu
Job back-office ERP malam hari: mencocokkan goods receipt dengan purchase order dan menandai selisihAgents SDK di worker Anda sendiriData keuangan, tool read-only ke database Anda sendiri, approval di kode Anda, dan history di storage Anda; ketentuan Agents API yang hanya-AS dan tanpa ZDR menggugurkannya bagi banyak klien
Chat status pesanan untuk pelanggan di website perusahaanFront end ChatKit dengan backend Agents SDKChatKit memberi UI, SDK menjaga tool dan auth tetap di server Anda, dan tidak ada yang bergantung pada Agent Builder
Task CI: mereproduksi test yang gagal, menginvestigasi, menyusun draf perbaikanAgents API dengan sandbox yang di-host OpenAIBerjalan lama, butuh shell dan file, diuntungkan oleh compaction, recovery, dan subagent terkelola, dan repository biasanya bukan data yang diregulasi
Ekstraksi volume tinggi: PDF invoice ke JSON terstrukturResponses APISatu panggilan dengan schema, tanpa loop, tidak ada yang perlu dibersihkan, dan layak ZDR jika organisasi memilikinya

Baris CI adalah tempat Agents API membuktikan nilainya. Menjalankan shell dalam sandbox, memadatkan context pada investigasi panjang, dan pulih dari worker yang crash adalah bagian yang lebih baik tidak saya bangun sendiri, dan source code tool internal jauh lebih mudah dibicarakan soal data dibanding buku besar vendor. Baris ERP berakhir sebaliknya karena alasan yang sama.

Memilih tanpa menjebak diri sendiri

Dokumentasi OpenAI menutup perbandingannya dengan peringatan yang layak dianggap serius: session Agents API, SDK session, conversation Responses, dan sandbox adalah resource yang berbeda, masing-masing dengan aturan state dan cleanup sendiri. Pindah di antara keduanya nanti adalah migrasi, bukan perubahan config. Inilah urutan saya mengambil keputusan.

  1. Klasifikasikan datanya terlebih dahulu. Jika job menyentuh data pribadi atau keuangan dengan klausul residency atau retensi, coret Agents API dari daftar sebelum ada yang terpikat oleh demonya.
  2. Tentukan di mana loop berjalan. Jika Anda butuh approval, audit trail, atau infrastruktur worker sendiri, itu SDK; jika Anda ingin OpenAI mengawal task panjang, itu Agents API.
  3. Simpan tool di balik function milik Anda sendiri. Lookup ERP read-only yang ditulis sebagai function biasa bisa berpindah antara SDK, Agents API, dan Responses mentah dengan adapter tipis.
  4. Simpan handle state di database Anda sendiri: session ID, conversation ID, atau key SDK session di samping job atau tiket pemiliknya, lengkap dengan jalur penghapusan untuk masing-masing.

Lock-in tidak otomatis buruk. Lock-in Agents API membeli harness yang dipelihara OpenAI; kebebasan SDK dibayar dengan pekerjaan operasional. Yang menyakitkan adalah memilih salah satunya secara kebetulan lalu baru menemukan baris data controls setelah klien bertanya.

Aturan yang kini saya pegang singkat: tentukan dulu di mana data boleh tinggal, lalu tentukan siapa yang menjalankan loop, baru setelah itu lihat fiturnya. Untuk sebagian besar pekerjaan back-office ERP, hasilnya Agents SDK dengan state di storage Anda sendiri; untuk task engineering dalam sandbox, Agents API adalah yang paling sedikit kodenya; untuk ekstraksi sekali panggil, Responses biasa sudah cukup; dan ChatKit adalah wajah yang Anda pasang di depan opsi mana pun yang dipilih.

FAQ

Pertanyaan Umum

Jawaban singkat untuk pertanyaan yang paling sering diajukan pembaca tentang topik ini.

Apa perbedaan OpenAI Agents API dan Agents SDK?

Agents API adalah layanan hosted: OpenAI menjalankan Codex harness terkelola dan menyimpan session, turn, dan item di sisinya. Agents SDK adalah library Python atau TypeScript yang runner-nya menjalankan agent loop di dalam aplikasi Anda sendiri, sehingga deployment, storage, dan approval ada di kendali Anda.

Apakah OpenAI Agents API mendukung Zero Data Retention?

Tidak. OpenAI mendokumentasikan bahwa Agents API tidak mendukung Zero Data Retention, dan memilih sandbox self-hosted tidak membuatnya layak. Jika Anda butuh ZDR, gunakan Agents SDK atau Responses API dan simpan history percakapan di storage Anda sendiri.

Bisakah data agent disimpan di region selain Amerika Serikat?

Tidak dengan Agents API, yang saat ini hanya mendukung data residency di Amerika Serikat. Responses API tercantum untuk regional storage di sepuluh region, termasuk Singapura, yang terdekat dengan Indonesia. Residency dikonfigurasi per project dan dikenai kenaikan harga 10% untuk model yang memenuhi syarat dan dirilis pada atau setelah 5 Maret 2026.

Kapan sebaiknya memakai Responses API alih-alih framework agent?

Gunakan saat pekerjaannya hanya satu panggilan model dengan schema, misalnya mengekstrak purchase order atau mengklasifikasi tiket. Runtime agent menambahkan session, batas turn, dan state yang harus dibersihkan tanpa memberi nilai tambah di sana. Untuk agent multi-langkah dengan tool kustom, Agents SDK menghemat Anda dari menulis loop sendiri.

Apakah ChatKit alternatif dari Agents SDK?

Bukan. ChatKit adalah antarmuka chat yang bisa di-embed, bukan runtime agent. OpenAI merekomendasikan menghubungkannya ke layanan agentic Anda sendiri melalui ChatKit Python SDK, yang cocok dipasangkan dengan backend Agents SDK. Jalur ChatKit yang di-host Agent Builder kini legacy karena Agent Builder berhenti pada 30 November 2026.