Compaction trong Claude API: để Claude tự tóm tắt khi agent chạy dài

Agent chạy càng lâu, lịch sử hội thoại càng dài: tốn token mỗi lượt, chậm hơn, và chất lượng giảm khi context phình to. Trước đây bạn phải tự viết code tóm tắt rồi thay lịch sử. Claude API giờ có compaction phía server: Claude tự viết bản tóm tắt các lượt cũ trên server, bạn không cần code tóm tắt riêng. Đây là cách giữ agent dài hơi trong cửa sổ context mà tiền token không tăng mãi.

Hai kiểu compaction

Tài liệu khuyên dùng compaction theo yêu cầu ở nơi nó khả dụng vì linh hoạt hơn. Nhưng kiểu theo ngưỡng là cách nhanh nhất để bắt đầu.

Compaction theo ngưỡng: một tham số

{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "messages": [...],
  "context_management": {
    "edits": [{
      "type": "compact_20260112",
      "trigger": {"type": "input_tokens", "value": 150000},
      "instructions": "Giữ lại quyết định thiết kế, file đã sửa và việc còn dang dở."
    }]
  }
}

• trigger mặc định 150.000 token input, tối thiểu 50.000.
• instructions thay thế hoàn toàn prompt tóm tắt mặc định, không bổ sung vào.
• pause_after_compaction: true trả về với stop_reason: "compaction" để bạn chỉnh message (ví dụ chèn lại vài lượt gần nhất) trước khi tiếp tục.

Khi kích hoạt, response bắt đầu bằng khối {"type": "compaction", "content": "..."}. Bạn nối nguyên response vào messages như bình thường; API bỏ qua mọi thứ trước khối compaction cuối cùng.

Tính chi phí đúng

"usage": {
  "input_tokens": 23000, "output_tokens": 1000,
  "iterations": [
    {"type": "compaction", "input_tokens": 180000, "output_tokens": 3500},
    {"type": "message", "input_tokens": 23000, "output_tokens": 1000}
  ]
}

Số input_tokens/output_tokens ở cấp trên không gồm lượt compaction. Muốn biết tổng bị tính tiền, cộng mọi mục trong usage.iterations. Gửi lại một khối compaction cũ không tốn thêm phí compaction.

Kết hợp với prompt caching

• Đặt breakpoint cache_control ở cuối system prompt: khi compaction xảy ra, cache system prompt vẫn còn, chỉ bản tóm tắt mới phải ghi cache.
• Có thể gắn cache_control vào chính khối compaction để cache bản tóm tắt.

Compaction hay context editing?

Context editing xoá kết quả tool cũ hoặc thinking cũ theo quy tắc, không tóm tắt. Compaction tóm tắt toàn bộ phần cũ. Agent có nhiều kết quả tool cồng kềnh nhưng ít cần nhớ thì context editing đủ; hội thoại dài cần giữ mạch quyết định thì dùng compaction.

Rủi ro và lưu ý

• Tóm tắt làm mất chi tiết: thứ không vào bản tóm tắt là mất. Viết instructions riêng liệt kê những gì bắt buộc giữ.
• Lỗi serialize với SDK Python: tài liệu cảnh báo dùng model_dump() thường trên block có thể gây lỗi 400; dùng to_dict() hoặc model_dump(exclude_none=True).
• Thinking blocks: với model có preserved thinking, kiểu theo ngưỡng không giữ thinking của các lượt chèn lại; xem trang hướng dẫn riêng.
• Đang ở beta: tên tham số, header có thể thay đổi; ghim phiên bản và theo dõi changelog.

Áp dụng thế nào?

• Dev: Thêm tham số compaction theo ngưỡng vào agent dài hơi; log usage.iterations để thấy chi phí thật.
• Tech Lead: Viết instructions tóm tắt theo nghiệp vụ và kiểm thử bằng eval: sau compaction agent còn hoàn thành task không.
• PM: Compaction mở đường cho agent chạy nhiều giờ; ước lượng chi phí theo số lần compaction, không chỉ theo số lượt.