Output terstruktur

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

• Output JSON (output_config.format): Dapatkan respons Claude dalam format JSON tertentu
• Penggunaan alat ketat (strict: true): Jamin 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 terbentuk dengan baik atau input 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
• Tipe data yang tidak konsisten
• Pelanggaran skema yang memerlukan penanganan kesalahan dan percobaan ulang

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

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

Output JSON

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

• Mengontrol format respons Claude
• Mengekstrak data dari gambar atau teks
• Menghasilkan laporan terstruktur
• Format 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 yang valid 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 Python dan TypeScript menyediakan pembantu yang memudahkan pekerjaan dengan output 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 alih-alih 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.messages.create(
    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": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
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

Python: client.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.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 setidaknya 100"), ketika batasan tidak langsung didukung dengan output 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 memberlakukan semua batasan melalui validasi.

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

Kasus penggunaan umum

Penggunaan alat ketat

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

• Memvalidasi parameter alat
• Membangun alur kerja agen
• Memastikan panggilan fungsi yang aman tipe
• Menangani alat kompleks dengan properti bersarang

Mengapa penggunaan alat ketat penting untuk agen

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

Penggunaan alat ketat menjamin parameter yang aman tipe:

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

Misalnya, anggaplah sistem pemesanan memerlukan 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 alat dengan input yang divalidasi di response.content[x].input

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

Jaminan:

• Input alat input ketat mengikuti input_schema
• Nama alat name selalu valid (dari alat yang disediakan atau alat server)

Cara kerjanya

Kasus penggunaan umum

Menggunakan kedua fitur bersama-sama

Output JSON dan penggunaan alat ketat menyelesaikan masalah yang berbeda dan dapat digunakan bersama-sama:

• Output JSON mengontrol format respons Claude (apa yang Claude katakan)
• 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 agen di mana Anda memerlukan panggilan alat yang andal dan 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"}],
    # JSON outputs: structured response format
    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
            }
        }
    },
    # Strict tool use: guaranteed tool parameters
    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 tata bahasa dan caching

Output 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 output terstruktur dan penggunaan alat bersama-sama)
  • Mengubah hanya bidang name atau description tidak membatalkan 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 akan sedikit lebih tinggi
• Prompt yang disuntikkan menghabiskan token Anda seperti prompt sistem lainnya
• Mengubah parameter output_config.format akan membatalkan cache prompt apa pun untuk utas percakapan itu

Batasan JSON Schema

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

Output yang tidak valid

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

Penolakan (stop_reason: "refusal")

Claude mempertahankan properti keselamatan dan kegunaannya bahkan saat menggunakan output 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
• Output mungkin tidak sesuai dengan skema Anda karena pesan penolakan mengambil alih batasan skema

Batas token tercapai (stop_reason: "max_tokens")

Jika respons dipotong 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

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 persisten dengan skema yang valid, hubungi dukungan dengan definisi skema Anda.

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

Tidak kompatibel dengan:

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