Cara Menggunakan OpenAI Agents API?

OpenAI Agents API menjalankan harness Codex sumber terbuka OpenAI untuk Anda. Kirim POST https://api.openai.com/v1/agents/sessions dengan header OpenAI-Beta: agents=v1, definisi agen, dan tugas; OpenAI menjalankan model serta loop alat, mempertahankan sesi, dan dapat menyediakan sandbox. Tidak ada biaya khusus Agents API: Anda tetap membayar token, alat, dan waktu kontainer yang di-host, sekitar $0.03 hingga $0.48 per sesi 20 menit untuk sandbox 1 GB hingga 16 GB. API ini memasuki beta publik pada 10 September 2026, lalu OpenAI menambahkan penggunaan komputer di DevDay pada 29 September.

Coba Apidog hari ini

Artikel ini membahas sesi REST pertama, pelacakan progres, alat MCP, subagen, dan alur persetujuan penggunaan komputer. Untuk membandingkannya dengan antarmuka agen OpenAI lainnya, baca Agents API vs Responses API vs Agents SDK. Untuk rangkuman acara, lihat rangkuman DevDay 2026. Karena seluruh alur menggunakan HTTP biasa, Anda dapat mengirim dan memvalidasi request dari Apidog sebelum menulis integrasi aplikasi.

Sekilas OpenAI Agents API

Item	Nilai
Status	Beta publik sejak 10 Sep 2026; penggunaan komputer ditambahkan 29 Sep
Buat sesi	POST /v1/agents/sessions
Header beta	OpenAI-Beta: agents=v1 — SDK OpenAI menambahkannya
Izin kunci	api.agents.read, api.agents.write, api.responses.write
Harga	Tidak ada biaya Agents API; token model mengikuti tarif API dan alat mengikuti tarif standar, misalnya pencarian web $10 per 1K panggilan
Kontainer yang di-host	$0.03 (small, 1 GB), $0.12 (medium, 4 GB), $0.48 (large, 16 GB) per sesi 20 menit
Lingkungan	none, openai_hosted, self_hosted
Model pada contoh dokumen	gpt-6-astra
Kontrol data	Hanya residensi data AS; tanpa Zero Data Retention (ZDR)
Ukuran request maksimum	4 MiB

Sumber: Memperkenalkan Agents API, ikhtisar Agents API, dan halaman harga.

Pahami empat objek utama

Sebelum membuat request, pahami relasi empat komponen berikut:

• Agen: model, instruksi, alat, dan server MCP. Konfigurasi dapat dikirim inline atau disimpan untuk digunakan kembali melalui agent_id.
• Lingkungan: sandbox atau komputer opsional untuk membaca file dan menjalankan perintah.
• Sesi: instans agen persisten yang menyimpan konfigurasi, percakapan, dan pekerjaan tersimpan.
• Peristiwa dan item: peristiwa melaporkan progres secara langsung; item adalah pesan dan panggilan alat yang disimpan.

Kirim pesan ke sesi yang sedang tidak aktif untuk memulai giliran baru. Kirim pesan saat giliran masih berjalan untuk mengarahkannya. Berdasarkan arsitektur Agents API, harness adalah instans Codex yang di-host untuk menjalankan loop model dan alat. Harness juga menangani pemadatan konteks, sehingga Anda tidak perlu mengonfigurasikannya sendiri.

Pilih lingkungan eksekusi

Tentukan lokasi eksekusi melalui environment.type.

1. Tanpa komputasi: none

Gunakan none jika agen hanya membutuhkan server MCP jarak jauh atau alat fungsi aplikasi Anda.

Dalam mode ini:

• Server MCP jarak jauh dan alat fungsi tetap berfungsi.
• Bash bawaan, apply-patch, file workspace, dan MCP eksekutor tidak tersedia.

2. Sandbox OpenAI: openai_hosted

