Pengeditan konteks

Ikhtisar

Pengeditan konteks memungkinkan Anda menghapus konten tertentu secara selektif dari riwayat percakapan saat berkembang. Selain mengoptimalkan biaya dan tetap dalam batas, ini tentang secara aktif mengkurasi apa yang dilihat Claude: konteks adalah sumber daya terbatas dengan hasil yang semakin berkurang, dan konten yang tidak relevan menurunkan fokus model. Pengeditan konteks memberi Anda kontrol runtime yang terperinci atas kurasi tersebut. Untuk prinsip-prinsip yang lebih luas di balik manajemen konteks, lihat Rekayasa konteks yang efektif. Halaman ini mencakup:

• Penghapusan hasil alat - Terbaik untuk alur kerja agentik dengan penggunaan alat yang berat di mana hasil alat lama tidak lagi diperlukan
• Penghapusan blok pemikiran - Untuk mengelola blok pemikiran saat menggunakan pemikiran yang diperluas, dengan opsi untuk mempertahankan pemikiran terbaru untuk kesinambungan konteks
• Kompaksi sisi klien SDK - Alternatif berbasis SDK untuk manajemen konteks berbasis ringkasan (kompaksi sisi server umumnya lebih disukai)

Strategi sisi server

Penghapusan hasil alat

Strategi clear_tool_uses_20250919 menghapus hasil alat ketika konteks percakapan tumbuh melampaui ambang batas yang Anda konfigurasi. Ini sangat berguna untuk alur kerja agentik dengan penggunaan alat yang berat. Hasil alat yang lebih lama (seperti konten file atau hasil pencarian) tidak lagi diperlukan setelah Claude memprosesnya.

Saat diaktifkan, API secara otomatis menghapus hasil alat tertua dalam urutan kronologis. Setiap hasil yang dihapus digantikan dengan teks placeholder sehingga Claude mengetahui bahwa itu telah dihapus. Secara default, hanya hasil alat yang dihapus. Anda dapat secara opsional menghapus hasil alat dan panggilan alat (parameter penggunaan alat) dengan mengatur clear_tool_inputs ke true.

Penghapusan blok pemikiran

Strategi clear_thinking_20251015 mengelola blok thinking dalam percakapan ketika pemikiran yang diperluas diaktifkan. Strategi ini memberi Anda kontrol atas pelestarian pemikiran: Anda dapat memilih untuk menyimpan lebih banyak blok pemikiran untuk mempertahankan kesinambungan penalaran, atau menghapusnya lebih agresif untuk menghemat ruang konteks.

Giliran percakapan asisten dapat mencakup beberapa blok konten (misalnya saat menggunakan alat) dan beberapa blok pemikiran (misalnya dengan pemikiran yang diselingi).

Pengeditan konteks terjadi di sisi server

Pengeditan konteks diterapkan di sisi server sebelum prompt mencapai Claude. Aplikasi klien Anda mempertahankan riwayat percakapan penuh yang tidak dimodifikasi. Anda tidak perlu menyinkronkan status klien Anda dengan versi yang telah diedit. Terus kelola riwayat percakapan penuh Anda secara lokal seperti biasa.

Pengeditan konteks dan caching prompt

Interaksi pengeditan konteks dengan caching prompt bervariasi berdasarkan strategi:

• Penghapusan hasil alat: Membatalkan prefiks prompt yang di-cache ketika konten dihapus. Untuk mengatasinya, hapus cukup token agar pembatalan cache sepadan. Gunakan parameter clear_at_least untuk memastikan jumlah minimum token dihapus setiap kali. Anda akan dikenakan biaya penulisan cache setiap kali konten dihapus, tetapi permintaan berikutnya dapat menggunakan kembali prefiks yang baru di-cache.

• Penghapusan blok pemikiran: Ketika blok pemikiran disimpan dalam konteks (tidak dihapus), cache prompt dipertahankan, memungkinkan cache hits dan mengurangi biaya token input. Ketika blok pemikiran dihapus, cache dibatalkan pada titik di mana penghapusan terjadi. Konfigurasikan parameter keep berdasarkan apakah Anda ingin memprioritaskan kinerja cache atau ketersediaan jendela konteks.

Model yang didukung

Pengeditan konteks tersedia di:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Penggunaan penghapusan hasil alat

Cara paling sederhana untuk mengaktifkan penghapusan hasil alat adalah dengan hanya menentukan jenis strategi. Semua opsi konfigurasi lainnya menggunakan nilai defaultnya:

Konfigurasi lanjutan

Anda dapat menyesuaikan perilaku penghapusan hasil alat dengan parameter tambahan:

Penggunaan penghapusan blok pemikiran

Aktifkan penghapusan blok pemikiran untuk mengelola konteks dan caching prompt secara efektif ketika pemikiran yang diperluas diaktifkan:

Opsi konfigurasi untuk penghapusan blok pemikiran

Strategi clear_thinking_20251015 mendukung konfigurasi berikut:

Contoh konfigurasi:

Simpan blok pemikiran dari 3 giliran asisten terakhir:

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

Simpan semua blok pemikiran (memaksimalkan cache hits):

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Menggabungkan strategi

Anda dapat menggunakan penghapusan blok pemikiran dan penghapusan hasil alat secara bersamaan:

Opsi konfigurasi untuk penghapusan hasil alat

Respons pengeditan konteks

Anda dapat melihat pengeditan konteks mana yang diterapkan pada permintaan Anda menggunakan bidang respons context_management, bersama dengan statistik berguna tentang konten dan token input yang dihapus.

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // Saat menggunakan `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // Saat menggunakan `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

Untuk respons streaming, pengeditan konteks akan disertakan dalam event message_delta terakhir:

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Penghitungan token

Endpoint penghitungan token mendukung manajemen konteks, memungkinkan Anda melihat pratinjau berapa banyak token yang akan digunakan prompt Anda setelah pengeditan konteks diterapkan.

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

Respons menampilkan jumlah token akhir setelah manajemen konteks diterapkan (input_tokens) dan jumlah token asli sebelum penghapusan terjadi (original_input_tokens).

Menggunakan dengan Alat Memori

Pengeditan konteks dapat dikombinasikan dengan alat memori. Ketika konteks percakapan Anda mendekati ambang batas penghapusan yang dikonfigurasi, Claude menerima peringatan otomatis untuk menyimpan informasi penting. Ini memungkinkan Claude menyimpan hasil alat atau konteks ke file memorinya sebelum dihapus dari riwayat percakapan.

Kombinasi ini memungkinkan Anda untuk:

• Menyimpan konteks penting: Claude dapat menulis informasi penting dari hasil alat ke file memori sebelum hasil tersebut dihapus
• Mempertahankan alur kerja yang berjalan lama: Mengaktifkan alur kerja agentik yang sebaliknya akan melampaui batas konteks dengan memindahkan informasi ke penyimpanan persisten
• Mengakses informasi sesuai kebutuhan: Claude dapat mencari informasi yang sebelumnya dihapus dari file memori saat diperlukan, daripada menyimpan semuanya di jendela konteks aktif

Misalnya, dalam alur kerja pengeditan file di mana Claude melakukan banyak operasi, Claude dapat merangkum perubahan yang telah selesai ke file memori saat konteks berkembang. Ketika hasil alat dihapus, Claude tetap memiliki akses ke informasi tersebut melalui sistem memorinya dan dapat terus bekerja secara efektif.

Untuk menggunakan kedua fitur bersama, aktifkan keduanya dalam permintaan API Anda:

Kompaksi sisi klien (SDK)

Kompaksi adalah fitur SDK yang secara otomatis mengelola konteks percakapan dengan menghasilkan ringkasan ketika penggunaan token tumbuh terlalu besar. Tidak seperti strategi pengeditan konteks sisi server yang menghapus konten, kompaksi menginstruksikan Claude untuk meringkas riwayat percakapan, kemudian mengganti riwayat penuh dengan ringkasan tersebut. Ini memungkinkan Claude untuk terus mengerjakan tugas yang berjalan lama yang sebaliknya akan melampaui jendela konteks.

Cara kerja kompaksi

Ketika kompaksi diaktifkan, SDK memantau penggunaan token setelah setiap respons model:

1. Pemeriksaan ambang batas: SDK menghitung total token sebagai input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Pembuatan ringkasan: Ketika ambang batas terlampaui, prompt ringkasan disuntikkan sebagai giliran pengguna, dan Claude menghasilkan ringkasan terstruktur yang dibungkus dalam tag <summary></summary>.
3. Penggantian konteks: SDK mengekstrak ringkasan dan mengganti seluruh riwayat pesan dengannya.
4. Kelanjutan: Percakapan dilanjutkan dari ringkasan, dengan Claude melanjutkan dari tempat terakhir berhenti.

Menggunakan kompaksi

Tambahkan compaction_control ke panggilan tool_runner Anda:

Apa yang terjadi selama kompaksi

Saat percakapan berkembang, riwayat pesan terakumulasi:

Sebelum kompaksi (mendekati 100k token):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 pertukaran lagi seperti ini ...
]

