Panduan migrasi

Panduan ini mencakup migrasi kode Messages API. Jika Anda menggunakan Claude Managed Agents, lihat Migrasi antar versi model. Runtime Managed Agents menangani sebagian besar perubahan bentuk permintaan yang dijelaskan di sini.

Migrasi ke Claude 4.6

Claude Opus 4.6 adalah pengganti yang hampir drop-in untuk Claude 4.5, dengan beberapa perubahan yang merusak untuk diperhatikan. Untuk daftar lengkap fitur baru, lihat Yang baru di Claude 4.6.

Perbarui nama model Anda

# Migrasi Opus
model = "claude-opus-4-5"  # Sebelum
model = "claude-opus-4-6"  # Sesudah

Perubahan yang merusak

Penghapusan prefill: Prefilling pesan asisten mengembalikan kesalahan 400 pada model Claude 4.6. Gunakan structured outputs, instruksi system prompt, atau output_config.format sebagai gantinya.
Penawaran parameter tool: Model Claude 4.6 mungkin menghasilkan escape string JSON yang sedikit berbeda dalam argumen panggilan tool (misalnya, penanganan escape Unicode atau escape forward slash yang berbeda). Jika Anda mengurai input panggilan tool sebagai string mentah daripada menggunakan parser JSON, verifikasi logika parsing Anda. Parser JSON standar (seperti json.loads() atau JSON.parse()) menangani perbedaan ini secara otomatis.

Perubahan yang direkomendasikan

Ini tidak diperlukan tetapi akan meningkatkan pengalaman Anda:

Migrasi ke adaptive thinking: thinking: {type: "enabled", budget_tokens: N} sudah usang pada model Claude 4.6 dan akan dihapus dalam rilis model di masa depan. Beralih ke thinking: {type: "adaptive"} dan gunakan parameter effort untuk mengontrol kedalaman thinking. Lihat Adaptive thinking.

Migrasi dari Claude 4.1 atau lebih awal ke Claude 4.6

Jika Anda bermigrasi dari Opus 4.1, Sonnet 4, atau model sebelumnya langsung ke Claude 4.6, terapkan perubahan yang merusak Claude 4.6 di atas ditambah perubahan tambahan di bagian ini.

# Dari Opus 4.1
model = "claude-opus-4-1-20250805"  # Sebelum
model = "claude-opus-4-6"  # Sesudah

# Dari Sonnet 4
model = "claude-sonnet-4-20250514"  # Sebelum
model = "claude-opus-4-6"  # Sesudah

# Dari Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Sebelum
model = "claude-opus-4-6"  # Sesudah

Perubahan yang merusak tambahan

Perbarui parameter sampling

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Gunakan hanya temperature ATAU top_p, bukan keduanya:

Python

# Sebelum - Ini akan error pada model Claude 4+
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # Tidak dapat menggunakan keduanya
    # ...
)

# Sesudah
response = client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,  # Gunakan temperature ATAU top_p, bukan keduanya
    # ...
)

Perubahan yang direkomendasikan tambahan

Hapus header beta legacy: Hapus token-efficient-tools-2025-02-19 dan output-128k-2025-02-19. Semua model Claude 4+ memiliki penggunaan tool yang efisien token bawaan dan header ini tidak berpengaruh.

Daftar periksa migrasi Claude 4.6

Perbarui ID model ke claude-opus-4-6
BREAKING: Hapus prefill pesan asisten (mengembalikan kesalahan 400); gunakan structured outputs atau output_config.format sebagai gantinya
Recommended: Migrasi dari thinking: {type: "enabled", budget_tokens: N} ke thinking: {type: "adaptive"} dengan parameter effort (budget_tokens sudah usang dan akan dihapus dalam rilis di masa depan)
Verifikasi parsing JSON panggilan tool menggunakan parser JSON standar
Hapus header beta effort-2025-11-24 (effort sekarang GA)
Hapus header beta fine-grained-tool-streaming-2025-05-14
Hapus header beta (adaptive thinking mengaktifkan interleaved thinking secara otomatis)

Migrasi ke Claude Sonnet 4.6

Claude Sonnet 4.6 menggabungkan intelijen yang kuat dengan kinerja cepat, menampilkan kemampuan pencarian agentic yang ditingkatkan dan eksekusi kode gratis saat digunakan dengan web search atau web fetch. Ini ideal untuk tugas coding, analisis, dan konten sehari-hari.

Untuk gambaran lengkap kemampuan, lihat overview model.

Harga Sonnet 4.6 adalah $3 per juta token input, $15 per juta token output. Lihat Claude pricing untuk detail.

Perbarui nama model Anda:

# Dari Sonnet 4.5
model = "claude-sonnet-4-5"  # Sebelum
model = "claude-sonnet-4-6"  # Sesudah

# Dari Sonnet 4
model = "claude-sonnet-4-20250514"  # Sebelum
model = "claude-sonnet-4-6"  # Sesudah

Perubahan yang merusak

Saat bermigrasi dari Sonnet 4.5

Prefilling pesan asisten tidak lagi didukung

Ini adalah perubahan yang merusak saat bermigrasi dari Sonnet 4.5 atau lebih awal.

Prefilling pesan asisten mengembalikan kesalahan 400 pada Sonnet 4.6. Gunakan structured outputs, instruksi system prompt, atau output_config.format sebagai gantinya.

Kasus penggunaan prefill umum dan migrasi:
- Mengontrol format output (memaksa output JSON/YAML): Gunakan structured outputs atau tools dengan enum fields untuk tugas klasifikasi.
- Menghilangkan preamble (menghapus frasa "Here is..."): Tambahkan instruksi langsung dalam system prompt: "Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc."
- Menghindari penolakan buruk: Claude sekarang jauh lebih baik dalam penolakan yang tepat. Prompting yang jelas dalam pesan pengguna tanpa prefill harus cukup.

Saat bermigrasi dari Claude 3.x

Perbarui parameter sampling

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Gunakan hanya temperature ATAU top_p, bukan keduanya.
Perbarui versi tool

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Perbarui ke versi tool terbaru (text_editor_20250728, code_execution_20250825). Hapus kode apa pun yang menggunakan perintah undo_edit.
Tangani alasan stop refusal

Perbarui aplikasi Anda untuk menangani alasan stop refusal.

Perubahan yang direkomendasikan

Hapus header beta fine-grained-tool-streaming-2025-05-14: Fine-grained tool streaming sekarang GA pada Sonnet 4.6 dan tidak lagi memerlukan header beta.
Migrasi output_format ke output_config.format: Parameter output_format sudah usang. Gunakan output_config.format sebagai gantinya.

Migrasi dari Sonnet 4.5

Pertimbangkan untuk bermigrasi dari Sonnet 4.5 ke Sonnet 4.6, yang memberikan lebih banyak kecerdasan dengan harga yang sama.

Sonnet 4.6 menggunakan tingkat usaha default high, berbeda dengan Sonnet 4.5 yang tidak memiliki parameter usaha. Pertimbangkan untuk menyesuaikan parameter usaha saat Anda bermigrasi dari Sonnet 4.5 ke Sonnet 4.6. Jika tidak secara eksplisit diatur, Anda mungkin mengalami latensi yang lebih tinggi dengan tingkat usaha default.

Jika Anda tidak menggunakan pemikiran yang diperluas

Jika Anda tidak menggunakan pemikiran yang diperluas pada Sonnet 4.5, Anda dapat melanjutkan tanpanya pada Sonnet 4.6. Anda harus secara eksplisit mengatur usaha ke tingkat yang sesuai untuk kasus penggunaan Anda. Pada usaha low dengan pemikiran dinonaktifkan, Anda dapat mengharapkan kinerja yang sama atau lebih baik relatif terhadap Sonnet 4.5 tanpa pemikiran yang diperluas.

Jika Anda menggunakan pemikiran yang diperluas

Jika Anda menggunakan pemikiran yang diperluas dengan budget_tokens pada Sonnet 4.5, masih berfungsi pada Sonnet 4.6 tetapi sudah usang. Bermigrasi ke pemikiran adaptif dengan parameter usaha.

Bermigrasi ke pemikiran adaptif

Pemikiran adaptif adalah pengganti yang direkomendasikan untuk budget_tokens pada Sonnet 4.6. Ini sangat cocok untuk pola beban kerja berikut:

Agen multi-langkah otonom: agen pengkodean yang mengubah persyaratan menjadi perangkat lunak yang berfungsi, pipeline analisis data, dan pencarian bug di mana model berjalan secara independen di banyak langkah. Pemikiran adaptif memungkinkan model untuk mengkalibrasi penalarannya per langkah, tetap berada di jalur selama lintasan yang lebih panjang. Untuk beban kerja ini, mulai dengan usaha high. Jika latensi atau penggunaan token menjadi perhatian, kurangi ke medium.
Agen penggunaan komputer: Sonnet 4.6 mencapai akurasi terbaik di kelasnya pada evaluasi penggunaan komputer menggunakan mode adaptif.
Beban kerja bimodal: campuran tugas mudah dan sulit di mana adaptif melewatkan pemikiran pada kueri sederhana dan bernalar secara mendalam pada kueri kompleks.

