Pengeditan konteks

Ikhtisar

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

• Penghapusan hasil alat - Terbaik untuk alur kerja agentic 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 kontinuitas konteks
• Pemadatan SDK sisi klien - Alternatif berbasis SDK untuk manajemen konteks berbasis ringkasan (pemadatan 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 dikonfigurasi. Ini sangat berguna untuk alur kerja agentic dengan penggunaan alat yang berat. Hasil alat yang lebih lama (seperti konten file atau hasil pencarian) tidak lagi diperlukan setelah Claude memprosesnya.

Ketika diaktifkan, API secara otomatis menghapus hasil alat tertua dalam urutan kronologis. API mengganti setiap hasil yang dihapus dengan teks placeholder sehingga Claude tahu itu telah dihapus. Secara default, hanya hasil alat yang dihapus. Anda dapat secara opsional menghapus baik hasil alat maupun 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 kontinuitas penalaran, atau menghapusnya lebih agresif untuk menghemat ruang konteks.

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

Pengeditan konteks terjadi sisi server

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

Pengeditan konteks dan caching prompt

Interaksi pengeditan konteks dengan prompt caching bervariasi menurut strategi:

• Penghapusan hasil alat: Membatalkan prefix prompt yang di-cache ketika konten dihapus. Untuk memperhitungkan ini, hapus cukup token untuk membuat pembatalan cache layak. Gunakan parameter clear_at_least untuk memastikan jumlah token minimum dihapus setiap kali. Anda akan dikenakan biaya penulisan cache setiap kali konten dihapus, tetapi permintaan berikutnya dapat menggunakan kembali prefix 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 semua model Claude yang didukung.

Penggunaan penghapusan hasil alat

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

Konfigurasi lanjutan

Anda dapat menyesuaikan perilaku penghapusan hasil alat dengan parameter tambahan:

Penggunaan pembersihan blok pemikiran

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

Opsi konfigurasi untuk pembersihan blok pemikiran

Strategi clear_thinking_20251015 mendukung konfigurasi berikut:

Contoh konfigurasi:

Pertahankan blok pemikiran dari 3 putaran asisten terakhir:

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

Pertahankan semua blok pemikiran (memaksimalkan cache hits):

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

Menggabungkan strategi

Anda dapat menggunakan pembersihan blok pemikiran dan pembersihan hasil alat bersama-sama:

Opsi konfigurasi untuk pembersihan 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": [
      // Ketika menggunakan `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // Ketika 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 acara message_delta terakhir:

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

Penghitungan token

Titik akhir 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 menunjukkan baik jumlah token akhir setelah manajemen konteks diterapkan (input_tokens) dan jumlah token asli sebelum pembersihan apa pun terjadi (original_input_tokens).

Menggunakan dengan Alat Memory

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

Kombinasi ini memungkinkan Anda untuk:

• Menyimpan konteks penting: Claude dapat menulis informasi penting dari hasil alat ke file memory sebelum hasil tersebut dihapus
• Mempertahankan alur kerja jangka panjang: Mengaktifkan alur kerja agentic yang sebaliknya akan melampaui batas konteks dengan memindahkan informasi ke penyimpanan persisten
• Mengakses informasi sesuai permintaan: Claude dapat mencari informasi yang sebelumnya dihapus dari file memory 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 selesai ke file memory saat konteks berkembang. Ketika hasil alat dihapus, Claude mempertahankan akses ke informasi tersebut melalui sistem memory dan dapat terus bekerja secara efektif.

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

Untuk referensi alat memory lengkap termasuk perintah dan contoh, lihat Alat Memory.

Pemadatan sisi klien (SDK)

Pemadatan 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, pemadatan menginstruksikan Claude untuk merangkum riwayat percakapan, kemudian mengganti riwayat lengkap dengan ringkasan tersebut. Ini memungkinkan Claude untuk terus bekerja pada tugas jangka panjang yang sebaliknya akan melampaui jendela konteks.

Cara kerja pemadatan

Ketika pemadatan 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 ia berhenti.

Menggunakan pemadatan

Tambahkan compaction_control ke panggilan tool_runner Anda untuk mengaktifkan perangkuman otomatis ketika penggunaan token melampaui ambang batas.

Apa yang terjadi selama pemadatan

Seiring percakapan berkembang, riwayat pesan terakumulasi:

Sebelum pemadatan (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 more exchanges like this ...
]

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

Setelah pemadatan (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 pemadatan terjadi. Ambang batas yang lebih rendah berarti pemadatan yang lebih sering dengan jendela konteks yang lebih kecil. Ambang batas yang lebih tinggi memungkinkan lebih banyak konteks tetapi berisiko mencapai batas.

# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Less frequent compaction when you need more context
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 khusus

Anda dapat memberikan prompt khusus untuk kebutuhan spesifik domain. Prompt Anda harus menginstruksikan Claude untuk membungkus ringkasannya dalam tag <summary></summary>.

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

Prompt ringkasan default

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

1. Ikhtisar Tugas: Permintaan inti pengguna, kriteria kesuksesan, dan batasan.
2. Status Saat Ini: Apa yang telah selesai, file yang dimodifikasi, dan artefak yang dihasilkan.
3. Penemuan Penting: Batasan teknis, keputusan yang dibuat, kesalahan yang diselesaikan, dan pendekatan yang gagal.
4. Langkah Berikutnya: Tindakan spesifik yang diperlukan, pemblokir, dan urutan prioritas.
5. Konteks untuk 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.

Batasan

Alat sisi server

Saat menggunakan alat sisi server, SDK mungkin menghitung penggunaan token secara tidak benar, menyebabkan pemadatan dipicu pada waktu yang salah.

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

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

SDK menghitung penggunaan total sebagai 63.000 + 270.000 = 333.000 token. Namun, nilai cache_read_input_tokens mencakup pembacaan 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 pemadatan secara prematur.

Solusi:

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

Kasus tepi penggunaan alat

Ketika SDK memicu pemadatan saat respons penggunaan alat tertunda, ia menghapus blok penggunaan alat dari riwayat pesan sebelum menghasilkan ringkasan. Claude akan mengeluarkan kembali panggilan alat setelah melanjutkan dari ringkasan jika masih diperlukan.

Memantau pemadatan

Memahami kapan pemadatan dipicu membantu Anda menyetel ambang batas dan memverifikasi perilaku yang diharapkan.

Kapan menggunakan pemadatan

Kasus penggunaan yang baik:

• Tugas agen jangka panjang yang memproses banyak file atau sumber data
• Alur kerja penelitian yang mengumpulkan 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 recall presisi dari detail percakapan awal
• Alur kerja menggunakan alat sisi server secara ekstensif
• Tugas yang perlu mempertahankan status yang tepat di banyak variabel