Was this page helpful?
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 jangka panjang. 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 terbatas dengan hasil yang menurun, 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 saat konteks percakapan berkembang melampaui ambang batas yang dikonfigurasi. Ini sangat berguna untuk alur kerja agentic dengan penggunaan alat 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. 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 saat 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: Saat 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 caching prompt bervariasi menurut strategi:
Penghapusan hasil alat: Membatalkan prefiks prompt yang di-cache saat 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 menimbulkan biaya penulisan cache setiap kali konten dihapus, tetapi permintaan berikutnya dapat menggunakan kembali prefiks yang baru di-cache.
Penghapusan blok pemikiran: Saat blok pemikiran dipertahankan dalam konteks (tidak dihapus), cache prompt dipertahankan, memungkinkan cache hits dan mengurangi biaya token input. Saat 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 penyimpanan cache prompt 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 menyimpan N putaran terakhir, atau "all" untuk menyimpan 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, menjaga 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 menjaga 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 memory tool. 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 memorinya 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 memori seiring pertumbuhan konteks. Ketika hasil alat dihapus, Claude mempertahankan akses ke informasi tersebut melalui sistem memorinya dan dapat terus bekerja secara efektif.
Untuk menggunakan kedua fitur bersama-sama, aktifkan keduanya dalam permintaan API Anda:
Untuk referensi memory tool lengkap termasuk perintah dan contoh, lihat Memory tool.
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 melebihi ambang batas.
Seiring pertumbuhan percakapan, 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 melebihi 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 kustom 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 kustom untuk kebutuhan khusus 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 web search atau web fetch.
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 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 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:
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" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Search for recent developments in AI"
}
],
"tools": [
{
"type": "web_search_20250305",
"name": "web_search"
}
],
"context_management": {
"edits": [
{"type": "clear_tool_uses_20250919"}
]
}
}'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" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-opus-4-6",
"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
}
],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 3
},
"clear_at_least": {
"type": "input_tokens",
"value": 5000
},
"exclude_tools": ["web_search"]
}
]
}
}'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" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"messages": [{"role": "user", "content": "Hello"}],
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"context_management": {
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
}
]
}
}'ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: Hello
tools:
- type: web_search_20250305
name: web_search
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
YAMLclear_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. |
curl https://api.anthropic.com/v1/messages/count_tokens \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-opus-4-6",
"messages": [
{
"role": "user",
"content": "Continue our conversation..."
}
],
"tools": [],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 5
}
}
]
}
}'ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
messages:
- role: user
content: Hello
tools:
- type: memory_20250818
name: memory
context_management:
edits:
- type: clear_tool_uses_20250919
YAML