Saat menggunakan pemikiran adaptif, evaluasi usaha medium dan high pada tugas Anda. Tingkat yang tepat tergantung pada pertukaran beban kerja Anda antara kualitas, latensi, dan penggunaan token.

Jika Anda melihat perilaku yang tidak konsisten atau regresi kualitas dengan pemikiran adaptif, coba kurangi pengaturan usaha atau gunakan max_tokens sebagai batas keras terlebih dahulu. Pemikiran yang diperluas dengan budget_tokens masih berfungsi pada Sonnet 4.6 tetapi sudah usang dan tidak lagi direkomendasikan.

Mempertahankan budget_tokens selama migrasi

Jika Anda perlu mempertahankan budget_tokens sementara saat bermigrasi, anggaran sekitar 16k token memberikan ruang untuk masalah yang lebih sulit tanpa risiko penggunaan token yang liar. Konfigurasi ini sudah usang dan akan dihapus dalam rilis model di masa depan.

Kasus penggunaan pengkodean dan agentic

Untuk pengkodean agentic, desain frontend, alur kerja berat alat, dan alur kerja enterprise yang kompleks, mulai dengan usaha medium. Jika Anda menemukan latensi terlalu tinggi, pertimbangkan untuk mengurangi usaha ke low. Jika Anda membutuhkan kecerdasan yang lebih tinggi, pertimbangkan untuk meningkatkan usaha ke high atau bermigrasi ke Opus 4.6.

Kasus penggunaan chat dan non-pengkodean

Untuk chat, pembuatan konten, pencarian, klasifikasi, dan tugas non-pengkodean lainnya, mulai dengan usaha low dengan pemikiran yang diperluas. Jika Anda membutuhkan kedalaman lebih, tingkatkan usaha ke medium.

Daftar periksa migrasi Sonnet 4.6

Perbarui ID model ke claude-sonnet-4-6
BREAKING: Hapus prefilling pesan asisten; gunakan output terstruktur atau output_config.format sebagai gantinya
BREAKING: Verifikasi penanganan parsing JSON parameter alat menangani perbedaan escaping
BREAKING: Perbarui versi alat ke versi terbaru (text_editor_20250728, code_execution_20250825); versi legacy tidak didukung (jika bermigrasi dari 3.x)
BREAKING: Hapus kode apa pun yang menggunakan perintah undo_edit (jika berlaku)
BREAKING: Perbarui parameter sampling untuk menggunakan hanya temperature ATAU top_p, bukan keduanya (jika bermigrasi dari 3.x)

Bermigrasi ke Claude Sonnet 4.5

Claude Sonnet 4.5 menggabungkan kecerdasan yang kuat dengan kinerja cepat, menjadikannya ideal untuk tugas pengkodean, analisis, dan konten sehari-hari.

Untuk gambaran lengkap tentang kemampuan, lihat gambaran umum model.

Harga Sonnet 4.5 adalah $3 per juta token input, $15 per juta token output. Lihat harga Claude untuk detail.

Perbarui nama model Anda:

# Dari Sonnet 4
model = "claude-sonnet-4-20250514"  # Sebelum
model = "claude-sonnet-4-5-20250929"  # Sesudah

# Dari Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Sebelum
model = "claude-sonnet-4-5-20250929"  # Sesudah

Perubahan yang merusak

Perubahan yang merusak ini berlaku saat bermigrasi dari model Claude 3.x Sonnet.

Perbarui parameter sampling

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Gunakan hanya temperature ATAU top_p, bukan keduanya.
Perbarui versi alat

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Perbarui ke versi alat terbaru (text_editor_20250728, code_execution_20250825). Hapus kode apa pun yang menggunakan perintah undo_edit.
Tangani alasan penghentian refusal

Perbarui aplikasi Anda untuk menangani alasan penghentian refusal.

Daftar periksa migrasi Sonnet 4.5

Perbarui ID model ke claude-sonnet-4-5-20250929
BREAKING: Perbarui versi alat ke versi terbaru (text_editor_20250728, code_execution_20250825); versi legacy tidak didukung (jika bermigrasi dari 3.x)
BREAKING: Hapus kode apa pun yang menggunakan perintah undo_edit (jika berlaku)
BREAKING: Perbarui parameter sampling untuk menggunakan hanya temperature ATAU top_p, bukan keduanya (jika bermigrasi dari 3.x)
Tangani alasan penghentian refusal baru di aplikasi Anda
Tinjau dan perbarui prompt mengikuti praktik terbaik prompting

Bermigrasi ke Claude Haiku 4.5

