Keluaran terstruktur

Keluaran terstruktur membatasi respons Claude untuk mengikuti skema tertentu, memastikan keluaran yang valid dan dapat diurai untuk pemrosesan hilir. Gunakan keluaran JSON (output_format) untuk respons data terstruktur, atau penggunaan alat ketat (strict: true) untuk validasi skema yang dijamin pada nama alat dan masukan.

Mengapa menggunakan keluaran terstruktur

Tanpa keluaran terstruktur, Claude dapat menghasilkan respons JSON yang salah bentuk atau masukan alat yang tidak valid yang merusak aplikasi Anda. Bahkan dengan prompt yang hati-hati, Anda mungkin mengalami:

• Kesalahan penguraian dari sintaks JSON yang tidak valid
• Bidang yang diperlukan hilang
• Jenis data yang tidak konsisten
• Pelanggaran skema yang memerlukan penanganan kesalahan dan pengulangan

Keluaran terstruktur menjamin respons yang sesuai dengan skema melalui decoding terbatas:

• Selalu valid: Tidak ada lagi kesalahan JSON.parse()
• Aman tipe: Jenis bidang dan bidang yang diperlukan dijamin
• Andal: Tidak perlu pengulangan untuk pelanggaran skema
• Dua mode: JSON untuk tugas seperti ekstraksi data, dan alat ketat untuk situasi seperti alat kompleks dan alur kerja agentic

Mulai cepat

Kapan menggunakan keluaran JSON vs penggunaan alat ketat

Pilih mode yang tepat untuk kasus penggunaan Anda:

Mengapa penggunaan alat ketat penting untuk agen

Membangun sistem agentic yang andal memerlukan kepatuhan skema yang dijamin. Parameter alat yang tidak valid merusak fungsi dan alur kerja Anda. Claude mungkin mengembalikan jenis yang tidak kompatibel ("2" bukan 2) atau bidang yang hilang, menyebabkan kesalahan runtime.

Penggunaan alat ketat menjamin parameter yang aman tipe:

• Fungsi menerima argumen yang diketik dengan benar setiap saat
• Tidak perlu memvalidasi dan mengulang panggilan alat
• Agen siap produksi yang bekerja secara konsisten dalam skala

Misalnya, anggaplah sistem pemesanan membutuhkan passengers: int. Tanpa mode ketat, Claude mungkin memberikan passengers: "two" atau passengers: "2". Dengan strict: true, Anda dijamin passengers: 2.

Cara kerja keluaran terstruktur

Bekerja dengan keluaran JSON di SDK

SDK Python dan TypeScript menyediakan pembantu yang memudahkan bekerja dengan keluaran JSON, termasuk transformasi skema, validasi otomatis, dan integrasi dengan perpustakaan skema populer.

Menggunakan Pydantic dan Zod

Untuk pengembang Python dan TypeScript, Anda dapat menggunakan alat definisi skema yang familiar seperti Pydantic dan Zod daripada menulis skema JSON mentah.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

Metode khusus SDK

Python: client.beta.messages.parse() (Direkomendasikan)

Metode parse() secara otomatis mengubah model Pydantic Anda, memvalidasi respons, dan mengembalikan atribut parsed_output.

Python: Pembantu transform_schema()

Untuk ketika Anda perlu secara manual mengubah skema sebelum mengirim, atau ketika Anda ingin memodifikasi skema yang dihasilkan Pydantic. Tidak seperti client.beta.messages.parse(), yang secara otomatis mengubah skema yang disediakan, ini memberi Anda skema yang diubah sehingga Anda dapat menyesuaikannya lebih lanjut.

Cara kerja transformasi SDK

SDK Python dan TypeScript secara otomatis mengubah skema dengan fitur yang tidak didukung:

1. Hapus batasan yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
2. Perbarui deskripsi dengan informasi batasan (misalnya, "Harus minimal 100"), ketika batasan tidak langsung didukung dengan keluaran terstruktur
3. Tambahkan additionalProperties: false ke semua objek
4. Filter format string ke daftar yang didukung saja
5. Validasi respons terhadap skema asli Anda (dengan semua batasan)

Ini berarti Claude menerima skema yang disederhanakan, tetapi kode Anda masih menerapkan semua batasan melalui validasi.

Contoh: Bidang Pydantic dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, tetapi deskripsi diperbarui menjadi "Harus minimal 100", dan SDK memvalidasi respons terhadap batasan asli.

Kasus penggunaan umum

