Pengeditan konteks

Ringkasan

Pengeditan konteks memungkinkan Anda untuk secara selektif menghapus konten tertentu dari riwayat percakapan saat berkembang. Ini membantu Anda mengoptimalkan biaya dan tetap berada dalam batas jendela konteks. Halaman ini mencakup:

• Penghapusan hasil alat - Terbaik untuk alur kerja agentic dengan penggunaan alat 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 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 memproses mereka.

Ketika diaktifkan, API secara otomatis menghapus hasil alat tertua dalam urutan kronologis. Setiap hasil yang dihapus diganti dengan teks placeholder sehingga Claude tahu bahwa hasil tersebut 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 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. Lanjutkan mengelola riwayat percakapan lengkap Anda secara lokal seperti biasanya.

Pengeditan konteks dan caching prompt

Interaksi pengeditan konteks dengan caching prompt bervariasi menurut strategi:

• Penghapusan hasil alat: Membatalkan awalan prompt yang di-cache ketika konten dihapus. Untuk memperhitungkan ini, hapus cukup token untuk membuat pembatalan cache layak dilakukan. 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 awalan 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.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 menentukan hanya jenis strategi. Semua opsi konfigurasi lainnya menggunakan nilai default mereka:

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"}
            ]
        }
    }'

Konfigurasi lanjutan

Anda dapat menyesuaikan perilaku penghapusan hasil alat dengan parameter tambahan:

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"]
                }
            ]
        }
    }'

Penggunaan penghapusan blok pemikiran

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

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": 1024,
        "messages": [...],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

Opsi konfigurasi untuk penghapusan blok pemikiran

Strategi clear_thinking_20251015 mendukung konfigurasi berikut:

Contoh konfigurasi:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Menggabungkan strategi

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

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

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, bersama dengan statistik yang membantu 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 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 untuk melihat pratinjau berapa banyak token yang akan digunakan prompt Anda setelah pengeditan konteks diterapkan.

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
                    }
                }
            ]
        }
    }'

{
    "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 penghapusan apa pun terjadi (original_input_tokens).

Menggunakan dengan Alat Memori

Pengeditan konteks dapat digabungkan dengan alat memori. Ketika konteks percakapan Anda mendekati ambang batas penghapusan yang dikonfigurasi, Claude menerima peringatan otomatis untuk mempertahankan informasi penting. Ini memungkinkan Claude untuk 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 penting dari hasil alat ke file memori sebelum hasil tersebut dihapus
• Mempertahankan alur kerja yang berjalan lama: Aktifkan 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 memori saat diperlukan, daripada menyimpan semuanya dalam 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 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:

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

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 yang berjalan lama 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 mana ia tinggalkan.

Menggunakan pemadatan

Tambahkan compaction_control ke panggilan tool_runner Anda:

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

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

final = runner.until_done()

Apa yang terjadi selama pemadatan

Saat 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 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.

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 kustom

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 default

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

1. Gambaran Umum Tugas: Permintaan inti pengguna, kriteria kesuksesan, dan batasan.
2. Status Saat Ini: Apa yang telah diselesaikan, 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, penghalang, dan urutan prioritas.
5. Konteks untuk Dipertahankan: Preferensi pengguna, detail khusus 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 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 akumulatif 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 alternatif:

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

Kasus tepi penggunaan alat

Ketika pemadatan dipicu saat respons penggunaan alat 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 pemadatan

Aktifkan pencatatan untuk melacak kapan pemadatan terjadi:

import logging

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

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

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 ingatan presisi tentang detail percakapan awal
• Alur kerja menggunakan alat sisi server secara ekstensif
• Tugas yang perlu mempertahankan status yang tepat di banyak variabel