# Mengatasi Error Parsing JSON dan Halusinasi Schema pada AI Agent

- URL: https://komunitech.com/blog/karir-skill/mengatasi-error-parsing-json-dan-halusinasi-schema-pada-ai-agent/
- Diterbitkan: 2026-11-11
- Diperbarui: 2026-11-12
- Penulis: Priyo Harjiyono
- Penerbit: KomuniTech (https://komunitech.com)

---

Membangun AI Agent yang andal untuk lingkungan produksi sering kali berbenturan dengan kenyataan pahit: Large Language Models (LLM) pada dasarnya adalah mesin pemprediksi token berturut-turut, bukan parser sintaksis yang deterministik. Saat kita meminta AI Agent memanggil alat (tool-calling) atau menghasilkan payload JSON untuk integrasi sistem, ketidakstabilan format sering menjadi batu sandungan utama.




## Apa itu Parsing Data?


Parsing data adalah proses mengubah data mentah yang tidak terstruktur menjadi format terstruktur yang mudah dipahami dan diproses oleh komputer.


Proses parsing umumnya melalui beberapa tahapan utama:


1. Tokenisasi (Analisis Leksikal): Memecah teks atau kode menjadi bagian-bagian kecil (disebut token), seperti kata kunci, operator, atau nama variabel.


2. Analisis Sintaks: Memeriksa apakah urutan token tersebut sudah mengikuti aturan tata bahasa atau format yang benar.


3. Penyusunan Struktur (Parse Tree / AST): Membentuk representasi data yang terstruktur (seperti pohon sintaksis) agar bisa diproses lebih lanjut oleh program.


Lalu mengapa LLM sering mengalami kegagalan sintaksis, apa saja dampaknya terhadap arsitektur automasi, serta strategi konkret untuk memaksa model menghasilkan structured output yang 100% patuh pada standar produksi.


Artikel Terkait: [Sertifikasi Prompt Engineering: Mana yang Dilihat Rekruter (2026)](https://komunitech.com/blog/karir-skill/sertifikasi-prompt-engineering/)




## Akar Masalah: Mengapa Model Gagal Membentuk JSON Valid?


Meskipun model AI generasi terbaru memiliki tingkat kecerdasan bernalar yang tinggi, format keluaran teksnya bersifat probabilistik. Karakteristik ini memicu beberapa kecenderungan bawaan yang merusak integritas payload JSON:





- Markdown Code Block Wrapper (```json)
Secara bawaan, banyak LLM dilatih untuk menyajikan jawaban yang mudah dibaca oleh manusia. Model cenderung membungkus objek JSON di dalam blok kode Markdown. Ketika parser eksternal menerima string tersebut secara mentah, fungsi JSON.parse() atau json.loads() akan melempar exception karena karakter backtick bukan merupakan bagian dari spesifikasi RFC 8259.

- Teks Pengantar dan Penutup (Conversational Filler)
Model sering kali menambahkan kalimat ramah seperti "Tentu, berikut adalah data JSON yang Anda minta:" di awal atau "Semoga membantu!" di akhir pesan. Adanya teks bebas ini merusak struktur dokumen JSON secara instan.

- Penggunaan Trailing Comma
Sesuai standar JSON formal, koma tidak boleh ditempatkan di akhir elemen terakhir dalam sebuah objek atau array (contoh: {"status": "active",}). Namun, dalam banyak bahasa pemrograman (seperti JavaScript atau Python list), trailing comma diizinkan. Model yang mempelajari miliaran baris kode sering kali menyisipkan koma ekstra ini tanpa disadari.

- Halusinasi Parameter dan Tipe Data pada Tool Definition
Saat melakukan function calling, model dapat mengarang field yang sama sekali tidak dicantumkan dalam JSON Schema yang diberikan. Selain itu, model kerap mengalami tipe data yang tidak konsisten, seperti memberikan string "123" untuk field yang secara eksplisit meminta tipe integer 123.



## Dampak Schema Hallucination pada Workflow Automasi


Ketidakpatuhan model terhadap format data bukan sekadar isu formatting, melainkan ancaman langsung terhadap keandalan sistem berskala besar.






| 
Jenis Dampak



| 
Mekanisme Kegagalan



| 
Konsekuensi Operasional








| 
API Failure (400 Bad Request)



| 
Payload yang dikirimkan AI Agent melanggar validasi schema pada REST API pihak ketiga.



| 
Request ditolak seketika oleh upstream server; transaksi bisnis gagal diproses.






| 
Pipeline Terputus (Broken DAG)



| 
Exception yang tidak ditangani (unhandled parsing error) menghentikan eksekusi workflow pada node Agent.



| 
Sistem terhenti di tengah jalan; membutuhkan intervensi manual dari tim engineering.






| 
Pemborosan Kredit API



| 
Agent terjebak dalam infinite loop saat mencoba mengulang permintaan yang gagal (retries).



| 
Konsumsi token melonjak drastis; biaya operasional LLM membengkak tanpa hasil.








Artikel Terkait: [Cara Menghasilkan Uang dari AI: Mana yang Beneran Ada Permintaannya (2026)](https://komunitech.com/blog/karir-skill/cara-menghasilkan-uang-dari-ai-2026/)




## Solusi Ampuh Memaksa Output Terstruktur


Untuk mengatasi masalah ini secara permanen, kita perlu menerapkan pendekatan berlapis (defense-in-depth) mulai dari tingkat inferensi model hingga validasi di sisi kode aplikasi.




### 1. Memanfaatkan Structured Outputs Bawaan (JSON Schema Mode)


Mayoritas penyedia LLM utama kini menyediakan fitur Constrained Decoding di tingkat API. Fitur ini memaksa pengolah dekoder LLM hanya memilih token yang valid berdasarkan grammar atau schema JSON yang didefinisikan.


# Contoh implementasi JSON Schema Mode menggunakan OpenAI SDK




import json


from openai import OpenAI


client = OpenAI()


response = client.chat.completions.create(


    model="gpt-4o-mini",


    messages=[


        {"role": "system", "content": "Anda adalah asisten ekstraksi data."},


        {"role": "user", "content": "Ekstrak data: Budi, 29 tahun, Software Engineer di Jakarta."}


    ],


    response_format={


        "type": "json_schema",


        "json_schema": {


            "name": "user_profile",


            "strict": True,


            "schema": {


                "type": "object",


                "properties": {


                    "nama": {"type": "string"},


                    "umur": {"type": "integer"},


                    "pekerjaan": {"type": "string"},


                    "lokasi": {"type": "string"}


                },


                "required": ["nama", "umur", "pekerjaan", "lokasi"],


                "additionalProperties": False


            }


        }


    }


)




data = json.loads(response.choices[0].message.content)







Dengan mengaktifkan opsi "strict": True, API jamin tidak akan menyisipkan markdown, teks pengantar, atau field yang tidak didaftarkan.




### 2. Pydantic Validation & Instructor Pattern


Di ekosistem Python, gabungan library Pydantic dan Instructor merupakan standar industri untuk mengelola structured outputs. Pydantic menangani pengetikan tipe data (data typing) yang ketat dan otomatis melakukan konversi tipe jika memungkinkan.




import instructor


from pydantic import BaseModel, Field


from openai import OpenAI




# Patch client OpenAI menggunakan Instructor


client = instructor.from_openai(OpenAI())




class UserProfile(BaseModel):


    nama: str = Field(description="Nama lengkap pengguna")


    umur: int = Field(description="Umur dalam satuan tahun")


    pekerjaan: str


    skills: list[str] = Field(default_factory=list, description="Daftar keahlian teknis")




# Query diproses dan di-parse langsung ke objek Pydantic


user: UserProfile = client.chat.completions.create(


    model="gpt-4o",


    response_model=UserProfile,


    messages=[


        {"role": "user", "content": "Siti adalah DevOps Engineer usia 31 tahun yang menguasai Docker dan Kubernetes."}


    ]


)




print(f"Nama: {user.nama}, Skills: {user.skills}")




### 



### 3. Self-Correction Loop / Reflection Pattern


Jika terjadi kesalahan parsing pada model yang tidak mendukung constrained decoding secara native, terapkan pola koreksi diri (Self-Correction Loop). Ketika ValidationError tertangkap, tangkapan pesan kesalahan (error trace) dikirimkan kembali ke LLM agar model dapat memperbaiki outputnya sendiri.


from pydantic import BaseModel, ValidationError


def execute_agent_with_retry(prompt: str, max_retries: int = 3):


    messages = [{"role": "user", "content": prompt}]


    for attempt in range(max_retries):


        raw_response = call_llm(messages)


        try:


            # Uji validitas JSON dan Schema


            validated_data = UserProfile.model_validate_json(raw_response)


            return validated_data


        except ValidationError as e:


            # Masukkan kesalahan ke dalam riwayat percakapan untuk koreksi


            messages.append({"role": "assistant", "content": raw_response})


            messages.append({


                "role": "user",


                "content": f"JSON yang Anda berikan tidak valid. Error: {e}. Harap perbaiki output JSON Anda."


            })


    raise RuntimeError("Agent gagal menghasilkan JSON valid setelah beberapa percobaan.")




### 



### 4. Perjelas Field Description pada Tool Definition


Kualitas prompt pada definisi alatan (tools) menentukan tingkat akurasi schema. Jangan menganggap model memahami konteks field hanya dari nama variabelnya.





- Hindari: "email": {"type": "string"}

- Gunakan: "email": {"type": "string", "description": "Alamat email resmi pengguna dengan format valid, contoh: nama@domain.com"}

- Gunakan Enum secara Eksplisit: Jika nilai variabel bersifat terbatas, berikan batasan enum langsung pada schema:
"status": {"type": "string", "enum": ["pending", "approved", "rejected"]}



## Checklist Singkat Sebelum Deployment Tool-Calling


Gunakan daftar verifikasi teknis berikut sebelum merilis fitur tool-calling atau JSON extraction ke lingkungan produksi:





- Aktifkan Native Strict Mode: Pastikan parameter strict: true aktif pada konfigurasi API provider yang mendukung Constrained Decoding.

- Validasi Runtime Pydantic/Zod: Pasang validator schema di layer aplikasi sebelum data diteruskan ke fungsi bisnis internal atau REST API.

- Isi Deskripsi Field Secara Spesifik: Seluruh field pada JSON schema memiliki deskripsi eksplisit, termasuk contoh format dan batasan nilai (enum).

- Terapkan Fallback & Retry Handler: Mekanisme penanganan error (retry loop) terpasang dengan batas maksimal pengulangan 2–3 kali untuk mencegah boros kredit API.

- Pembersihan String Mentah (Sanitization): Jalankan fungsi pembersih string (pembuang blok kode ```json dan whitespace ekstra) sebagai pertahanan pertama sebelum proses parsing.

- Evaluasi Unit Test Schema: Buat test suite yang menguji ketahanan agent terhadap edge cases seperti input pengguna yang ambigu atau kosong.


Error parsing JSON biasanya pertama kali muncul saat agent mulai memanggil tool. Alur dasarnya kami bahas di [tutorial menghubungkan AI agent ke tools dan API eksternal](https://komunitech.com/blog/ai-agent/cara-menghubungkan-ai-agent-ke-tools-api-eksternal-tutorial-kursus-gratis-2026/), sedangkan pesan error di luar urusan JSON, seperti 401 atau 429, dijelaskan di [panduan arti kode error pada AI agent](https://komunitech.com/blog/tutorial/arti-kode-error-pada-ai-agent-dan-solusinya/).

## FAQ Seputar Parsing Error & Schema JSON

### Mengapa LLM masih sering menyisipkan backtick markdown (```json) padahal sudah dilarang di prompt?

Karena data pre-training LLM didominasi oleh teks percakapan dan dokumentasi teknis yang terbiasa memformat kode dengan markdown. Jika hanya mengandalkan prompt, probabilitas token markdown tetap ada. Solusi paling pasti adalah menggunakan API Structured Outputs native (strict mode) atau regex/stripper di layer kode backend sebelum parsing.

### Apakah Pydantic otomatis membetulkan tipe data yang salah dari LLM?

Ya, Pydantic memiliki mekanisme type coercion. Misalnya, jika LLM mengembalikan string '42' untuk field berjenis integer, Pydantic akan otomatis mengonversinya menjadi angka 42. Namun, jika LLM mengembalikan nilai yang tidak bisa dikonversi (misal: 'empat puluh dua'), ValidationError akan dilempar.

### Kapan perlu memakai Self-Correction Loop vs Native Structured Outputs?

Jika provider LLM yang kamu pakai mendukung native structured outputs (seperti OpenAI Strict Mode atau Gemini JSON Mode), prioritaskan fitur native tersebut karena tingkat keberhasilannya 100% tanpa boros token. Gunakan Self-Correction Loop sebagai fallback saat memakai open-source LLM lokal (Ollama/vLLM) yang belum mendukung constrained decoding tingkat server.
