Responses API vs Chat Completions untuk Agen: Memilih Kontrak

Untuk beban kerja agen, Responses API adalah pilihan default yang lebih baik: API ini memberikan status percakapan sisi server melalui previous_response_id, item output yang memiliki tipe (typed) alih-alih sekadar blob pesan tunggal, dan event streaming semantik. Fitur-fitur ini mengurangi beban pembukuan yang seharusnya dikelola oleh lapisan orkestrasi Anda. Chat Completions tetap menjadi pilihan yang valid jika Anda menginginkan kontrol penuh atas riwayat pesan atau sedang berintegrasi dengan alat yang dibangun di sekitar format pesan chat OpenAI, namun untuk agen pemanggil alat (tool-calling) multi-giliran, Responses adalah pilihan yang lebih langsung.

Kedua endpoint tersebut didokumentasikan pada halaman referensi model saat ini untuk GPT-5.6 dan GPT-5.5, dan kontrak permintaan/tanggapan bersama untuk Responses ditentukan dalam referensi pembuatan Responses.

Poin Penting

• Chat Completions dikelola oleh pemanggil: Anda mengirim array messages lengkap pada setiap permintaan dan menyusun ulang riwayat sendiri.
• Responses dibantu oleh server: Anda mengirim input ditambah instructions opsional, dan dapat merangkai giliran dengan previous_response_id alih-alih mengirim ulang riwayat.
• Pemanggilan alat berbeda secara struktural: Chat Completions menyarangkan panggilan di bawah choices[0].message.tool_calls; Responses memancarkannya sebagai item bertipe dalam array output yang datar.
• Hasil alat dicocokkan berdasarkan tool_call_id (Chat) dibandingkan dengan call_id pada item function_call_output (Responses).
• Streaming berbasis delta per potongan (chunk) di Chat Completions dibandingkan dengan event semantik bernama di Responses.
• Dukungan alat yang dihosting (penelusuran web, interpreter kode, pencarian file, dll.) bergantung pada model di kedua API; periksa halaman model sebelum berasumsi mengenai ketersediaannya.

Perbandingan Tingkat Bidang

Perhatian	Chat Completions	Responses
Endpoint	POST /v1/chat/completions	POST /v1/responses
Input utama	messages: [] (array lengkap setiap panggilan)	input (string atau array item)
Panduan gaya sistem	messages[0].role = "system"	Bidang instructions tingkat atas
Kelanjutan multi-giliran	Pemanggil mengirim ulang seluruh riwayat messages	previous_response_id mereferensikan giliran sebelumnya di sisi server
Bentuk output	choices[0].message (objek pesan tunggal)	output: [], array item bertipe (pesan, function_call, dll.)
Lokasi panggilan alat	choices[0].message.tool_calls[]	Item dalam output dengan type: "function_call"
Pengiriman hasil alat	Pesan baru dengan role: "tool", tool_call_id	Item dengan type: "function_call_output", call_id
Streaming	Fragmen chunk.choices[0].delta	Event bernama (response.output_text.delta, response.completed, dll.)

previous_response_id: Apa Fungsinya Sebenarnya

Dalam Chat Completions, memori percakapan sepenuhnya menjadi tanggung jawab Anda. Setiap permintaan harus menyertakan riwayat pesan lengkap, dan server tidak memiliki gagasan tentang giliran sebelumnya. Sebaliknya, Responses API mengembalikan id pada setiap objek respons. Jika aplikasi Anda menyimpan id tersebut dan meneruskannya kembali sebagai previous_response_id pada panggilan berikutnya, server akan menyusun ulang status percakapan sebelumnya di sisinya. Anda hanya perlu mengirim input baru untuk giliran saat ini ditambah (opsional) instructions baru. Ini mengalihkan manajemen status dari lapisan aplikasi Anda ke infrastruktur OpenAI, yang penting bagi agen yang melakukan banyak pemanggilan alat secara berurutan karena Anda menghindari serialisasi ulang dan pengiriman ulang riwayat yang terus bertambah di setiap lompatan.

