Output terstruktur

"Structured outputs" (output terstruktur) membatasi respons Claude agar mengikuti skema tertentu, memastikan output yang valid dan dapat di-parse untuk pemrosesan lanjutan. 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.
• "Strict tool use" (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 bentuk atau input alat yang tidak valid sehingga merusak aplikasi Anda. Bahkan dengan prompting yang cermat, Anda mungkin menemui:

• Error parsing akibat sintaks JSON yang tidak valid
• Field wajib yang hilang
• Tipe data yang tidak konsisten
• Pelanggaran skema yang memerlukan penanganan error dan percobaan ulang

Output terstruktur menjamin respons yang sesuai skema melalui "constrained decoding" (decoding terbatas):

• Selalu valid: Tidak ada lagi error JSON.parse()
• Aman secara tipe: Tipe field dan field wajib terjamin
• Andal: Tidak perlu percobaan ulang untuk pelanggaran skema

Cara kerjanya

1. 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. 2

   Kirim dalam output_config.format

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

3. 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)

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

Cara kerja transformasi SDK

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

1. Menghapus constraint yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
2. Memperbarui deskripsi dengan menambahkan setiap constraint yang tidak didukung ke deskripsi field (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 constraint-nya, jika helper memvalidasi respons

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

Contoh: Field dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, dan SDK menambahkan {minimum: 100} ke deskripsi field. 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)

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

Kasus penggunaan umum

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

Penggunaan alat ketat

Untuk menegakkan kepatuhan JSON Schema pada input alat dengan sampling yang dibatasi grammar, lihat Penggunaan alat ketat.

Menggunakan kedua fitur bersama-sama

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

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

Ketika 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 pemanggilan alat yang andal sekaligus output akhir yang terstruktur.

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 dan caching grammar

Output terstruktur menggunakan sampling terbatas dengan artefak grammar yang dikompilasi. Ini memperkenalkan beberapa karakteristik performa yang perlu diperhatikan:

• Latensi permintaan pertama: Pertama kali Anda menggunakan skema tertentu, ada latensi tambahan saat grammar dikompilasi
• Caching otomatis: Grammar yang dikompilasi di-cache selama 24 jam sejak penggunaan terakhir, membuat permintaan berikutnya jauh lebih cepat
• Invalidasi cache: Cache diinvalidasi jika Anda mengubah:
  • Struktur skema JSON
  • Kumpulan alat dalam permintaan Anda (saat menggunakan output terstruktur dan penggunaan alat bersamaan)
  • Mengubah hanya field name atau description tidak menginvalidasi cache

Modifikasi prompt dan biaya token

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

• Jumlah token input Anda sedikit lebih tinggi
• Prompt yang disisipkan membebani Anda token seperti prompt sistem lainnya
• Mengubah parameter output_config.format akan menginvalidasi cache prompt apa pun untuk thread 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.

Urutan properti

Saat menggunakan output terstruktur, properti dalam objek mempertahankan urutan yang didefinisikan dalam 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 akan 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 diutamakan daripada constraint 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 thinking.

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 enum dan const string: Claude mungkin mengembalikan nilai yang berbeda dari skema Anda hanya dalam kapitalisasi, biasanya pada huruf pertama kata setelah spasi. Misalnya, dengan skema ini:

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

Output mungkin berisi "Conversation Topic 3" (huruf "T" kapital) meskipun nilai persis tersebut tidak ada dalam enum. Respons selesai secara normal, tanpa error dan tanpa stop_reason khusus. Ini berlaku untuk output JSON maupun 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 skema JSON Anda menjadi grammar yang membatasi output Claude. Skema yang lebih kompleks menghasilkan grammar yang lebih besar dan membutuhkan waktu lebih lama untuk dikompilasi. Untuk melindungi dari waktu kompilasi yang berlebihan, API menegakkan beberapa batas kompleksitas.

Batas eksplisit

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

Batas internal tambahan

Di luar batas eksplisit dalam tabel sebelumnya, ada batas internal tambahan pada ukuran grammar 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 grammar yang dikompilasi menjadi sangat besar secara tidak proporsional.

Ketika batas ini terlampaui, Anda akan menerima error 400 dengan pesan "Schema is too complex for compilation." Error ini berarti kompleksitas gabungan skema Anda melebihi apa yang dapat dikompilasi secara efisien, meskipun setiap batas individual dalam tabel sebelumnya terpenuhi. Sebagai pengaman terakhir, API juga menegakkan batas waktu kompilasi 180 detik. Skema yang lolos semua pemeriksaan eksplisit tetapi menghasilkan grammar 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 kritis sebagai ketat. Jika Anda memiliki banyak alat, gunakan mode 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 state grammar. Jika suatu parameter selalu memiliki default yang wajar, pertimbangkan untuk menjadikannya wajib dan meminta Claude memberikan default tersebut secara eksplisit.

3. Sederhanakan struktur bersarang. Objek yang bersarang dalam dengan field opsional melipatgandakan kompleksitas. Ratakan struktur jika memungkinkan.

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

Untuk masalah yang terus berlanjut dengan skema yang valid, hubungi dukungan dengan 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 dan akan dihapus di masa mendatang. Jika tetap ingin menggunakannya, tambahkan header beta structured-outputs-2025-11-13. Tanpa header tersebut, API mengembalikan error 400.

Python SDK (v1.0 dan yang lebih baru) tidak menerima output_format={...} pada client.beta.messages.create() atau count_tokens() dan memunculkan TypeError. Gunakan output_config sebagai gantinya. Lihat Menggunakan skema JSON mentah untuk bentuk API yang diperbarui.

Retensi data

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 grammar 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 oleh pengamanan HIPAA.

Untuk kelayakan ZDR dan HIPAA di semua fitur, lihat API dan retensi data.

Kompatibilitas fitur

Berfungsi dengan:

• Pemrosesan batch: Proses output terstruktur dalam skala besar dengan diskon 50%
• Penghitungan token: Hitung token tanpa kompilasi
• Streaming: Stream output terstruktur seperti respons biasa
• 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 constraint skema JSON ketat. Mengembalikan error 400 jika kutipan diaktifkan bersama output_config.format.
• Prefilling Pesan: Tidak kompatibel dengan output JSON

Langkah selanjutnya

Compatibility