This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
Untuk sebagian besar kasus penggunaan, pemadatan sisi server adalah strategi utama untuk mengelola konteks dalam percakapan yang berjalan lama. Strategi di halaman ini berguna untuk skenario spesifik di mana Anda memerlukan kontrol yang lebih halus atas konten apa yang dihapus.
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:
| Pendekatan | Tempat dijalankan | Strategi | Cara kerjanya |
|---|---|---|---|
| Sisi server | API | Penghapusan hasil alat (clear_tool_uses_20250919)Penghapusan blok pemikiran ( clear_thinking_20251015) | Diterapkan sebelum prompt mencapai Claude. Menghapus konten tertentu dari riwayat percakapan. Setiap strategi dapat dikonfigurasi secara independen. |
| Sisi klien | SDK | Pemadatan | Tersedia di Python, TypeScript, dan Ruby SDKs saat menggunakan tool_runner. Menghasilkan ringkasan dan mengganti riwayat percakapan lengkap. Lihat Pemadatan sisi klien di bawah. |
Pengeditan konteks dalam beta dengan dukungan untuk penghapusan hasil alat dan penghapusan blok pemikiran. Untuk mengaktifkannya, gunakan header beta context-management-2025-06-27 dalam permintaan API Anda.
Bagikan umpan balik tentang fitur ini melalui formulir umpan balik.
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.
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.
Perilaku default: Ketika pemikiran yang diperluas diaktifkan tanpa mengonfigurasi strategi clear_thinking_20251015, API secara otomatis menyimpan hanya blok pemikiran dari giliran asisten terakhir (setara dengan keep: {type: "thinking_turns", value: 1}).
Untuk memaksimalkan cache hits, pertahankan semua blok pemikiran dengan mengatur keep: "all".
Giliran percakapan asisten mungkin mencakup beberapa blok konten (misalnya saat menggunakan alat) dan beberapa blok pemikiran (misalnya dengan pemikiran yang disisipi).
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.
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.
Pengeditan konteks tersedia di semua model Claude yang didukung.
Cara paling sederhana untuk mengaktifkan penghapusan hasil alat adalah dengan menentukan hanya jenis strategi. Semua opsi konfigurasi lainnya menggunakan nilai default mereka:
Anda dapat menyesuaikan perilaku penghapusan hasil alat dengan parameter tambahan:
Aktifkan pembersihan blok pemikiran untuk mengelola konteks dan prompt caching secara efektif ketika pemikiran yang diperluas diaktifkan:
Strategi clear_thinking_20251015 mendukung konfigurasi berikut:
| Opsi konfigurasi | Default | Deskripsi |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Menentukan berapa banyak putaran asisten terbaru dengan blok pemikiran yang akan dipertahankan. Gunakan {type: "thinking_turns", value: N} di mana N harus > 0 untuk mempertahankan N putaran terakhir, atau "all" untuk mempertahankan semua blok pemikiran. |
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"
}Anda dapat menggunakan pembersihan blok pemikiran dan pembersihan hasil alat bersama-sama:
Ketika menggunakan beberapa strategi, strategi clear_thinking_20251015 harus didaftar terlebih dahulu dalam array edits.
| Opsi konfigurasi | Default | Deskripsi |
|---|---|---|
trigger | 100.000 token input | Menentukan kapan strategi pengeditan konteks diaktifkan. Setelah prompt melebihi ambang batas ini, pembersihan akan dimulai. Anda dapat menentukan nilai ini dalam input_tokens atau tool_uses. |
keep | 3 penggunaan alat | Menentukan berapa banyak pasangan penggunaan alat/hasil terbaru yang akan dipertahankan setelah pembersihan terjadi. API menghapus interaksi alat tertua terlebih dahulu, mempertahankan yang paling baru. |
clear_at_least | Tidak ada | Memastikan jumlah token minimum dihapus setiap kali strategi diaktifkan. Jika API tidak dapat menghapus setidaknya jumlah yang ditentukan, strategi tidak akan diterapkan. Ini membantu menentukan apakah pembersihan konteks layak memecahkan cache prompt Anda. |
exclude_tools | Tidak ada | Daftar nama alat yang penggunaan alat dan hasilnya tidak boleh pernah dihapus. Berguna untuk mempertahankan konteks penting. |
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": [
// ...
]
}
}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).
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:
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.
Anthropic merekomendasikan pemadatan sisi server daripada pemadatan SDK. Pemadatan sisi server menangani manajemen konteks secara otomatis dengan kompleksitas integrasi yang lebih rendah, perhitungan penggunaan token yang lebih baik, dan tanpa batasan sisi klien. Gunakan pemadatan SDK hanya jika Anda secara khusus memerlukan kontrol sisi klien atas proses perangkuman.
Pemadatan tersedia di Python, TypeScript, dan Ruby SDKs saat menggunakan metode tool_runner.
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.
Ketika pemadatan diaktifkan, SDK memantau penggunaan token setelah setiap respons model:
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.<summary></summary>.Tambahkan compaction_control ke panggilan tool_runner Anda untuk mengaktifkan perangkuman otomatis ketika penggunaan token melampaui ambang batas.
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.
| Parameter | Tipe | Diperlukan | Default | Deskripsi |
|---|---|---|---|---|
enabled | boolean | Ya | - | Apakah akan mengaktifkan pemadatan otomatis |
context_token_threshold | number | Tidak | 100,000 | Jumlah token di mana pemadatan dipicu |
model | string | Tidak | Model yang sama dengan model utama | Model yang digunakan untuk menghasilkan ringkasan |
summary_prompt | string | Tidak | Lihat di bawah | Prompt khusus untuk pembuatan ringkasan |
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}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",
}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 bawaan menginstruksikan Claude untuk membuat ringkasan kelanjutan terstruktur yang mencakup:
Struktur ini memungkinkan Claude untuk melanjutkan pekerjaan secara efisien tanpa kehilangan konteks penting atau mengulangi kesalahan.
Pemadatan memerlukan pertimbangan khusus saat menggunakan alat sisi server seperti pencarian web atau pengambilan web.
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:
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.
Memahami kapan pemadatan dipicu membantu Anda menyetel ambang batas dan memverifikasi perilaku yang diharapkan.
Kasus penggunaan yang baik:
Kasus penggunaan yang kurang ideal:
Was this page helpful?
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[{"role": "user", "content": "Search for recent developments in AI"}],
tools=[{"type": "web_search_20250305", "name": "web_search"}],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Create a simple command line calculator app using Python",
}
],
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000,
},
{"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
# Trigger clearing when threshold is exceeded
"trigger": {"type": "input_tokens", "value": 30000},
# Number of tool uses to keep after clearing
"keep": {"type": "tool_uses", "value": 3},
# Optional: Clear at least this many tokens
"clear_at_least": {"type": "input_tokens", "value": 5000},
# Exclude these tools from being cleared
"exclude_tools": ["web_search"],
}
]
},
)response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
messages=[...],
thinking={"type": "enabled", "budget_tokens": 10000},
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
}
]
},
)response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
messages=[...],
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[...],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
},
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 50000},
"keep": {"type": "tool_uses", "value": 5},
},
]
},
)clear_tool_inputs | false | Mengontrol apakah parameter panggilan alat dihapus bersama dengan hasil alat. Secara default, hanya hasil alat yang dihapus sambil menjaga panggilan alat asli Claude tetap terlihat. |
response = client.beta.messages.count_tokens(
model="claude-opus-4-7",
messages=[{"role": "user", "content": "Continue our conversation..."}],
tools=[...], # Your tool definitions
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 30000},
"keep": {"type": "tool_uses", "value": 5},
}
]
},
)
print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")
print(
f"Savings: {response.context_management['original_input_tokens'] - response.input_tokens} tokens"
)response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[...],
tools=[
{"type": "memory_20250818", "name": "memory"},
# Your other tools
],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)