Gunakan openai_hosted untuk menjalankan perintah dalam sandbox Linux yang dikelola OpenAI. Sandbox menyediakan Python dan Node.js di /workspace.

Konfigurasi utama:

• container_size: small (1 GB), medium (default, 4 GB), atau large (16 GB).
• network.access: enabled, disabled, atau restricted.
• network.allowed_domains: daftar domain jika akses jaringan dibatasi.

File yang ditulis ke /workspace/outputs menjadi artefak ketika giliran selesai. Sandbox yang tidak aktif tanpa keep-alive dapat dihapus setelah satu jam.

3. Infrastruktur sendiri: self_hosted

Gunakan self_hosted jika Anda membutuhkan kontrol penuh atas lingkungan eksekusi. Jalankan codex exec-server di laptop, kontainer, atau sandbox jarak jauh Anda. Server tersebut kemudian membuat koneksi keluar menggunakan kunci lingkungan yang terpisah.

Postingan peluncuran mencantumkan Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, dan Vercel sebagai mitra sandbox. Panduan self-hosted juga menambahkan AWS Lambda MicroVMs.

Buat sesi pertama melalui REST

Pastikan OPENAI_API_KEY memiliki izin berikut:

api.agents.read
api.agents.write
api.responses.write

Kemudian buat sesi dengan kontainer kecil. Contoh berikut meminta agen membuat, menjalankan, dan melaporkan hasil skrip Python:

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": "Tulis kode yang bersih, jalankan, dan laporkan output sebenarnya."
    },
    "environment": {
      "type": "openai_hosted",
      "container_size": "small"
    },
    "input": "Buat tree.py, sebuah skrip yang mencetak pohon file di direktori saat ini. Jalankan dan tunjukkan outputnya.",
    "stream": true
  }'

Dengan stream: true, respons berupa aliran peristiwa untuk giliran pertama. Simpan ID sesi dari respons tersebut karena seluruh operasi berikutnya menggunakan resource yang sama.

Tindakan	Request
Kirim tindak lanjut atau arahan	POST /v1/agents/sessions/{id}/events dengan peristiwa agent.session.input.message
Batalkan giliran aktif	Endpoint yang sama dengan tipe agent.session.input.cancel
Baca pekerjaan tersimpan	GET /v1/agents/sessions/{id}/items?order=asc&limit=100
Hapus sesi	DELETE /v1/agents/sessions/{id}

Gunakan SDK JavaScript

SDK JavaScript menggunakan struktur yang sama. Contoh berikut menambahkan pencarian web, subagen, dan brankas:

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: "Ringkas perubahan penting dalam catatan rilis terbaru.",
});

console.log(session.id);

Simpan session.id untuk mengirim pesan berikutnya, membuka stream peristiwa, membaca item, atau membersihkan sesi.

Pantau progres dengan stream atau webhook

Streaming SSE

Buka stream berikut sebelum mengirim input agar tidak melewatkan peristiwa awal:

GET /v1/agents/sessions/{id}/events?stream=true
Accept: text/event-stream

Peristiwa yang perlu Anda tangani:

• agent.session.turn.output_text.delta dan agent.session.turn.output_text.done untuk output teks.
• agent.session.turn.completed, agent.session.turn.failed, atau agent.session.turn.cancelled untuk status akhir giliran.
• agent.session.requires_action ketika agen membutuhkan hasil fungsi, koneksi lingkungan, atau persetujuan penggunaan komputer.

Perhatikan tiga hal berikut saat membangun UI atau worker:

1. agent.session.idle tidak otomatis berarti giliran berhasil.
2. Giliran yang selesai masih dapat memiliki panggilan alat yang gagal.
3. Menutup koneksi stream tidak menghentikan tugas yang sedang berjalan.

Stream tidak memutar ulang peristiwa yang terlewat. Setelah koneksi terputus, buka stream baru lalu ambil kembali status sesi dan item tersimpan.

Webhook

Berlangganan ke peristiwa berikut jika tugas Anda dapat berlangsung beberapa menit:

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

