AI 기술 설명 – 컴팩션 온디맨드(Compaction on Demand) – 긴 대화를 서버가 요약해 주는 Claude API 기능
컴팩션 온디맨드(Compaction on Demand)는 Claude API에서 앱이 정한 시점에 긴 대화의 앞부분을 서버가 요약 블록 하나로 바꿔 주는 기능입니다. 컴팩션 개요 문서는 오래된 턴을 Claude가 서버에서 쓴 요약으로 대체하기 때문에 직접 요약 코드를 짤 필요가 없다고 설명해요. 대화가 길어질수록 응답 품질이 떨어지니 활성 컨텍스트를 작게 유지하는 목적도 있다고 적습니다.
릴리스 노트에 따르면 컴팩션 온디맨드는 2026년 9월 14일에 compact-2026-09-04 베타 헤더와 함께 공개됐어요. 언제 요약할지를 앱이 고르고, 요약 요청을 백그라운드로 돌릴 수 있고, 최근 턴을 원문 그대로 남길 수 있다는 점이 그 항목의 요지입니다. 이 글은 컨텍스트 엔지니어링 글에서 다룬 “AI가 읽는 양을 설계하는 방법”과 이어지는 주제로, 요약을 서버에 맡기는 방법과 그 한계만 따로 정리했습니다.
컴팩션 온디맨드는 요약 요청 한 번으로 시작한다
컴팩션 온디맨드 문서에 따르면 요약 요청은 대화 턴과 별개의 요청입니다. 지금까지의 대화에 compaction 매개변수를 붙여 보내면 API가 요청 안의 모든 메시지를 한 번 요약하고, 답변은 만들지 않고, stop_reason이 "compaction"인 응답에 블록 하나만 담아 돌려줘요. 블록에는 읽을 수 있는 요약 텍스트와 서명(signature)이 들어 있습니다.
# 문서의 Python 예제에서 요청 호출 부분만 가져온 코드입니다
response = client.beta.messages.create(
model="claude-opus-5-5",
# max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
max_tokens=4096,
betas=["compact-2026-09-04"],
messages=history,
compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")max_tokens는 넉넉하게
문서의 주석대로 max_tokens는 생각(thinking) 과정을 포함한 호출 전체의 상한이라서 수천 토큰을 주라고 합니다. 요약 호출은 요청에 쓴 모델, system, tools, 생각 설정을 그대로 쓰므로 대화의 나머지에 쓰는 system과 tools를 똑같이 보내라는 안내도 있어요.
요약된 메시지를 지우고 블록을 맨 앞에 둔다
응답을 받으면 기록에서 보낸 메시지를 지우고 돌려받은 블록으로 바꿉니다. 블록은 messages 맨 앞에 두고, 이후 요청마다 베타 헤더와 함께 보내요. 블록은 서명까지 받은 그대로 보내야 하며, 고치면 400 오류(compaction_signature_invalid 또는 compaction_content_mismatch)가 납니다. 요청마다 블록은 하나만 보낼 수 있고, 이미 블록으로 시작하는 대화가 다시 길어지면 compaction을 한 번 더 보내 새 블록이 옛 요약과 그 뒤를 함께 요약하게 합니다.
오류가 나지 않는 실수 두 가지
문서가 꼽은 실수는 요약된 메시지를 블록 뒤에 남겨 두는 것과, 이후 요청에서 블록을 빼먹는 것입니다. 첫 번째는 API가 그 메시지를 Claude에게 다시 보내고, 두 번째는 Claude는 요약을 받지 못해요. 둘 다 오류가 나지 않아요. 요약된 메시지를 블록 앞에 남기면 compaction_block_misplaced 400 오류가 나니 이 경우와 구분해야 합니다.
비용도 문서가 정리합니다. 요약 호출은 일반 요청처럼 과금되고 속도 제한을 받으며, usage.iterations에 compaction 항목으로 보고돼요. 답변이 없어서 최상위 input_tokens와 output_tokens는 0이니 사용량은 iterations를 합산하라고 합니다. 이후 요청에 블록을 실어 보내는 데에는 컴팩션 비용이 추가되지 않는다고 해요.
언제 요약할지는 앱이 정한다
컴팩션 온디맨드에서는 시점을 정하는 쪽이 앱입니다. 완료된 턴 뒤라면 언제든 요약 요청을 보낼 수 있다고 문서가 적어요. 문서의 반복문 예제는 마지막 응답의 input_tokens와 output_tokens를 더해 다음 요청의 크기를 가늠하고, 그 합이 직접 정한 한도를 넘으면 요약을 요청합니다. 프롬프트 캐싱을 쓰면 input_tokens가 마지막 캐시 지점 뒤의 토큰만 세므로 cache_read_input_tokens와 cache_creation_input_tokens도 더하라고 하고, 토큰 세기(token counting) 엔드포인트에 같은 메시지를 보내는 방법도 안내합니다. 한도는 모델의 컨텍스트 창보다 낮게 잡으라고 해요. 예제의 2,500토큰은 짧은 대화에서도 요약이 일어나게 일부러 낮춘 값이라고 문서가 밝힙니다.
SDK의 도구 실행기(tool runner)는 요약 요청을 대신 보내 주는 메서드를 갖고 있습니다. Python에서는 compact_before_next_turn()을 부르면 현재 턴과 도구 호출이 끝난 뒤 실행기가 요약을 요청하고 기록을 바꿔요. 실행기는 베타 헤더를 자동으로 붙이지 않아서 compact-2026-09-04 베타로 직접 만들어야 합니다.
요약 내용이 마음에 들지 않으면 instructions에 16,384자까지 직접 쓴 요약 지시문을 넣을 수 있고, 이 지시문은 기본 프롬프트를 통째로 대체해요. 무엇을 남길지 적고 도구를 호출하지 말라고 쓰라는 안내가 붙습니다.
컴팩션의 세 가지 방식과 온디맨드가 다른 점
개요 문서의 비교표는 요약을 맡기는 방식을 셋으로 나눕니다. 문서는 쓸 수 있는 곳에서는 온디맨드를 쓰라고 권해요.
| 방식 | 시점을 정하는 쪽 | 쓰는 코드 |
|---|---|---|
| 컴팩션 온디맨드 | 요청을 보내는 앱 | 요약을 요청하고 맞바꾸는 반복문 |
| 토큰 임계값 컴팩션 | 입력 토큰이 정해 둔 값에 닿을 때 API | 일반 요청에 매개변수 하나 |
| 직접 만든 요약기 | 앱 | 요약 호출, 프롬프트, 기록 다시 쓰기 |
표는 개요 문서의 비교표에서 몇 행만 옮겼어요. 온디맨드는 반복문을 직접 짜야 하는 대신 백그라운드 실행을 지원해요. 토큰 임계값 쪽도 최근 턴 유지는 가능하지만 일시 정지 후 다시 넣는 방식이고, 백그라운드 실행은 없으며, 요청이 임계값에 닿으면 그 요청 안에서 요약이 돕니다. 온디맨드는 시점을 직접 통제해야 하거나, 요약을 쓰는 동안 멈출 수 없거나, 최근 턴을 남겨야 하는 앱에 맞다고 문서가 적습니다.
AI 기술 설명 – 캐시 진단(Cache Diagnostics) – 프롬프트 캐싱이 빗나간 이유를 알려 주는 Claude API 기능최근 턴 원문 유지와 백그라운드 요약 옵션
기본 반복문은 대화 전체를 요약합니다. 최근 턴을 유지하는 문서는 마지막 몇 턴을 원문 그대로 블록 뒤에 두는 방법을 설명해요. 남길 턴을 정하는 매개변수는 없고, 기록에서 자르는 지점을 앱이 고릅니다. 지점 앞 메시지만 요약 요청에 넣고, 지점 뒤 메시지는 블록 뒤에 그대로 붙입니다. 남긴 턴이 원래 길이로 돌아가니 많이 남길수록 요약이 비우는 공간은 줄어들어요. 도구 호출과 그 결과는 같은 쪽에 두라고 합니다.
백그라운드 문서는 요약을 쓰는 동안 대화를 멈추지 않는 방법입니다. 요약 요청을 보내고 메시지 개수를 기록한 뒤 대화는 전체 기록으로 계속하고, 블록이 도착하면 보낸 개수만큼 앞에서 지우고 그 자리에 블록을 둡니다. 그 사이 늘어난 메시지는 블록 뒤에 남아요.
요약 요청에 앞부분만 넣고, 남길 뒷부분을 블록 뒤에 원문으로 붙입니다. 마지막 몇 턴이 Claude에게 정확히 가야 할 때 씁니다.
요약을 기다리는 동안 대화를 이어 갑니다. 요청이 두 개 열려 있고 둘 다 속도 제한에 잡히므로, 늘어나는 턴을 받을 여유가 컨텍스트 창에 있을 때 시작하라고 문서가 안내해요.
둘은 함께 쓸 수 있다고 문서가 적습니다. 보존된 생각(preserved thinking)을 지원하는 모델에서 생각 블록을 돌려보내는 앱은 남긴 턴의 생각이 유효하게 남는 조건이 따로 있어서, 문서의 별도 항목을 확인해야 해요.
요약이 오지 않을 때와 사라지는 내용
요약 호출이 텍스트로 정상 종료하고 도구 호출이 없을 때만 요약이 만들어집니다. 그렇지 않아도 응답은 200에 content가 비어 있어서, 블록을 찾기 전에 stop_reason부터 확인하라고 문서가 강조해요. 이런 경우에도 요약 없이 이어 가다가 나중에 다시 요약을 요청하면 된다고 합니다.
더 눈여겨볼 부분은 제한 항목입니다. 문서는 요약된 메시지 안의 이미지, 문서, container_upload 블록, 가져온 URL이 블록으로 바뀌면 사라진다고 적어요. 이후 턴에 필요하면 다시 적거나 다시 올리라고 합니다. 요약된 범위 안의 role: "system" 메시지도 함께 요약돼서 그 텍스트 지시는 더 이상 적용되지 않고, 메시지별로 정한 노력(effort) 수준도 이어지지 않아요. 지시나 수준이 여전히 필요하면 다음 새 user 턴 바로 뒤에 role: "system" 메시지로 다시 쓰라고 안내합니다.
같은 절의 나머지 항목은 이렇습니다. compaction과 context_management는 한 요청에 함께 보낼 수 없고, 토큰 세기 엔드포인트는 compaction 매개변수를 무시하며, 블록에 붙인 cache_control은 요약 뒤에 캐시 지점을 만들어요. 작업 예산(task budget)의 remaining 값은 compaction이나 블록이 있는 요청에 보내면 400 오류가 납니다.
베타 상태와 지원 범위
문서 머리의 표시는 상태가 베타이고, 지원 모델은 Fable 5와 5.1, Mythos 5와 5.1 및 Preview, Opus 4.6·4.7·4.8·5·5.5, Sonnet 4.6·5·5.5, Haiku 5.5라고 적습니다. 지원 플랫폼은 Claude API, AWS 위 Claude 플랫폼, Google Cloud, Microsoft Foundry가 모두 베타예요. 모델이 지원하는지는 베타 헤더를 붙인 Models API에서 capabilities.compaction으로 확인할 수 있다고 합니다.
이 글에서는 문서의 코드와 응답 예시를 직접 실행하지 않았습니다. 설명한 동작은 모두 공식 문서가 적은 내용이고, 카드 속 JSON도 문서의 예시에서 형식을 옮긴 것입니다. 베타 기능이라 헤더와 매개변수가 바뀔 수 있으니 쓰기 전에 원문을 확인하세요.
참고한 공식 문서
본문은 컴팩션 개요, 컴팩션 온디맨드, 최근 턴 유지, 백그라운드 컴팩션, 릴리스 노트를 읽고 정리했습니다. 기능이 바뀔 수 있으니 쓰기 전에 원문을 확인하세요.
컴팩션 온디맨드 자주 묻는 질문
컴팩션 온디맨드는 어떻게 쓰나요?
compact-2026-09-04 베타 헤더와 함께 대화 전체에 compaction 매개변수(type은 summarize)를 붙여 보내면, 답변 대신 compaction 블록 하나가 돌아옵니다. 이후 요청에서는 그 블록을 messages 맨 앞에 두고 요약된 메시지는 지웁니다.
최근 대화는 요약하지 않고 그대로 둘 수 있나요?
문서는 가능하다고 합니다. 남길 턴을 요약 요청에서 빼고 블록 뒤에 원문 그대로 붙이면 돼요. 어느 턴까지 남길지 정하는 매개변수는 없고 자르는 지점을 앱이 직접 고릅니다.
컴팩션 후에도 이미지나 문서가 남나요?
남지 않습니다. 문서의 제한 항목은 요약된 메시지 안의 이미지, 문서, container_upload 블록, 가져온 URL이 블록으로 바뀌면 사라지니 이후 턴에 필요하면 다시 적거나 올리라고 안내합니다.
글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.
이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.
One Comment