Context editing on the Claude API: auto-clear old tool results so long agents stay cheap

Agent chạy lâu trên Claude API có một kiểu "béo phì" đặc trưng: mỗi lần đọc file, tìm kiếm web, query database, kết quả được nối vào lịch sử và đi theo mọi request sau đó. Sau 30 lượt, phần lớn context là output tool cũ mà agent không còn cần, vừa tốn tiền vừa làm model kém tập trung. Context editing là tính năng beta cho phép server tự động xoá các phần đó trước khi prompt tới Claude, trong khi phía client của bạn vẫn giữ nguyên lịch sử đầy đủ. Bài này giải thích hai chiến lược, các tham số và cách phối hợp với prompt caching.

Hai chiến lược

Bật bằng beta header context-management-2025-06-27.

Tham số của chiến lược xoá kết quả tool

• trigger: khi nào bắt đầu xoá; mặc định 100.000 input token (có thể tính theo số lần gọi tool).
• keep: giữ lại bao nhiêu cặp gọi/kết quả gần nhất; mặc định 3.
• clear_at_least: mỗi lần xoá phải bỏ được ít nhất bấy nhiêu token, nếu không thì không xoá (để đáng việc mất cache).
• exclude_tools: tool không bao giờ bị xoá kết quả (ví dụ web search cần trích dẫn).
• clear_tool_inputs: xoá luôn cả tham số gọi tool, mặc định false.

Ví dụ cấu hình

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    tools=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": 30000},
             "keep": {"type": "tool_uses", "value": 3},
             "clear_at_least": {"type": "input_tokens", "value": 5000},
             "exclude_tools": ["web_search"]},
        ]
    },
)

Khi kết hợp hai chiến lược, clear_thinking phải đứng trước. Response trả về context_management.applied_edits cho biết đã xoá bao nhiêu lần gọi tool và bao nhiêu token; endpoint đếm token cũng nhận cấu hình này để bạn ước tính trước.

Phối hợp với prompt caching

• Xoá kết quả tool làm mất cache từ điểm bị sửa. Vì vậy đặt clear_at_least đủ lớn: xoá ít mà mất cache thì lỗ.
• Xoá thinking: giữ thì cache còn, xoá thì cache mất tại điểm xoá.
• Chọn trigger vừa phải: xoá thường xuyên với lượng nhỏ là kiểu tệ nhất về chi phí.

Kết hợp với memory tool

Thêm memory tool (memory_20250818) vào danh sách tools cùng cấu hình context editing: khi context gần ngưỡng xoá, Claude nhận cảnh báo để ghi thông tin quan trọng vào file bộ nhớ trước khi kết quả tool liên quan bị xoá. Agent "quên" chi tiết trong context nhưng vẫn giữ được điều cốt lõi bên ngoài.

Context editing hay compaction?

Tài liệu khuyến nghị với phần lớn hội thoại dài nên dùng server-side compaction (tóm tắt lịch sử). Context editing hợp khi bạn cần kiểm soát chi tiết cái gì bị xoá, ví dụ agent đọc nhiều file lớn mà chỉ cần vài kết quả gần nhất. Tuỳ chọn compaction_control phía client trong SDK đã bị đánh dấu deprecated.

Rủi ro và lưu ý

• Tính năng đang beta; tên type có hậu tố ngày và có thể đổi.
• Agent có thể cần lại kết quả đã xoá và phải gọi tool lần nữa; theo dõi số lần gọi lặp.
• Mặc định giữ thinking khác nhau theo đời model; đặt keep rõ ràng nếu code chạy với nhiều model.

Áp dụng thế nào?

• Dev: Với agent đọc file/tìm kiếm nhiều, bật xoá kết quả tool với keep 3–5 và clear_at_least vài nghìn token; log applied_edits.
• Tech Lead: So chi phí và chất lượng ba phương án: không làm gì, context editing, compaction trên cùng bộ eval trước khi chọn.
• PM: Context editing là "núm" giảm chi phí cho agent chạy lâu mà không cần đổi model; đưa vào danh sách tối ưu chi phí.