Output terstruktur

Output terstruktur membatasi respons Claude agar mengikuti skema tertentu, memastikan output yang valid dan dapat diurai untuk pemrosesan lanjutan. Output terstruktur menyediakan dua fitur yang saling melengkapi:

• Output JSON (output_config.format): Dapatkan respons Claude dalam format JSON tertentu
• Penggunaan alat ketat (strict: true): Menjamin validasi skema pada nama dan input alat

Anda dapat menggunakan fitur-fitur ini secara independen atau bersamaan 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 dari sintaks JSON yang tidak valid
• Field 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 lagi kesalahan JSON.parse()
• Aman secara tipe: Tipe field dan field wajib yang terjamin
• Andal: Tidak perlu percobaan ulang untuk pelanggaran skema



Output JSON

Output JSON mengontrol format respons Claude, memastikan Claude mengembalikan JSON valid yang cocok dengan skema Anda. Gunakan output JSON ketika Anda perlu:

• Mengontrol format respons Claude
• Mengekstrak data dari gambar atau teks
• Menghasilkan laporan terstruktur
• Memformat respons API



Mulai cepat

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    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_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,
            },
        }
    },
)
print(response.content[0].text)

Format respons: JSON valid yang cocok dengan skema Anda di response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}



Cara kerjanya



Bekerja dengan output JSON di SDK

SDK menyediakan helper yang memudahkan bekerja dengan output JSON, termasuk transformasi skema, validasi otomatis, dan integrasi dengan pustaka skema populer.



Menggunakan definisi skema native

Alih-alih menulis skema JSON mentah, Anda dapat menggunakan alat definisi skema yang familier dalam bahasa Anda:

• Python: Model Pydantic dengan client.messages.parse()
• TypeScript: Skema Zod dengan zodOutputFormat() atau literal JSON Schema bertipe dengan jsonSchemaOutputFormat()
• Java: Kelas Java biasa dengan derivasi skema otomatis melalui outputConfig(Class<T>)
• Ruby: Kelas Anthropic::BaseModel dengan output_config: {format: Model}
• PHP: Kelas yang mengimplementasikan StructuredOutputModel dengan outputConfig: ['format' => MyClass::class]
• C#: Kelas C# biasa dengan overload generik Create<T>(), yang menurunkan skema secara otomatis
• Go: Struct Go yang direfleksikan menjadi skema JSON secara otomatis pada API beta, atau skema JSON mentah melalui output_config
• CLI: Skema JSON mentah yang diteruskan melalui output_config

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    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

Setiap SDK menyediakan helper yang memudahkan bekerja dengan output terstruktur. Lihat halaman SDK masing-masing untuk detail lengkap.



Cara kerja transformasi SDK

SDK Python, TypeScript, Ruby, dan PHP secara otomatis mentransformasi skema dengan fitur yang tidak didukung. SDK C# dan Go menerapkan transformasi yang sama ketika skema diturunkan dari tipe native (Create<T>() di C#; refleksi struct atau BetaJSONSchemaOutputFormat() pada API beta Go). Langkah-langkah transformasi:

1. Menghapus constraint yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
2. Memperbarui deskripsi dengan info constraint (misalnya, "Must be at least 100"), ketika constraint tidak didukung secara langsung dengan output terstruktur
3. Menambahkan additionalProperties: false ke semua objek
4. Memfilter format string ke daftar yang didukung saja
5. Memvalidasi respons terhadap skema asli Anda (dengan semua constraint)

Ini berarti Claude menerima skema yang disederhanakan, tetapi kode Anda tetap menegakkan semua constraint melalui validasi.

Contoh: Field Pydantic dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, tetapi SDK memperbarui deskripsi menjadi "Must be at least 100" dan memvalidasi respons terhadap constraint asli.



Kasus penggunaan umum



Penggunaan alat ketat

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



Menggunakan kedua fitur bersamaan

Output JSON dan penggunaan alat ketat menyelesaikan 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 dan output akhir yang terstruktur.

response = client.messages.create(
    model="claude-opus-4-8",
    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 terjamin
    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 grammar dan caching

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 disuntikkan dikenakan biaya 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. Baik output JSON maupun penggunaan alat ketat berbagi batasan ini.



Pengurutan properti

Saat menggunakan output terstruktur, properti dalam objek mempertahankan urutan yang didefinisikan dari skema Anda, dengan satu peringatan 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": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Jika urutan properti dalam output penting untuk 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 properti 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 constraint skema

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



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 yang 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 berinteraksi satu sama lain dengan cara yang dapat membuat grammar 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 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 ini secara berurutan:

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

2. Kurangi parameter opsional. Buat parameter required jika memungkinkan. Setiap parameter opsional kira-kira menggandakan sebagian dari ruang state grammar. Jika parameter selalu memiliki default yang masuk akal, pertimbangkan untuk membuatnya wajib dan meminta Claude memberikan default tersebut secara eksplisit.

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

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

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



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 di bawah 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 normal
• Penggunaan gabungan: Gunakan output JSON (output_config.format) dan penggunaan alat ketat (strict: true) bersamaan dalam permintaan yang sama

Tidak kompatibel dengan:

• Sitasi: Sitasi memerlukan penyisipan blok sitasi dengan teks, yang bertentangan dengan constraint skema JSON yang ketat. Mengembalikan kesalahan 400 jika sitasi diaktifkan dengan output_config.format.
• Prefilling Pesan: Tidak kompatibel dengan output JSON



Langkah selanjutnya