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
• Penggunaan alat ketat (strict: true): Menjamin validasi skema pada nama dan input alat

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

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-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,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

Format respons: JSON valid yang cocok dengan skema Anda dalam blok konten teks respons

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

Cara kerjanya

1. 1

   Definisikan skema JSON Anda

   Buat skema JSON yang mendeskripsikan struktur yang Anda inginkan untuk diikuti Claude. Skema ini menggunakan format JSON Schema standar dengan beberapa batasan (lihat Batasan JSON Schema).

2. 2

   Tambahkan parameter output_config.format

   Sertakan parameter output_config.format dalam permintaan API Anda dengan type: "json_schema" dan definisi skema Anda.

3. 3

   Parse respons

   Respons Claude adalah JSON valid yang cocok dengan skema Anda, dikembalikan dalam blok konten teks respons.

Bekerja dengan output JSON di SDK

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

Menggunakan definisi skema native

Alih-alih menulis skema JSON mentah, Anda dapat menggunakan alat definisi skema yang sudah 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-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)

Metode khusus SDK

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

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Akses output yang telah di-parse secara langsung
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Pertama, konversi model Pydantic ke skema JSON, lalu transformasikan
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Ubah skema jika diperlukan
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

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 transformasinya:

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 oleh output terstruktur
3. Menambahkan additionalProperties: false ke semua objek
4. Memfilter format string hanya ke daftar yang didukung
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 deskripsinya menjadi "Must be at least 100" dan memvalidasi respons terhadap constraint asli.

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

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.

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