Cara Menggunakan OpenAI Agents API?

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

Di bawah ini: sesi REST pertama, peristiwa progres, alat MCP, subagen, dan alur persetujuan penggunaan komputer. Untuk perbandingannya dengan antarmuka agen OpenAI lainnya, baca Agents API vs Responses API vs Agents SDK; untuk sisa acara, lihat rangkuman DevDay 2026. Setiap panggilan adalah HTTP biasa, jadi Anda bisa mengirimnya dari Apidog sebelum menulis kode aplikasi.

Sekilas OpenAI Agents API

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

Empat Konsep

Dokumen membangun API di sekitar empat bagian:

• Agen: model, instruksi, alat, dan server MCP. Teruskan secara inline, atau simpan dan gunakan kembali agent_id-nya.
• Lingkungan: sandbox atau komputer opsional tempat agen membaca file dan menjalankan perintah.
• Sesi: instans agen yang tahan lama yang menyimpan konfigurasi, percakapan, dan pekerjaan yang disimpan.
• Peristiwa dan item: peristiwa melaporkan progres secara langsung; item adalah pesan yang disimpan dan panggilan alat.

Pesan yang dikirim ke sesi yang tidak aktif memulai giliran baru; pesan yang dikirim di tengah giliran mengarahkannya. Harness (sesuai halaman arsitektur, instans Codex yang di-host yang menjalankan loop model dan alat) juga menangani pemadatan konteks, sehingga Anda tidak mengkonfigurasinya.

Pilih Lingkungan

environment.type memutuskan tempat perintah berjalan:

• none: tanpa komputasi. Server MCP jarak jauh dan alat fungsi Anda masih berfungsi; Bash bawaan, apply-patch, file ruang kerja, dan MCP eksekutor tidak.
• openai_hosted: OpenAI mengelola sandbox Linux dengan Python dan Node.js di /workspace. Tetapkan container_size ke small (1 GB), medium (default, 4 GB), atau large (16 GB), dan network.access ke enabled, disabled, atau restricted dengan allowed_domains. File di /workspace/outputs menjadi artefak ketika giliran selesai. Sandbox yang tidak aktif tanpa keep-alives dapat dihapus setelah satu jam.
• self_hosted: infrastruktur Anda. Anda menjalankan codex exec-server di laptop, kontainer, atau sandbox jarak jauh, dan itu terhubung keluar dengan kunci lingkungan terpisah.

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

Sesi Pertama Anda melalui REST

Ekspor kunci dengan izin di atas sebagai OPENAI_API_KEY, lalu kirim tugas quickstart dengan kontainer kecil:

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, responsnya adalah aliran peristiwa giliran pertama. Simpan ID sesi darinya; sisa siklus hidup menggunakan sumber daya yang sama:

JavaScript SDK memiliki bentuk yang sama. Versi ini, yang diadaptasi dari postingan peluncuran, menambahkan alat, 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);

Ikuti progres: stream atau webhook

Streaming. Buka GET /v1/agents/sessions/{id}/events?stream=true dengan Accept: text/event-stream sebelum Anda mengirim input, agar Anda tidak melewatkan peristiwa awal. Perhatikan untuk:

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

Tiga jebakan: agent.session.idle tidak berarti giliran berhasil, giliran yang selesai dapat berisi panggilan alat yang gagal, dan menutup aliran tidak menghentikan tugas. Stream tidak memutar ulang peristiwa yang terlewat, jadi setelah terputus, buka stream baru dan ambil sesi serta itemnya.

Webhook. Berlangganan agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle, dan agent.session.failed. Perhatikan penamaannya: stream mengatakan requires_action, webhook mengatakan action_required. Payload menghilangkan detail panggilan, jadi handler Anda mengambil sesi dan membaca required_actions. Verifikasi setiap tanda tangan (verifikasi tanda tangan webhook); operasi API yang berjalan lama oleh agen AI menjelaskan mengapa webhook cocok untuk tugas multi-menit.

Alat MCP, pencarian alat, panggilan alat terprogram, dan subagen

MCP. Tambahkan server 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 (connection_origin: "service"), jadi server harus dapat dijangkau dari OpenAI. Gunakan connection_origin: "environment" untuk server jaringan pribadi, atau stdio untuk memulai satu di sandbox. Untuk kredensial, teruskan transport.authorization untuk satu sesi, atau lampirkan kredensial brankas (static_bearer atau mcp_oauth) dengan vault_ids.

Pencarian alat. Alat MCP ditemukan secara otomatis ketika model mendukung pencarian alat. Untuk banyak alat fungsi, tambahkan {"type": "tool_search"} dan tandai fungsi defer_loading: true.