Ada perbedaan penamaan yang penting:

• Stream menggunakan requires_action.
• Webhook menggunakan action_required.

Payload webhook tidak menyertakan detail panggilan secara lengkap. Handler Anda harus mengambil sesi dan membaca required_actions. Selalu verifikasi tanda tangan webhook; lihat verifikasi tanda tangan webhook. Untuk alasan penggunaan webhook pada pekerjaan berdurasi panjang, baca operasi API yang berjalan lama oleh agen AI.

Tambahkan MCP, pencarian alat, dan subagen

Hubungkan server MCP

Tambahkan server MCP ke agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "required": true
}

Secara default OpenAI membuat koneksi dengan connection_origin: "service", sehingga server MCP harus dapat dijangkau dari infrastruktur OpenAI.

Pilih opsi lain jika diperlukan:

• Gunakan connection_origin: "environment" untuk server di jaringan privat.
• Gunakan stdio untuk memulai server MCP di sandbox.
• Kirim transport.authorization untuk kredensial satu sesi.
• Lampirkan kredensial brankas static_bearer atau mcp_oauth melalui vault_ids.

Aktifkan pencarian alat

Alat MCP ditemukan secara otomatis ketika model mendukung pencarian alat. Jika Anda memiliki banyak alat fungsi, tambahkan:

{ "type": "tool_search" }

Kemudian tandai fungsi yang tidak perlu dimuat sejak awal dengan:

{
  "defer_loading": true
}

Panggilan alat terprogram

Panggilan alat terprogram aktif secara default. Agen memperoleh alat exec untuk menjalankan JavaScript dalam runtime V8 terisolasi. Ini memungkinkan agen mengulang panggilan alat dan meringkas hasil besar sebelum hasil tersebut masuk ke konteks model.

Nonaktifkan fitur ini jika tidak dibutuhkan:

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

Jalankan subagen

Aktifkan subagen dengan konfigurasi berikut:

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

Batas default adalah enam subagen. Subagen berbagi sistem file lingkungan dan mewarisi alat MCP serta pencarian web. Namun, subagen tidak dapat menggunakan alat fungsi. Pada item giliran, subagent_id bernilai null untuk agen utama.

Tambahkan penggunaan komputer dengan aman

Penggunaan komputer memberikan browser yang di-host kepada agen. Aktifkan alat dan desktop pada lingkungan yang di-host:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [
      {
        "type": "computer_use",
        "include_screenshots": true
      }
    ]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": {
      "enabled": true
    },
    "network": {
      "access": "enabled"
    }
  }
}

Browser membutuhkan persetujuan pengguna sebelum mengunjungi setiap origin situs web baru, termasuk situs publik.

Saat menerima agent.session.requires_action:

1. Ambil data sesi.
2. Temukan entri computer_use_approval_request.
3. Periksa request.type.
4. Kirim hasil persetujuan kembali melalui endpoint peristiwa.

Terdapat dua jenis request bersarang:

• browser_origin_access: tampilkan origin dan reason, lalu kirim approve, deny, atau cancel.
• browser_authentication: tampilkan formulir login dari fields, opsi login dari options jika tersedia, serta credential_origin. Kirim action: "submit" dengan nilai pengguna atau action: "cancel".

Contoh pengiriman persetujuan origin:

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"
      }
    }]
  }'

Pekerjaan browser muncul sebagai item computer_use_call dengan properti seperti id, turn_id, title, status, dan output. Jika include_screenshots aktif dan tangkapan layar tersedia, output dapat memuat JPEG base64.

Jangan masukkan tangkapan layar ke log aplikasi karena dapat berisi data akun pengguna.

Panduan penggunaan komputer menekankan batasan berikut:

• Persetujuan origin bukan konfirmasi tindakan. Menyetujui sebuah situs tidak memaksa agen meminta konfirmasi sebelum pembelian atau penghapusan.
• Login dapat mencakup email, kata sandi, dan kode verifikasi. Passkey dan login kode QR tidak didukung.
• Hanya agen utama yang dapat meminta autentikasi. Subagen tidak dapat melakukannya.
• Nonaktifkan retry otomatis saat mengirim kredensial. Gunakan maxRetries: 0 di SDK atau --retry 0 pada curl.
• Status 202 berarti request diterima. Status tersebut tidak menjamin navigasi atau login berhasil.
• Request autentikasi kedaluwarsa setelah lima menit.
• Persetujuan origin tidak menggantikan kebijakan jaringan. Domain target dan domain pengalihannya tetap harus diizinkan dalam network.

Rekapitulasi menyatakan penggunaan komputer dikirim “melalui API dan di Codex serta ChatGPT Work pada Pro 500 dan Enterprise.” Untuk pengujian berbasis UI dengan model yang sama, lihat penggunaan komputer GPT-6 Astra untuk pengujian API.

Berikan API kepada agen, bukan UI

Browser adalah opsi cadangan untuk perangkat lunak yang tidak memiliki API. Jika sistem tersebut milik Anda, prioritaskan server MCP dengan alat yang bertipe, tanpa perintah berbasis origin, dan hasil yang dapat diperiksa secara programatis.

Baca Penggunaan komputer vs API terstruktur untuk memahami trade-off. Anda juga dapat menggunakan Apidog MCP Server untuk memasok spesifikasi API ke asisten coding yang menulis wrapper.

Uji Agents API di Apidog sebelum menulis kode

Karena API masih beta, validasi bentuk setiap request secara manual di Apidog terlebih dahulu.

Ikuti alur pengujian ini:

1. Buat environment Apidog dengan OPENAI_API_KEY, VAULT_ID, dan SESSION_ID.
2. Tambahkan header berikut pada setiap request:

   Authorization: Bearer {{OPENAI_API_KEY}}
   OpenAI-Beta: agents=v1

1. Kirim request buat-sesi tanpa stream. Assert status 2xx, pastikan id tidak kosong, lalu ekstrak id ke SESSION_ID.
2. Buka aliran peristiwa sebagai request SSE.
3. Kirim input dari request kedua dan amati peristiwa yang masuk.
4. Simpan payload persetujuan dan pembatalan sebagai request terpisah agar setiap kasus required_actions dapat diputar ulang.
5. Gabungkan request menjadi skenario pengujian, lalu jalankan di CI dengan Apidog CLI.

Panduan pengujian API agen AI menyediakan pola assertion untuk output non-deterministik. Unduh Apidog untuk mengikuti langkah-langkahnya.

FAQ

Apakah OpenAI Agents API gratis?

Tidak ada biaya platform khusus, tetapi Anda membayar token model, panggilan alat, dan waktu kontainer yang di-host.

Model mana yang berfungsi dengan Agents API?

Contoh dokumen, termasuk seluruh contoh penggunaan komputer, memakai gpt-6-astra. Halaman tersebut tidak mencantumkan model lain yang didukung, jadi uji model Anda terlebih dahulu.

Apakah Agents API mendukung Zero Data Retention?

Tidak. API ini hanya mendukung residensi data AS dan tidak memenuhi syarat ZDR, termasuk saat menggunakan sandbox yang di-host sendiri.

Apa perbedaannya dengan Agents SDK atau Responses API?

SDK menjalankan loop di dalam aplikasi Anda. Responses API adalah panggilan model yang loop-nya Anda bangun sendiri. Lihat perbandingan lengkapnya.

Mulai dari satu sesi hanya-baca

Mulailah dengan sesi hanya-baca dan satu server MCP. Setelah alur sesi, event, dan error handling stabil, tambahkan penggunaan komputer di belakang handler persetujuan yang menolak secara default.

Jika ChatGPT perlu bereaksi terhadap peristiwa dari server Anda sendiri, gunakan MCP Events.