Claude Haiku 4.5 adalah model Haiku tercepat dan paling cerdas dengan kinerja mendekati frontier, memberikan kualitas model premium untuk aplikasi interaktif dan pemrosesan volume tinggi.

Untuk gambaran lengkap tentang kemampuan, lihat gambaran umum model.

Harga Haiku 4.5 adalah $1 per juta token input, $5 per juta token output. Lihat harga Claude untuk detail.

Perbarui nama model Anda:

# Dari Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Sebelum
model = "claude-haiku-4-5-20251001"  # Sesudah

# Dari Haiku 3
model = "claude-3-haiku-20240307"  # Sebelum
model = "claude-haiku-4-5-20251001"  # Sesudah

Tinjau batas laju baru: Haiku 4.5 memiliki batas laju terpisah dari Haiku 3.5 dan Haiku 3. Lihat dokumentasi Batas laju untuk detail.

Untuk peningkatan kinerja yang signifikan pada tugas pengkodean dan penalaran, pertimbangkan untuk mengaktifkan pemikiran yang diperluas dengan thinking: {type: "enabled", budget_tokens: N}.

Pemikiran yang diperluas mempengaruhi efisiensi prompt caching.

Pemikiran yang diperluas sudah usang dalam model Claude 4.6 atau lebih baru. Jika menggunakan model lebih baru, gunakan pemikiran adaptif sebagai gantinya.

Jelajahi kemampuan baru: Lihat gambaran umum model untuk detail tentang kesadaran konteks, kapasitas output yang ditingkatkan (64k token), kecerdasan yang lebih tinggi, dan kecepatan yang ditingkatkan.

Perubahan yang merusak

Perubahan yang merusak ini berlaku saat bermigrasi dari model Claude 3.x Haiku.

Perbarui parameter sampling

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Gunakan hanya temperature ATAU top_p, bukan keduanya.
Perbarui versi alat

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Perbarui ke versi alat terbaru (text_editor_20250728, code_execution_20250825). Hapus kode apa pun yang menggunakan perintah undo_edit.
Tangani alasan penghentian refusal

Perbarui aplikasi Anda untuk menangani alasan penghentian refusal.

Daftar periksa migrasi Haiku 4.5

Perbarui ID model ke claude-haiku-4-5-20251001
BREAKING: Perbarui versi alat ke versi terbaru (text_editor_20250728, code_execution_20250825); versi legacy tidak didukung
BREAKING: Hapus kode apa pun yang menggunakan perintah undo_edit (jika berlaku)
BREAKING: Perbarui parameter sampling untuk menggunakan hanya temperature ATAU top_p, bukan keduanya
Tangani alasan penghentian refusal baru di aplikasi Anda
Tinjau dan sesuaikan untuk batas laju baru (terpisah dari Haiku 3.5)
Tinjau dan perbarui prompt mengikuti

Dapatkan bantuan

Periksa dokumentasi API untuk spesifikasi terperinci
Tinjau kemampuan model untuk perbandingan kinerja
Tinjau catatan rilis API untuk pembaruan API
Hubungi dukungan jika Anda mengalami masalah apa pun selama migrasi

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[...],
)

Perbarui versi tool

Ini adalah perubahan yang merusak saat bermigrasi dari model Claude 3.x.

Perbarui ke versi tool terbaru. Hapus kode apa pun yang menggunakan perintah undo_edit.

# Sebelum
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# Sesudah
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

Text editor: Gunakan text_editor_20250728 dan str_replace_based_edit_tool. Lihat dokumentasi tool text editor untuk detail.
Code execution: Upgrade ke code_execution_20250825. Lihat dokumentasi tool code execution untuk instruksi migrasi.

Tangani alasan stop refusal

Perbarui aplikasi Anda untuk menangani alasan stop refusal:

Python

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Tangani penolakan dengan tepat
    pass

Tangani alasan stop model_context_window_exceeded

Model Claude 4.5+ mengembalikan alasan stop model_context_window_exceeded ketika generasi berhenti karena mencapai batas jendela konteks, bukan batas max_tokens yang diminta. Perbarui aplikasi Anda untuk menangani alasan stop baru ini:

Python

response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # Tangani batas jendela konteks dengan tepat
    pass

interleaved-thinking-2025-05-14

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 8192,
    "output_config": {
        "effort": "low"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64000,
    "thinking": {
        "type": "adaptive"
    },
    "output_config": {
        "effort": "medium"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: interleaved-thinking-2025-05-14" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16384,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16384
    },
    "output_config": {
        "effort": "medium"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: interleaved-thinking-2025-05-14" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 8192,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16384
    },
    "output_config": {
        "effort": "low"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'