Panggilan alat terprogram. Aktif secara default: agen mendapatkan alat exec yang menjalankan JavaScript dalam runtime V8 terisolasi, sehingga dapat mengulang panggilan alat dan memotong hasil besar sebelum mencapai konteks. Nonaktifkan dengan {"type": "programmatic_tool_calling", "enabled": false}.

Subagen. Atur multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (batas default adalah 6). Subagen berbagi sistem file lingkungan dan mewarisi alat MCP serta pencarian web, tetapi tidak dapat menggunakan alat fungsi. subagent_id sebuah giliran adalah null untuk agen utama.

Penggunaan komputer: tambahan DevDay

Penggunaan komputer memberi agen browser yang di-host. Tambahkan alat dan desktop ke 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 memerlukan persetujuan pengguna sebelum mengunjungi setiap asal situs web baru, termasuk situs publik. Pada agent.session.requires_action, ambil sesi dan temukan entri computer_use_approval_request. request.type yang bersarang adalah salah satu dari dua jenis:

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

Kedua jawaban dikirim kembali melalui endpoint peristiwa:

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 id, turn_id, title, status, dan output, yang membawa tangkapan layar JPEG base64 ketika include_screenshots aktif dan tersedia. Jauhkan tangkapan layar dari log; mereka dapat menampilkan data akun.

Panduan penggunaan komputer menandai peringatan ini:

• Persetujuan origin bukan konfirmasi tindakan. Menyetujui situs tidak membuat agen bertanya sebelum setiap pembelian atau penghapusan. Jika Anda membutuhkannya, batasi browser ke sumber daya yang tidak dapat melakukan tindakan tersebut, atau gunakan runtime browser yang Anda kontrol.
• Masuk mencakup email, kata sandi, dan kode verifikasi. Passkey dan masuk kode QR tidak didukung.
• Hanya agen utama yang dapat meminta otentikasi. Subagen tidak bisa.
• Nonaktifkan percobaan ulang otomatis pada pengiriman kredensial (maxRetries: 0 di SDK, --retry 0 di curl).
• 202 berarti diterima, bukan berarti navigasi atau masuk berhasil. Permintaan otentikasi kedaluwarsa setelah lima menit.
• Persetujuan origin tidak mengesampingkan kebijakan jaringan. Izinkan situs dan domain pengalihannya di network juga.

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 agen API Anda, bukan UI Anda

Browser adalah solusi cadangan untuk perangkat lunak tanpa API. Jika sistem itu milik Anda, bungkus dalam server MCP: alat bertipe, tanpa perintah origin, hasil yang dapat diperiksa. Penggunaan komputer vs API terstruktur membahas trade-off, dan Apidog MCP Server memasok spesifikasi API Anda ke asisten coding yang menulis wrapper.

Uji Agents API di Apidog sebelum menulis kode

API sedang dalam beta, jadi konfirmasikan bentuk setiap panggilan secara manual di Apidog terlebih dahulu:

1. Buat lingkungan Apidog dengan OPENAI_API_KEY, VAULT_ID, dan SESSION_ID. Kirim Bearer {{OPENAI_API_KEY}} dan OpenAI-Beta: agents=v1 pada setiap permintaan.
2. Kirim permintaan buat-sesi tanpa stream, assert status 2xx dan id yang tidak kosong, dan ekstrak id ke SESSION_ID.
3. Buka aliran peristiwa sebagai permintaan SSE, kirim input dari permintaan kedua, dan saksikan peristiwa tiba.
4. Simpan payload persetujuan dan pembatalan sebagai permintaan untuk memutar ulang setiap kasus required_actions.
5. Rangkai semuanya menjadi skenario pengujian dan jalankan di CI dengan Apidog CLI.

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

FAQ

Apakah OpenAI Agents API gratis? Tidak ada biaya platform, tetapi Anda membayar untuk token model, panggilan alat, dan waktu kontainer yang di-host.

Model mana yang berfungsi dengan Agents API? Contoh dokumen, termasuk setiap contoh penggunaan komputer, menggunakan gpt-6-astra. Halaman-halaman tersebut tidak mencantumkan model lain yang didukung, jadi uji model Anda terlebih dahulu.

Apakah Agents API mendukung Zero Data Retention? Tidak. Ini hanya mendukung residensi data AS dan tidak memenuhi syarat ZDR, bahkan dengan sandbox yang di-host sendiri.

Bagaimana perbedaannya dengan Agents SDK atau Responses API? SDK menjalankan loop di dalam aplikasi Anda; Responses API adalah panggilan model yang Anda bangun loop di sekitarnya. Lihat perbandingan lengkapnya.

Mulai dengan Satu Sesi Hanya Baca

Mulai dengan sesi yang hanya membaca, tambahkan satu server MCP, lalu tambahkan penggunaan komputer di balik handler persetujuan yang menolak secara default. Ketika ChatGPT harus bereaksi terhadap peristiwa dari server Anda sendiri, MCP Events adalah bagian yang sesuai.