Pengeditan konteks



Ikhtisar

Pengeditan konteks memungkinkan Anda menghapus konten tertentu secara selektif dari riwayat percakapan seiring pertumbuhannya. Selain mengoptimalkan biaya dan tetap berada dalam batas, ini tentang mengkurasi secara aktif 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 yang lebih luas di balik manajemen konteks, lihat Effective context engineering. Halaman ini mencakup:

• Penghapusan hasil alat - Paling cocok untuk alur kerja agentic dengan penggunaan alat yang intensif di mana hasil alat lama tidak lagi diperlukan
• Penghapusan blok thinking - Untuk mengelola blok thinking saat menggunakan pemikiran diperpanjang, dengan opsi untuk mempertahankan thinking terbaru demi kontinuitas konteks
• Compaction SDK sisi klien - Alternatif berbasis SDK untuk manajemen konteks berbasis ringkasan (compaction sisi server umumnya lebih disarankan)



Strategi sisi server



Penghapusan hasil alat

Strategi clear_tool_uses_20250919 menghapus hasil alat ketika konteks percakapan tumbuh melampaui ambang batas yang Anda konfigurasikan. Ini sangat berguna untuk alur kerja agentic dengan penggunaan alat yang intensif. Hasil alat yang lebih lama (seperti isi 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 mengetahui bahwa hasil tersebut telah dihapus. Secara default, hanya hasil alat yang dihapus. Anda dapat secara opsional menghapus hasil alat sekaligus panggilan alat (parameter penggunaan alat) dengan mengatur clear_tool_inputs ke true.



Penghapusan blok thinking

Strategi clear_thinking_20251015 mengelola blok thinking dalam percakapan saat pemikiran diperpanjang diaktifkan. Strategi ini memberi Anda kontrol atas preservasi thinking: Anda dapat memilih untuk mempertahankan lebih banyak blok thinking guna menjaga kontinuitas penalaran, atau menghapusnya secara lebih agresif untuk menghemat ruang konteks.

Satu giliran percakapan asisten dapat mencakup beberapa blok konten (misalnya, saat menggunakan alat) dan beberapa blok thinking (misalnya, dengan interleaved thinking).



Pengeditan konteks terjadi di sisi server

Pengeditan konteks diterapkan di sisi server sebelum prompt mencapai Claude. Aplikasi klien Anda mempertahankan riwayat percakapan lengkap yang tidak dimodifikasi. Anda tidak perlu menyinkronkan state klien Anda dengan versi yang telah diedit. Lanjutkan mengelola riwayat percakapan lengkap 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 mengatasi hal ini, hapus token dalam jumlah yang cukup agar pembatalan cache tersebut 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 thinking: Ketika blok thinking dipertahankan dalam konteks (tidak dihapus), cache prompt tetap terjaga, memungkinkan cache hit dan mengurangi biaya token input. Ketika blok thinking dihapus, cache dibatalkan pada titik di mana penghapusan terjadi. Konfigurasikan parameter keep berdasarkan apakah Anda ingin memprioritaskan performa 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 hanya menentukan tipe strategi. Semua opsi konfigurasi lainnya menggunakan nilai default:

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}]},
)



Konfigurasi lanjutan

Anda dapat menyesuaikan perilaku penghapusan hasil alat dengan parameter tambahan:

response = client.beta.messages.create(
    model="claude-opus-5",
    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",
                # Picu pembersihan ketika ambang batas terlampaui
                "trigger": {"type": "input_tokens", "value": 30000},
                # Jumlah penggunaan alat yang dipertahankan setelah pembersihan
                "keep": {"type": "tool_uses", "value": 3},
                # Opsional: Bersihkan setidaknya sejumlah token ini
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Kecualikan alat-alat ini dari pembersihan
                "exclude_tools": ["web_search"],
            }
        ]
    },
)



Penggunaan penghapusan blok thinking

Aktifkan penghapusan blok thinking untuk mengelola konteks dan caching prompt secara efektif saat pemikiran diperpanjang diaktifkan:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)