Pertimbangan penting

Kompilasi tata bahasa dan caching

Keluaran terstruktur menggunakan sampling terbatas dengan artefak tata bahasa yang dikompilasi. Ini memperkenalkan beberapa karakteristik kinerja yang perlu diperhatikan:

• Latensi permintaan pertama: Pertama kali Anda menggunakan skema tertentu, akan ada latensi tambahan saat tata bahasa dikompilasi
• Caching otomatis: Tata bahasa yang dikompilasi di-cache selama 24 jam dari penggunaan terakhir, membuat permintaan berikutnya jauh lebih cepat
• Invalidasi cache: Cache dibatalkan jika Anda mengubah:
  • Struktur skema JSON
  • Set alat dalam permintaan Anda (saat menggunakan keluaran terstruktur dan penggunaan alat)
  • Mengubah hanya bidang name atau description tidak membatalkan cache

Modifikasi prompt dan biaya token

Saat menggunakan keluaran terstruktur, Claude secara otomatis menerima prompt sistem tambahan yang menjelaskan format keluaran yang diharapkan. Ini berarti:

• Jumlah token masukan Anda akan sedikit lebih tinggi
• Prompt yang disuntikkan membebani Anda token seperti prompt sistem lainnya
• Mengubah parameter output_format akan membatalkan [cache prompt](/docs/Bahasa Indonesia/build-with-claude/prompt-caching) apa pun untuk utas percakapan itu

Batasan JSON Schema

Keluaran terstruktur mendukung JSON Schema standar dengan beberapa batasan. Baik keluaran JSON maupun penggunaan alat ketat berbagi batasan ini.

Keluaran yang tidak valid

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

Penolakan (stop_reason: "refusal")

Claude mempertahankan properti keselamatan dan kegunaannya bahkan saat menggunakan keluaran terstruktur. Jika Claude menolak permintaan karena alasan keselamatan:

• Respons akan memiliki stop_reason: "refusal"
• Anda akan menerima kode status 200
• Anda akan ditagih untuk token yang dihasilkan
• Keluaran mungkin tidak sesuai dengan skema Anda (penolakan memiliki prioritas)

Batas token tercapai (stop_reason: "max_tokens")

Jika respons terpotong karena mencapai batas max_tokens:

• Respons akan memiliki stop_reason: "max_tokens"
• Keluaran mungkin tidak lengkap dan tidak sesuai dengan skema Anda
• Coba lagi dengan nilai max_tokens yang lebih tinggi untuk mendapatkan keluaran terstruktur yang lengkap

Kesalahan validasi skema

Jika skema Anda menggunakan fitur yang tidak didukung atau terlalu kompleks, Anda akan menerima kesalahan 400:

"Terlalu banyak definisi rekursif dalam skema"

• Penyebab: Skema memiliki definisi rekursif yang berlebihan atau siklik
• Solusi: Sederhanakan struktur skema, kurangi kedalaman nesting

"Skema terlalu kompleks"

• Penyebab: Skema melebihi batas kompleksitas
• Solusi: Pecah menjadi skema yang lebih kecil, sederhanakan struktur, atau kurangi jumlah alat yang ditandai sebagai strict: true

Untuk masalah berkelanjutan dengan skema yang valid, hubungi dukungan dengan definisi skema Anda.

Kompatibilitas fitur

Bekerja dengan:

• [Pemrosesan batch](/docs/Bahasa Indonesia/build-with-claude/batch-processing): Proses keluaran terstruktur dalam skala dengan diskon 50%
• [Penghitungan token](/docs/Bahasa Indonesia/build-with-claude/token-counting): Hitung token tanpa kompilasi
• [Streaming](/docs/Bahasa Indonesia/build-with-claude/streaming): Stream keluaran terstruktur seperti respons normal
• Penggunaan gabungan: Gunakan keluaran JSON (output_format) dan penggunaan alat ketat (strict: true) bersama dalam permintaan yang sama

Tidak kompatibel dengan:

• [Kutipan](/docs/Bahasa Indonesia/build-with-claude/citations): Kutipan memerlukan interleaving blok kutipan dengan teks, yang bertentangan dengan batasan skema JSON ketat. Mengembalikan kesalahan 400 jika kutipan diaktifkan dengan output_format.
• [Prefilling Pesan](/docs/Bahasa Indonesia/build-with-claude/prompt-engineering/prefill-claudes-response): Tidak kompatibel dengan keluaran JSON