Ketika token melampaui ambang batas, SDK menyuntikkan permintaan ringkasan dan Claude menghasilkan ringkasan. Seluruh riwayat kemudian digantikan:

Setelah kompaksi (kembali ke ~2-3k token):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude melanjutkan bekerja dari ringkasan ini seolah-olah itu adalah riwayat percakapan asli.

Opsi konfigurasi

Memilih ambang batas token

Ambang batas menentukan kapan kompaksi terjadi. Ambang batas yang lebih rendah berarti kompaksi lebih sering dengan jendela konteks yang lebih kecil. Ambang batas yang lebih tinggi memungkinkan lebih banyak konteks tetapi berisiko mencapai batas.

# Kompaksi lebih sering untuk skenario dengan memori terbatas
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Kompaksi lebih jarang ketika Anda membutuhkan lebih banyak konteks
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Menggunakan model berbeda untuk ringkasan

Anda dapat menggunakan model yang lebih cepat atau lebih murah untuk menghasilkan ringkasan:

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

Prompt ringkasan kustom

Anda dapat menyediakan prompt kustom untuk kebutuhan domain tertentu. Prompt Anda harus menginstruksikan Claude untuk membungkus ringkasannya dalam tag <summary></summary>.

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Rangkum penelitian yang telah dilakukan sejauh ini, termasuk:
- Sumber yang dikonsultasikan dan temuan utama
- Pertanyaan yang dijawab dan hal yang belum diketahui
- Langkah selanjutnya yang direkomendasikan

Bungkus ringkasan Anda dalam tag <summary></summary>.""",
}

Prompt ringkasan default

Prompt ringkasan bawaan menginstruksikan Claude untuk membuat ringkasan kelanjutan terstruktur yang mencakup:

1. Ikhtisar Tugas: Permintaan inti pengguna, kriteria keberhasilan, dan batasan.
2. Status Saat Ini: Apa yang telah diselesaikan, file yang dimodifikasi, dan artefak yang dihasilkan.
3. Temuan Penting: Batasan teknis, keputusan yang dibuat, kesalahan yang diselesaikan, dan pendekatan yang gagal.
4. Langkah Selanjutnya: Tindakan spesifik yang diperlukan, pemblokir, dan urutan prioritas.
5. Konteks yang Perlu Dipertahankan: Preferensi pengguna, detail spesifik domain, dan komitmen yang dibuat.

Struktur ini memungkinkan Claude untuk melanjutkan pekerjaan secara efisien tanpa kehilangan konteks penting atau mengulangi kesalahan.

Keterbatasan

Alat sisi server

Saat menggunakan alat sisi server, SDK mungkin salah menghitung penggunaan token, menyebabkan kompaksi dipicu pada waktu yang salah.

Misalnya, setelah operasi pencarian web, respons API mungkin menampilkan:

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK menghitung total penggunaan sebagai 63.000 + 270.000 = 333.000 token. Namun, nilai cache_read_input_tokens mencakup pembacaan yang terakumulasi dari beberapa panggilan API internal yang dibuat oleh alat sisi server, bukan konteks percakapan aktual Anda. Panjang konteks nyata Anda mungkin hanya 63.000 input_tokens, tetapi SDK melihat 333k dan memicu kompaksi secara prematur.

Solusi alternatif:

• Gunakan endpoint penghitungan token untuk mendapatkan panjang konteks yang akurat
• Hindari kompaksi saat menggunakan alat sisi server secara ekstensif

Kasus tepi penggunaan alat

Ketika kompaksi dipicu sementara respons penggunaan alat sedang tertunda, SDK menghapus blok penggunaan alat dari riwayat pesan sebelum menghasilkan ringkasan. Claude akan mengeluarkan kembali panggilan alat setelah melanjutkan dari ringkasan jika masih diperlukan.

Memantau kompaksi

Aktifkan logging untuk melacak kapan kompaksi terjadi:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Log akan menampilkan:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

Kapan menggunakan kompaksi

Kasus penggunaan yang baik:

• Tugas agen yang berjalan lama yang memproses banyak file atau sumber data
• Alur kerja penelitian yang mengakumulasi sejumlah besar informasi
• Tugas multi-langkah dengan kemajuan yang jelas dan terukur
• Tugas yang menghasilkan artefak (file, laporan) yang bertahan di luar percakapan

Kasus penggunaan yang kurang ideal:

• Tugas yang memerlukan pengingatan tepat dari detail percakapan awal
• Alur kerja yang menggunakan alat sisi server secara ekstensif
• Tugas yang perlu mempertahankan status tepat di banyak variabel