Opsi konfigurasi untuk penghapusan blok thinking

Strategi clear_thinking_20251015 mendukung konfigurasi berikut:

Contoh konfigurasi:

Pertahankan blok thinking dari 3 giliran asisten terakhir:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

Pertahankan semua blok thinking (memaksimalkan cache hit):

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)



Menggabungkan strategi

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    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},
            },
        ]
    },
)

print(response)



Opsi konfigurasi untuk penghapusan hasil alat



Respons pengeditan konteks

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

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

Untuk respons streaming, pengeditan konteks 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.

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    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"
)

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

Respons menunjukkan jumlah token akhir setelah manajemen konteks diterapkan (input_tokens) dan jumlah token asli sebelum penghapusan apa pun 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:

• Mempertahankan konteks penting: Claude dapat menulis informasi esensial dari hasil alat ke file memori sebelum hasil tersebut dihapus
• Menjaga alur kerja yang berjalan lama: Memungkinkan alur kerja agentic yang seharusnya melebihi 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 seiring pertumbuhan konteks. Ketika hasil alat dihapus, Claude tetap memiliki akses ke informasi tersebut melalui sistem memorinya dan dapat terus bekerja secara efektif.

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

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



Compaction sisi klien (SDK)

Compaction 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, compaction menginstruksikan Claude untuk merangkum riwayat percakapan, lalu mengganti seluruh riwayat dengan ringkasan tersebut. Ini memungkinkan Claude untuk terus mengerjakan tugas yang berjalan lama yang seharusnya melebihi jendela konteks.



Cara kerja compaction

Saat compaction 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 disisipkan 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 titik terakhir.



Menggunakan compaction

Tambahkan compaction_control ke panggilan tool_runner Anda untuk mengaktifkan peringkasan otomatis ketika penggunaan token melebihi ambang batas.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Apa yang terjadi selama compaction

Seiring pertumbuhan percakapan, riwayat pesan terakumulasi:

Sebelum compaction (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 menyisipkan permintaan ringkasan dan Claude menghasilkan ringkasan. Seluruh riwayat kemudian diganti:

Setelah compaction (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 pekerjaan dari ringkasan ini seolah-olah itu adalah riwayat percakapan asli.



Opsi konfigurasi



Memilih ambang batas token

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

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # Nilai lebih rendah memadatkan lebih sering; naikkan ke 150000 jika tugas butuh lebih banyak konteks
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Menggunakan model berbeda untuk ringkasan

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

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Prompt ringkasan kustom

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

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    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.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Prompt ringkasan default

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

1. Task Overview: Permintaan inti pengguna, kriteria keberhasilan, dan batasan.
2. Current State: Apa yang telah diselesaikan, file yang dimodifikasi, dan artefak yang dihasilkan.
3. Important Discoveries: Batasan teknis, keputusan yang dibuat, error yang diselesaikan, dan pendekatan yang gagal.
4. Next Steps: Tindakan spesifik yang diperlukan, hambatan, dan urutan prioritas.
5. Context to Preserve: Preferensi pengguna, detail spesifik domain, dan komitmen yang dibuat.

Struktur ini memungkinkan Claude 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 compaction terpicu pada waktu yang salah.

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

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

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

Solusi alternatif:

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



Kasus khusus penggunaan alat

Ketika SDK memicu compaction saat respons penggunaan alat masih 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 compaction

Memahami kapan compaction terpicu membantu Anda menyesuaikan ambang batas dan memverifikasi perilaku yang diharapkan.

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 compaction

Kasus penggunaan yang cocok:

• Tugas agen yang berjalan lama yang memproses banyak file atau sumber data
• Alur kerja riset yang mengakumulasi informasi dalam jumlah besar
• 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 presisi atas detail percakapan awal
• Alur kerja yang menggunakan alat sisi server secara ekstensif
• Tugas yang perlu mempertahankan state yang tepat di banyak variabel



Langkah selanjutnya