Structured Output: JSON Mode dan Function Calling

Masalah: AI Suka Menjawab dengan Basa-Basi

Kamu butuh data terstruktur dari AI, misalnya daftar tugas dalam format JSON agar bisa diproses kode. Tapi AI menjawab: "Tentu! Berikut daftar tugasnya: ..." diikuti JSON yang dibungkus penjelasan, kadang dengan koma yang salah sehingga JSON-nya tidak valid. Untuk dipakai program, ini tidak bisa diterima: kode butuh format PASTI, bukan "kira-kira JSON".

Structured output adalah teknik (dan fitur model) untuk memaksa AI mengeluarkan format terstruktur yang valid: JSON sesuai skema, tanpa basa-basi. Ini fondasi dari function calling (cara agent "bertindak") dan semua integrasi AI-ke-kode.

Contoh 1: Meminta JSON yang Valid (Praktik)

Cara manual (prompt):

Ekstrak informasi dari teks berikut ke dalam JSON VALID saja, tanpa teks lain sebelum/sesudah. Skema: {"nama": string, "umur": number, "hobi": [string]} Teks: "Perkenalkan, aku Budi, umur 17 tahun. Hobiku ngoding dan main futsal."

Hasil yang diharapkan: {"nama": "Budi", "umur": 17, "hobi": ["ngoding", "main futsal"]}

Tips agar berhasil: (1) tulis kata "VALID" dengan tegas, (2) beri skema eksplisit dengan tipe data, (3) larang teks lain ("tanpa teks lain sebelum/sesudah"), (4) beri contoh 1 output ideal (kombinasi dengan few-shot!). Untuk model modern, tingkat keberhasilan sudah tinggi, tapi selalu validasi dengan JSON.parse() di kodemu, jangan percaya buta.

Cara fitur (JSON mode): banyak API (OpenAI, Gemini, OpenRouter untuk model yang mendukung) punya parameter response_format: {"type": "json_object"} yang memaksa output JSON valid di level model, bukan sekadar prompt. Kalau kamu membangun aplikasi, pakai fitur ini, bukan cuma prompt.

Contoh 2: Function Calling, Cara Agent Bertindak (Konsep + Praktik)

Bayangkan kamu membuat asisten yang bisa mengecek cuaca. Kamu tidak mau AI "menjawab" cuaca (ia tidak tahu cuaca hari ini), kamu mau ia memanggil fungsi getCuaca(kota) yang kamu sediakan, lalu menjawab berdasarkan hasilnya.

Alurnya:

1. Kamu daftarkan tools ke model: "ada fungsi getCuaca dengan parameter kota (string)."
2. User bertanya: "cuaca di Jakarta gimana?"
3. Model TIDAK menjawab langsung, melainkan mengembalikan function call terstruktur: {"name": "getCuaca", "arguments": {"kota": "Jakarta"}}
4. KODEMU mengeksekusi fungsi itu (panggil API cuaca beneran), dapat hasil "32C cerah".
5. Kamu kirim hasilnya kembali ke model, baru ia menjawab: "Jakarta 32C, cerah."

Inilah cara kerja SEMUA AI agent (OpenCode, Claude Code): "tools" mereka (baca file, jalankan perintah) adalah function calling. Model memutuskan kapan memanggil tool apa dengan argumen apa; kode di sekelilingnya yang mengeksekusi.

Coba pahami dengan eksperimen berpikir: prompt "berapa 237 * 489?" ke AI biasa = ia menebak (kadang salah!). Ke agent dengan tool kalkulator = ia memanggil hitung("237*489") dan menjawab tepat. Itulah kekuatan function calling: menggabungkan penalaran AI dengan ketepatan kode.

Catatan teknis: Function calling butuh model yang dilatih khusus untuk itu (tidak semua model bisa; Hermes terkenal bagus di ini, modul hermes-model-terbuka). Format standarnya: model mengembalikan "tool call" berisi nama fungsi + argumen JSON yang valid terhadap skema yang kamu daftarkan. Tantangan praktis: (1) argumen tidak valid (model mengarang parameter yang tidak ada) -> validasi skema di kodemu dan minta ulang; (2) model tidak memanggil tool padahal harusnya -> perjelas deskripsi tool ("pakai tool ini untuk SEMUA perhitungan matematika"); (3) rantai tool call (butuh 3 panggilan berurutan) -> implementasikan loop seperti agent. Untuk skema kompleks, pakai JSON Schema standar untuk mendefinisikan parameter.

Kesalahan Umum

1. Tidak memvalidasi output. "AI-nya sudah mode JSON, pasti valid." Selalu try/catch JSON.parse dan tangani gagalnya. Model bisa tetap salah dalam edge case.
2. Skema terlalu kompleks. 5 level nested dengan 20 field opsional = model bingung. Sederhanakan skema; pecah jadi beberapa panggilan kalau perlu.
3. Mendaftar tool tanpa deskripsi jelas. Deskripsi tool adalah "instruksi" bagi model kapan memakainya. "getData()" vs "getData(): mengambil data user dari database berdasarkan ID, pakai untuk SEMUA pertanyaan tentang user" = beda jauh hasilnya.
4. Memberi AI tool berbahaya tanpa batasan. Tool hapusFile() yang bisa dipanggil AI = risiko. Daftarkan hanya tool yang aman, atau minta konfirmasi manusia untuk aksi destruktif (prinsip dari modul keamanan-ai-coding).

Rangkuman

Structured output = memaksa AI ke format valid (JSON) lewat prompt tegas + fitur JSON mode + validasi di kodemu. Function calling = model mengembalikan panggilan fungsi terstruktur, kodemu mengeksekusi: inilah "tangan" semua AI agent. Pahami keduanya dan kamu memahami cara kerja agent dari dalam, bukan cuma sebagai pengguna.