Claude Platform Docs
PesanKemampuan model

Output terstruktur

Dapatkan hasil JSON yang tervalidasi dari alur kerja agen

“Structured outputs” (output terstruktur) membatasi respons Claude agar mengikuti skema tertentu, sehingga memastikan output yang valid dan dapat di-parse untuk pemrosesan hilir. Output terstruktur menyediakan dua fitur yang saling melengkapi:

  • Output JSON (output_config.format): Dapatkan respons Claude dalam format JSON tertentu, misalnya untuk mengekstrak data dari gambar atau teks, menghasilkan laporan terstruktur, atau memformat respons API. Halaman ini membahas output JSON.
  • Penggunaan alat ketat (strict: true): Menjamin validasi skema pada nama dan input alat. Lihat Penggunaan alat ketat.

Anda dapat menggunakan fitur-fitur ini secara terpisah atau bersama-sama dalam permintaan yang sama.

Mengapa menggunakan output terstruktur

Tanpa output terstruktur, Claude dapat menghasilkan respons JSON yang salah format atau input alat yang tidak valid yang merusak aplikasi Anda. Bahkan dengan prompting yang cermat, Anda mungkin menemui:

  • Kesalahan parsing akibat sintaks JSON yang tidak valid
  • Bidang wajib yang hilang
  • Tipe data yang tidak konsisten
  • Pelanggaran skema yang memerlukan penanganan kesalahan dan percobaan ulang

Output terstruktur menjamin respons yang sesuai skema melalui “constrained decoding” (dekode terbatas):

  • Selalu valid: Tidak ada kesalahan parsing JSON
  • Aman tipe: Tipe bidang dan bidang wajib terjamin
  • Andal: Tidak perlu percobaan ulang karena pelanggaran skema

Cara kerjanya

  1. Definisikan skema Anda

    Jelaskan struktur yang Anda inginkan sebagai skema JSON atau sebagai tipe dalam bahasa pemrograman Anda. Skema mengikuti JSON Schema, dengan beberapa batasan.

  2. Kirim dalam output_config.format

    Permintaan membawa skema dalam output_config.format dengan type: "json_schema". Helper SDK mengaturnya untuk Anda.

  3. Baca respons

    Claude mengembalikan JSON valid yang cocok dengan skema Anda di blok konten teks respons. Helper SDK mem-parse-nya ke dalam tipe Anda.

Penggunaan

from pydantic import BaseModel



class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

Berikan model Pydantic ke client.messages.parse(), metode yang direkomendasikan, sebagai output_format. SDK mentransformasi skema model, mengirimkannya sebagai output_config.format, memvalidasi respons, dan mengembalikan model yang telah di-parse dalam parsed_output.

Contoh sebelumnya menghasilkan output:

Output
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Jika Anda mengetahui kunci-kunci sebuah bidang, gunakan model Pydantic bersarang, bukan dict. SDK mengirimkan bidang dict sebagai objek dengan properties kosong, sehingga Claude hanya dapat mengembalikan {} untuk bidang tersebut. Jika Anda tidak mengetahui kuncinya sebelumnya, lihat Objek dengan kunci arbitrer.

Cara kerja transformasi SDK

Sebagian besar helper SDK mentransformasi skema yang menggunakan fitur yang tidak didukung. Langkah-langkah transformasinya:

  1. Menghapus batasan yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
  2. Memperbarui deskripsi dengan menambahkan setiap batasan yang tidak didukung ke deskripsi bidang (misalnya, {minimum: 100})
  3. Menambahkan additionalProperties: false ke semua objek
  4. Memfilter format string hanya ke daftar yang didukung
  5. Memvalidasi respons terhadap skema asli Anda dan semua batasannya, jika helper memvalidasi respons

Claude menerima skema yang disederhanakan, tetapi helper yang memvalidasi respons tetap menegakkan setiap batasan dalam kode Anda.

Contoh: Bidang dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, dan SDK menambahkan {minimum: 100} ke deskripsi bidang. Helper yang memvalidasi respons tetap memeriksa respons terhadap minimum: 100.

Menggunakan skema JSON mentah

Untuk menggunakan skema JSON dari file, spesifikasi OpenAPI, atau kode yang membangunnya saat runtime, berikan skema tersebut dalam output_config.format.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

Contoh sebelumnya menghasilkan output:

Output
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

Untuk memindahkan batasan yang tidak didukung oleh API ke dalam deskripsi bidang, lewatkan skema melalui transform_schema() dari paket anthropic sebelum mengirimkannya, dan edit hasilnya jika perlu. transform_schema() juga menerima model Pydantic. Berbeda dengan client.messages.parse(), fungsi ini mengembalikan skema yang telah ditransformasi alih-alih mengirimkannya.

