Output terstruktur

Output terstruktur membatasi respons Claude agar mengikuti skema tertentu, memastikan output yang valid dan dapat diurai untuk pemrosesan hilir. Dua fitur pelengkap tersedia:

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

Fitur-fitur ini dapat digunakan secara independen atau bersama-sama dalam permintaan yang sama.

Mengapa menggunakan output terstruktur

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

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

Output terstruktur menjamin respons yang sesuai skema melalui decoding terbatas:

• Selalu valid: Tidak ada lagi kesalahan JSON.parse()
• Aman tipe: Tipe bidang dan bidang yang diperlukan terjamin
• Andal: Tidak perlu percobaan ulang untuk pelanggaran skema

Output JSON

Output JSON mengontrol format respons Claude, memastikan Claude mengembalikan JSON valid yang sesuai 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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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
        }
      }
    }
  }'

Format respons: JSON valid yang sesuai 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 pengerjaan 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 familiar dalam bahasa Anda:

• Python: Model Pydantic dengan client.messages.parse()
• TypeScript: Skema Zod dengan zodOutputFormat()
• Java: Kelas Java biasa dengan derivasi skema otomatis melalui outputFormat(Class<T>)
• Ruby: Kelas Anthropic::BaseModel dengan output_config: {format: Model}
• C#, Go, PHP: 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-6",
    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 pengerjaan structured outputs. Lihat halaman SDK individual untuk detail lengkap.

Cara kerja transformasi SDK

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

1. Menghapus batasan yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
2. Memperbarui deskripsi dengan info batasan (misalnya, "Harus minimal 100"), ketika batasan tidak didukung langsung dengan structured outputs
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 batasan)

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

Contoh: Field 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

Penggunaan tool yang ketat

Penggunaan tool yang ketat memvalidasi parameter tool, memastikan Claude memanggil fungsi Anda dengan argumen yang bertipe dengan benar. Gunakan penggunaan tool yang ketat ketika Anda perlu:

• Memvalidasi parameter tool
• Membangun alur kerja agentic
• Memastikan pemanggilan fungsi yang type-safe
• Menangani tool kompleks dengan properti bersarang

Mengapa penggunaan tool yang ketat penting untuk agen

Membangun sistem agentic yang andal memerlukan jaminan kesesuaian skema. Tanpa mode ketat, Claude mungkin mengembalikan tipe yang tidak kompatibel ("2" alih-alih 2) atau field yang diperlukan hilang, merusak fungsi Anda dan menyebabkan kesalahan runtime.

Penggunaan tool yang ketat menjamin parameter yang type-safe:

• Fungsi menerima argumen yang bertipe dengan benar setiap saat
• Tidak perlu memvalidasi dan mencoba ulang pemanggilan tool
• Agen siap produksi yang bekerja secara konsisten dalam skala besar

Misalnya, anggaplah sistem pemesanan membutuhkan passengers: int. Tanpa mode ketat, Claude mungkin memberikan passengers: "two" atau passengers: "2". Dengan strict: true, respons akan selalu berisi passengers: 2.

Mulai cepat

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

Format respons: Blok penggunaan tool dengan input yang telah divalidasi di response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Jaminan:

• input tool secara ketat mengikuti input_schema
• name tool selalu valid (dari tool yang disediakan atau server tools)

Cara kerjanya

Kasus penggunaan umum

Menggunakan kedua fitur bersama-sama

Output JSON dan penggunaan tool yang ketat memecahkan masalah yang berbeda dan dapat digunakan bersama-sama:

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

Ketika digabungkan, Claude dapat memanggil tool dengan parameter yang terjamin valid DAN mengembalikan respons JSON terstruktur. Ini berguna untuk alur kerja agentic di mana Anda membutuhkan panggilan tool yang andal sekaligus output akhir yang terstruktur.

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Help me plan a trip to Paris for next month"}
    ],
    # 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 tool yang ketat: parameter tool yang 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,
            },
        }
    ],
)

Pertimbangan penting

Kompilasi grammar dan caching

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

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

Modifikasi prompt dan biaya token

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

• Jumlah token input Anda akan sedikit lebih tinggi
• Prompt yang disuntikkan membutuhkan token seperti system prompt lainnya
• Mengubah parameter output_config.format akan menginvalidasi cache prompt mana pun untuk thread percakapan tersebut

Keterbatasan JSON Schema

Output terstruktur mendukung JSON Schema standar dengan beberapa keterbatasan. Baik output JSON maupun penggunaan tool yang ketat berbagi keterbatasan ini.

Urutan properti

Saat menggunakan output terstruktur, properti dalam objek mempertahankan urutan yang ditentukan dari skema Anda, dengan satu catatan penting: properti yang diperlukan muncul pertama, 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 (diperlukan, dalam urutan skema)
2. email (diperlukan, dalam urutan skema)
3. notes (opsional, dalam urutan skema)
4. age (opsional, dalam 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, pastikan semua properti ditandai sebagai required, atau pertimbangkan pengurutan ulang ini dalam logika parsing Anda.

Output yang tidak valid

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

Penolakan (stop_reason: "refusal")

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

• Respons akan memiliki stop_reason: "refusal"
• Anda akan menerima kode status 200
• Anda akan ditagih untuk token yang dihasilkan
• Output mungkin tidak sesuai dengan skema Anda karena pesan penolakan mengambil prioritas di atas batasan skema

Batas token tercapai (stop_reason: "max_tokens")

Jika respons terpotong karena mencapai batas max_tokens:

• Respons akan memiliki stop_reason: "max_tokens"
• Output mungkin tidak lengkap dan tidak sesuai 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 memberlakukan 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 di atas, 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 tool 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 error 400 dengan pesan "Schema is too complex for compilation." Error ini berarti kompleksitas gabungan skema Anda melebihi apa yang dapat dikompilasi secara efisien, bahkan jika setiap batas individual di atas terpenuhi. Sebagai langkah terakhir, API juga memberlakukan batas waktu kompilasi 180 detik. Skema yang melewati semua pemeriksaan eksplisit tetapi menghasilkan grammar yang dikompilasi 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 tool kritis sebagai ketat. Jika Anda memiliki banyak tool, simpan untuk tool di mana pelanggaran skema menyebabkan masalah nyata, dan andalkan kepatuhan alami Claude untuk tool yang lebih sederhana.

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

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

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

Untuk masalah persisten 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 terakhir digunakan untuk tujuan optimasi. Tidak ada data prompt atau respons yang disimpan di luar respons API.

Untuk kelayakan ZDR di semua fitur, lihat API dan Retensi Data.

Kompatibilitas fitur

Bekerja 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 tool yang ketat (strict: true) bersama-sama dalam permintaan yang sama

Tidak kompatibel dengan:

• Kutipan: Kutipan memerlukan penyisipan blok kutipan dengan teks, yang bertentangan dengan batasan skema JSON yang ketat. Mengembalikan error 400 jika kutipan diaktifkan dengan output_config.format.
• Prefilling Pesan: Tidak kompatibel dengan output JSON