Kelemahannya adalah aplikasi Anda masih perlu menyimpan id di tempat yang tahan lama (penyimpanan sesi, baris basis data) di antara giliran; API tidak memberi Anda retensi tak terbatas atau pencarian atas respons masa lalu, API hanya memungkinkan Anda mereferensikan respons yang tepat sebelumnya sebagai titik kelanjutan.

Contoh Permintaan Saat Ini (gpt-5.6)

Chat Completions: Anda memiliki riwayat lengkap:

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses: giliran pertama dengan instructions dan input:

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses: giliran tindak lanjut, tidak ada riwayat yang dikirim ulang:

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

Siklus Hidup Function-Call

Chat Completions:

1. Model mengembalikan choices[0].message.tool_calls, masing-masing dengan id dan nama/argumen fungsi.
2. Anda menjalankan fungsi secara lokal.
3. Anda menambahkan pesan asisten (dengan tool_calls) ke array messages Anda, lalu menambahkan pesan baru: { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. Anda mengirim ulang seluruh array messages yang diperbarui untuk melanjutkan.

Responses:

1. Array output berisi item dengan type: "function_call", termasuk call_id, name, dan arguments.
2. Anda menjalankan fungsi secara lokal.
3. Anda mengirim permintaan baru dengan previous_response_id diatur ke id respons sebelumnya, dan input berisi item dengan type: "function_call_output", yang mencocokkan call_id, dan hasilnya.
4. Server telah menyimpan konteks pemanggilan fungsi, jadi Anda tidak perlu mengirim ulang giliran sebelumnya.

Perbedaan struktural antara item output bertipe datar dan pesan tunggal dengan array bersarang cenderung menyederhanakan logika penguraian di Responses, karena Anda dapat melakukan iterasi pada output dan beralih berdasarkan type alih-alih menggali bidang opsional pesan.

Daftar Periksa Keputusan

• Membangun agen multi-giliran dengan pemanggilan alat? Gunakan Responses sebagai default; previous_response_id menghilangkan pembukuan riwayat.
• Perlu kontrol tepat atas apa yang ada dalam riwayat (redaksi, peringkasan kustom, penyisipan pesan non-standar)? Chat Completions memberi Anda kontrol tersebut secara eksplisit, karena Anda menyusun messages sendiri.
• Memigrasikan integrasi Chat Completions yang ada? Timbang biaya refaktor terhadap penghematan manajemen status; untuk panggilan jangka pendek satu giliran, manfaatnya lebih kecil.
• Bergantung pada alat yang dihosting (penelusuran, interpreter kode, alat file)? Verifikasi dukungan di halaman model spesifik sebelum berkomitmen, karena ketersediaan bervariasi menurut model dan endpoint.
• Perlu streaming dengan semantik event yang terperinci (misalnya, membedakan delta teks dari delta pemanggilan alat tanpa memeriksa bentuk delta)? Event bernama Responses lebih eksplisit daripada potongan delta generik Chat Completions.
• Bekerja dalam kerangka kerja atau SDK yang ada yang dibangun di sekitar pesan chat? Konfirmasikan kematangan dukungan Responses-nya sebelum beralih kontrak di tengah proyek.

Agen multi-penyedia dan terjemahan kontrak

Agen jarang bertahan pada satu penyedia dalam waktu lama. Agen pengodean mungkin merutekan ke Claude Sonnet 5 atau Kimi K2.7 Code untuk pekerjaan implementasi, beralih ke DeepSeek V4 Flash atau Gemini 3.5 Flash untuk draf murah, dan sesekali memanggil GLM-5.2 atau Qwen3.7 Plus untuk kontrol biaya model terbuka (open-weight). Tidak satu pun dari penyedia ini yang harus mengekspos kontrak Chat Completions atau Responses OpenAI secara asli.

Di sinilah lapisan perutean berperan. Dokumentasi TokenLab di docs.tokenlab.sh menjelaskan satu permukaan API dan kunci yang digunakan untuk menjangkau beberapa penyedia model, yang menghilangkan kebutuhan untuk menulis integrasi klien terpisah per kontrak penyedia. Artikel terkait kami tentang alias header untuk kompatibilitas kontrak membahas bagaimana header permintaan dapat dipetakan sehingga kode yang ditulis terhadap satu bentuk kontrak dapat menjangkau model yang tidak mendukungnya secara asli. Jika Anda membangun chatbot atau agen yang perlu memanggil lebih dari satu keluarga model, panduan kami tentang membangun chatbot AI dengan satu kunci API membahas penyiapannya dalam istilah yang lebih konkret.

Untuk daftar lengkap model saat ini yang dapat dijangkau melalui TokenLab, termasuk opsi perutean frontier, pengodean, dan berbiaya rendah yang dirujuk di atas, lihat halaman model kami. Konfirmasikan ketersediaan saat ini dan catatan khusus kontrak di sana sebelum menyelesaikan arsitektur Anda, karena jajaran model berubah lebih sering daripada kontrak API.

Keterbatasan

Artikel ini tidak menyatakan kembali referensi API tingkat bidang yang tepat dari OpenAI untuk kedua kontrak, karena detail tersebut memiliki versi dan dapat berubah. Jangan perlakukan contoh bentuk permintaan di atas sebagai kode siap produksi. Kami juga belum membahas kontrak asli setiap penyedia secara mendalam di sini; Claude, Gemini, DeepSeek, dan GLM masing-masing menerbitkan referensi API mereka sendiri, dan tidak satu pun dari mereka berkewajiban untuk mencocokkan bentuk Chat Completions atau Responses OpenAI. Jika agen Anda memerlukan jaminan tentang urutan pemanggilan alat, format event streaming, atau perilaku pemrosesan batch, verifikasi spesifikasi tersebut terhadap dokumentasi penyedia yang disebutkan, bukan terhadap artikel ini.

FAQ

Apakah Responses API merupakan pengganti Chat Completions? Dokumentasi quickstart OpenAI memposisikan Responses API sebagai jalur saat ini untuk pengembangan baru, termasuk kasus penggunaan agen, sementara Chat Completions tetap menjadi bagian dari permukaan API mereka yang didokumentasikan. Apakah Chat Completions sudah tidak digunakan lagi (deprecated), dihentikan (sunset), atau sekadar warisan (legacy) pada waktu tertentu adalah sesuatu yang harus Anda konfirmasikan langsung di dokumen OpenAI saat ini, karena status dukungan dapat berubah.

Apakah penyedia lain seperti Claude, Gemini, atau DeepSeek menggunakan kontrak yang sama? Tidak secara asli. Setiap penyedia menentukan bentuk permintaan dan tanggapannya sendiri. Jika Anda perlu menjalankan agen di seluruh model OpenAI dan penyedia seperti Claude Sonnet 5 atau DeepSeek V4 Pro, rencanakan lapisan terjemahan alih-alih berasumsi adanya kontrak bersama.

Apakah beralih kontrak mengubah kualitas output model? Tidak. Kontrak adalah transportasi dan struktur permintaan dan tanggapan, bukan model itu sendiri. Kualitas output diatur oleh model mana yang Anda panggil (misalnya GPT-5.5 dibandingkan dengan Claude Sonnet 5), bukan oleh apakah Anda menggunakan Chat Completions atau Responses API untuk memanggilnya.

Jika Anda sedang mengevaluasi kontrak dan model mana yang cocok untuk agen Anda, mulailah dengan build uji kecil terhadap endpoint yang didokumentasikan TokenLab dan bandingkan overhead orkestrasi secara langsung. Mulailah di docs.tokenlab.sh untuk menjalankan perbandingan tersebut terhadap beban kerja Anda sendiri.