Kasus penggunaan umum

Penggunaan alat ketat

Untuk menegakkan kepatuhan JSON Schema pada input alat dengan “grammar-constrained sampling” (sampling yang dibatasi tata bahasa), lihat Penggunaan alat ketat.

Menggunakan kedua fitur bersama-sama

Output JSON dan penggunaan alat ketat menyelesaikan masalah yang berbeda dan dapat bekerja bersama:

  • Output JSON mengontrol format respons Claude (apa yang dikatakan Claude).
  • Penggunaan alat ketat memvalidasi parameter alat (bagaimana Claude memanggil fungsi Anda).

Jika digabungkan, Claude dapat memanggil alat dengan parameter yang dijamin valid DAN mengembalikan respons JSON terstruktur. Ini berguna untuk alur kerja agentik di mana Anda memerlukan panggilan alat yang andal sekaligus output akhir yang terstruktur.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Output JSON: format respons terstruktur
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Penggunaan alat ketat: parameter alat yang dijamin
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Pertimbangan penting

Kompilasi tata bahasa dan caching

Output terstruktur menggunakan sampling terbatas dengan artefak tata bahasa yang dikompilasi. Hal ini menimbulkan beberapa karakteristik kinerja yang perlu diperhatikan:

  • Latensi permintaan pertama: Pertama kali Anda menggunakan skema tertentu, ada “latency” (latensi) tambahan saat tata bahasa dikompilasi.
  • Caching otomatis: Tata bahasa yang dikompilasi di-cache selama 24 jam sejak penggunaan terakhir, sehingga permintaan berikutnya jauh lebih cepat.
  • Invalidasi cache: Cache diinvalidasi jika Anda mengubah struktur skema JSON atau, saat menggunakan output terstruktur dan penggunaan alat sekaligus, kumpulan alat dalam permintaan Anda. Mengubah hanya bidang name atau description tidak menginvalidasi cache.

Modifikasi prompt dan biaya token

Saat menggunakan output terstruktur, Claude secara otomatis menerima “system prompt” (prompt sistem) tambahan yang menjelaskan format output yang diharapkan. Ini berarti:

  • Jumlah token input Anda sedikit lebih tinggi.
  • Prompt yang disisipkan membebankan token kepada Anda seperti prompt sistem lainnya.
  • Mengubah parameter output_config.format menginvalidasi cache prompt apa pun untuk utas percakapan tersebut.

Batasan JSON Schema

Output terstruktur mendukung JSON Schema standar dengan beberapa batasan. Output JSON dan penggunaan alat ketat sama-sama memiliki batasan ini.

Objek dengan kunci arbitrer

Cantumkan setiap kunci sebuah objek, baik dalam properties maupun sebagai bidang dari class atau skema yang Anda berikan ke SDK. Karena additionalProperties harus bernilai false, Claude hanya dapat mengembalikan kunci yang Anda cantumkan.

API menerima objek dengan properties yang kosong atau tidak ada, tetapi Claude hanya dapat mengembalikan {} untuknya. Tipe map, dictionary, atau record tidak mencantumkan kunci apa pun, sehingga SDK Python dan TypeScript mengirimkannya sebagai objek dengan properties kosong. SDK Java dan Ruby justru memunculkan kesalahan.

Jika Anda tidak mengetahui kuncinya sebelumnya, gunakan array sebagai gantinya. Berikan setiap item sebuah key dan value, seperti dalam skema ini:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

Urutan properti

Saat menggunakan output terstruktur, properti dalam objek mempertahankan urutan yang didefinisikan dari skema Anda, dengan satu catatan penting: properti wajib muncul terlebih dahulu, diikuti oleh properti opsional.

Misalnya, dengan skema ini:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Output mengurutkan properti sebagai:

  1. name (wajib, sesuai urutan skema)
  2. email (wajib, sesuai urutan skema)
  3. notes (opsional, sesuai urutan skema)
  4. age (opsional, sesuai urutan skema)

Ini berarti output mungkin terlihat seperti:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Jika urutan properti dalam output penting bagi aplikasi Anda, tandai semua properti sebagai wajib, atau perhitungkan pengurutan ulang ini dalam logika parsing Anda.

Output tidak valid

Meskipun output terstruktur menjamin kepatuhan skema dalam sebagian besar kasus, ada skenario di mana output mungkin tidak cocok dengan skema Anda:

Penolakan (stop_reason: "refusal")

Claude mempertahankan sifat keamanan dan kebermanfaatannya bahkan saat menggunakan output terstruktur. Jika Claude menolak permintaan karena alasan keamanan:

  • Respons memiliki stop_reason: "refusal".
  • Anda akan menerima kode status 200.
  • Anda akan ditagih untuk token yang dihasilkan.
  • Output mungkin tidak cocok dengan skema Anda karena pesan penolakan lebih diutamakan daripada batasan skema.

Properti yang meminta pemikiran model atau penalaran langkah demi langkah dapat menyebabkan penolakan reasoning_extraction. Mintalah penjelasan singkat sebagai gantinya. Lihat Simpan penalaran di blok pemikiran.

Batas token tercapai (stop_reason: "max_tokens")

Jika respons terpotong karena mencapai batas max_tokens:

  • Respons memiliki stop_reason: "max_tokens".
  • Output mungkin tidak lengkap dan tidak cocok dengan skema Anda.
  • Coba lagi dengan nilai max_tokens yang lebih tinggi untuk mendapatkan output terstruktur yang lengkap.

Kapitalisasi nilai enum

Output terstruktur tidak menjamin kapitalisasi nilai string enum dan const: Claude mungkin mengembalikan nilai yang berbeda dari skema Anda hanya dalam kapitalisasi, biasanya pada huruf pertama kata yang mengikuti spasi. Misalnya, dengan skema ini:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

Output mungkin berisi "Conversation Topic 3" (huruf kapital “T”) meskipun nilai persis tersebut tidak ada dalam enum. Respons selesai secara normal, tanpa kesalahan dan tanpa stop_reason khusus. Ini berlaku untuk output JSON dan penggunaan alat ketat. Bandingkan nilai enum tanpa membedakan huruf besar/kecil, dan hindari nilai enum yang hanya berbeda dalam kapitalisasi.

Batas kompleksitas skema

Output terstruktur bekerja dengan mengompilasi JSON schema Anda menjadi tata bahasa yang membatasi output Claude. Skema yang lebih kompleks menghasilkan tata bahasa yang lebih besar yang membutuhkan waktu lebih lama untuk dikompilasi. Untuk melindungi dari waktu kompilasi yang berlebihan, API menerapkan beberapa batas kompleksitas.

Batas eksplisit

Batas berikut berlaku untuk semua permintaan dengan output_config.format atau strict: true:

BatasNilaiDeskripsi
Alat ketat per permintaan20Jumlah maksimum alat dengan strict: true. Alat non-ketat tidak dihitung dalam batas ini.
Parameter opsional24Total parameter opsional di semua skema alat ketat dan skema output JSON. Setiap parameter yang tidak tercantum dalam required dihitung dalam batas ini.
Parameter dengan tipe union16Total parameter yang menggunakan anyOf atau array tipe (misalnya, "type": ["string", "null"]) di semua skema ketat. Parameter ini sangat mahal karena menciptakan biaya kompilasi eksponensial.

Batas internal tambahan

Selain batas eksplisit dalam tabel sebelumnya, terdapat batas internal tambahan pada ukuran tata bahasa yang dikompilasi. Batas ini ada karena kompleksitas skema tidak dapat direduksi menjadi satu dimensi: fitur seperti parameter opsional, tipe union, objek bersarang, dan jumlah alat saling berinteraksi dengan cara yang dapat membuat tata bahasa yang dikompilasi menjadi sangat besar secara tidak proporsional.

Ketika batas ini terlampaui, Anda akan menerima kesalahan 400 dengan pesan “Schema is too complex for compilation.” Kesalahan ini berarti kompleksitas gabungan skema Anda melebihi apa yang dapat dikompilasi secara efisien, bahkan jika setiap batas individual dalam tabel sebelumnya terpenuhi. Sebagai pengaman terakhir, API juga menerapkan batas waktu kompilasi 180 detik. Skema yang lolos semua pemeriksaan eksplisit tetapi menghasilkan tata bahasa terkompilasi yang sangat besar mungkin mencapai batas waktu ini.

Tips untuk mengurangi kompleksitas skema

Jika Anda mencapai batas kompleksitas, coba strategi berikut secara berurutan:

  1. Tandai hanya alat penting sebagai ketat. Jika Anda memiliki banyak alat, gunakan penggunaan alat ketat hanya untuk alat di mana pelanggaran skema menyebabkan masalah nyata, dan andalkan kepatuhan alami Claude untuk alat yang lebih sederhana.

  2. Kurangi parameter opsional. Jadikan parameter required jika memungkinkan. Setiap parameter opsional kira-kira menggandakan sebagian ruang status tata bahasa. Jika sebuah parameter selalu memiliki nilai default yang wajar, pertimbangkan untuk menjadikannya wajib dan minta Claude memberikan nilai default tersebut secara eksplisit.

  3. Sederhanakan struktur bersarang. Objek yang bersarang dalam dengan bidang opsional memperparah kompleksitas. Ratakan struktur jika memungkinkan.

  4. Pisahkan menjadi beberapa permintaan. Jika Anda memiliki banyak alat ketat, pertimbangkan untuk membaginya ke beberapa permintaan terpisah atau subagen.

Untuk masalah yang terus berlanjut dengan skema yang valid, hubungi dukungan dengan menyertakan definisi skema Anda.

Migrasi dari beta

Parameter output_format telah dipindahkan ke output_config.format, dan header beta tidak lagi diperlukan. Parameter output_format sudah usang. Untuk tetap menggunakannya, tambahkan header beta structured-outputs-2025-11-13. Tanpa header tersebut, API mengembalikan kesalahan 400.

Di Python SDK (v1.0 dan yang lebih baru), dictionary skema yang diberikan sebagai output_format={...} memunculkan TypeError. Gunakan output_config sebagai gantinya. Model Pydantic yang diberikan sebagai output_format=Model ke parse() atau stream() berfungsi tanpa perubahan dan tanpa header beta, karena SDK mengirimkannya sebagai output_config. Lihat Menggunakan skema JSON mentah untuk bentuk API yang diperbarui.

Kompatibilitas fitur

Berfungsi dengan:

  • Pemrosesan batch: Proses output terstruktur dalam skala besar dengan diskon 50 persen
  • Penghitungan token: Hitung token tanpa kompilasi
  • Streaming: Streaming output terstruktur seperti respons normal
  • Penggunaan gabungan: Gunakan output JSON (output_config.format) dan penggunaan alat ketat (strict: true) bersama-sama dalam permintaan yang sama

Tidak kompatibel dengan:

  • Kutipan: Kutipan memerlukan penyisipan blok kutipan di antara teks, yang bertentangan dengan batasan skema JSON yang ketat. API mengembalikan kesalahan 400 jika kutipan diaktifkan bersama output_config.format. Untuk mengekstrak data terstruktur dengan kutipan untuk setiap nilai, lihat Mendapatkan data terstruktur dengan kutipan.
  • Prefilling pesan: Prefilling tidak kompatibel dengan output JSON.

Ketersediaan

Output terstruktur
API
  • Messages API
  • Managed Agents Tidak didukung
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages
Retensi data nolLayak (bersyarat)

Tidak termasuk Model yang dicakup

Prompt Anda dan output Claude tidak disimpan. Hanya JSON schema yang di-cache, hingga 24 jam sejak terakhir digunakan. Ini juga mencakup penggunaan alat ketat (strict: true pada alat), yang menggunakan pipeline grammar yang sama. Pelajari lebih lanjut

HIPAALayak

PHI tidak boleh disertakan dalam definisi JSON schema; lihat panduan penanganan PHI. Pelajari lebih lanjut

Prompt dan respons diproses dengan ZDR saat menggunakan output terstruktur. Namun, skema JSON itu sendiri di-cache sementara hingga 24 jam sejak penggunaan terakhir untuk tujuan optimasi. Tidak ada data prompt atau respons yang disimpan di luar respons API.

Output terstruktur memenuhi syarat HIPAA, tetapi PHI tidak boleh disertakan dalam definisi skema JSON. API mengompilasi skema JSON menjadi tata bahasa yang di-cache secara terpisah dari konten pesan, dan skema yang di-cache ini tidak menerima perlindungan PHI yang sama seperti prompt dan respons. Jangan sertakan PHI dalam nama properti skema, nilai enum, nilai const, atau ekspresi reguler pattern. PHI hanya boleh muncul dalam konten pesan (prompt dan respons), di mana PHI dilindungi berdasarkan perlindungan HIPAA.

Langkah selanjutnya

Minta Claude mengutip sumbernya saat menjawab pertanyaan tentang dokumen yang diberikan.

Tegakkan kepatuhan JSON Schema pada input alat Claude dengan sampling yang dibatasi tata bahasa.

Hubungkan Claude ke alat dan API eksternal. Pelajari di mana alat dijalankan dan bagaimana loop agentik bekerja.

Pelajari struktur harga Anthropic untuk model dan fitur.

Apakah halaman ini membantu?