메시지컨텍스트 관리

컴팩션

컨텍스트 윈도우 한도에 근접하는 긴 대화를 관리하기 위한 서버 측 컨텍스트 컴팩션입니다.

"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지는 API 및 데이터 보존을 참조하세요.

서버 측 컴팩션은 장기 실행 대화와 에이전트 워크플로에서 컨텍스트를 관리하기 위한 권장 전략입니다. 클라이언트 측 요약 코드 없이 컨텍스트 관리를 자동으로 처리합니다.

"Compaction"(컴팩션)은 컨텍스트 윈도우 한도에 근접할 때 오래된 컨텍스트를 자동으로 요약하여 장기 실행 대화와 작업의 유효 컨텍스트 길이를 확장합니다. 또한 활성 컨텍스트를 작게 유지합니다. 대화가 길어질수록 응답 품질이 저하되므로, 컴팩션은 오래된 콘텐츠를 간결한 요약으로 대체합니다.

긴 컨텍스트가 품질을 저하시키는 이유와 컴팩션이 어떻게 도움이 되는지에 대한 자세한 내용은 효과적인 컨텍스트 엔지니어링을 참조하세요.

다음과 같은 경우에 이상적입니다:

사용자가 하나의 채팅을 오랜 기간 사용하기를 원하는 채팅 기반의 멀티턴 대화
컨텍스트 윈도우를 초과할 수 있는 많은 후속 작업(주로 도구 사용)이 필요한 작업 지향 프롬프트

컴팩션은 베타 버전입니다. 이 기능을 사용하려면 API 요청에 베타 헤더 compact-2026-01-12를 포함하세요.

지원되는 모델

컴팩션은 다음 모델에서 지원됩니다:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

컴팩션 작동 방식

컴팩션이 활성화되면 Claude는 대화가 구성된 토큰 임계값에 도달할 때 자동으로 대화를 요약합니다. API는 다음과 같이 동작합니다:

입력 토큰이 지정된 트리거 임계값에 도달하는 시점을 감지합니다.
현재 대화의 요약을 생성합니다.
요약을 포함하는 compaction 블록을 생성합니다.
컴팩션된 컨텍스트로 응답을 계속합니다.

후속 요청에서는 응답을 메시지에 추가하세요. API는 compaction 블록 이전의 모든 콘텐츠 블록을 자동으로 제거하고 요약에서부터 대화를 계속합니다.

컴팩션 흐름: 입력 토큰이 트리거에 도달하면 Claude가 compaction 블록에 요약을 작성하고 계속 진행합니다

기본 사용법

Messages API 요청의 context_management.edits에 compact_20260112 전략을 추가하여 컴팩션을 활성화하세요.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# 대화를 계속하려면 응답(압축 블록 포함)을 추가합니다
messages.append({"role": "assistant", "content": response.content})

매개변수

매개변수	타입	기본값	설명
`type`	string	필수	`"compact_20260112"`여야 합니다
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	컴팩션을 트리거할 시점입니다. `input_tokens`가 유일하게 지원되는 트리거 타입입니다. `value`는 최소 50,000 토큰이어야 합니다.
`pause_after_compaction`	boolean	`false`	컴팩션 요약 생성 후 일시 중지할지 여부
`instructions`	string	`null`	사용자 정의 요약 프롬프트입니다. 제공되면 기본 프롬프트를 완전히 대체합니다.

트리거 구성

trigger 매개변수를 사용하여 컴팩션이 트리거되는 시점을 구성하세요:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

사용자 정의 요약 지침

기본 요약 프롬프트는 모델에 따라 다릅니다. 각 기본 프롬프트는 Claude에게 향후 컨텍스트 윈도우에서 작업을 계속하는 데 필요한 정보를 담은 요약을 <summary></summary> 태그 안에 작성하도록 지시합니다. 예를 들어, 일부 모델은 다음 프롬프트를 사용합니다:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

instructions 매개변수를 통해 사용자 정의 지침을 제공할 수 있습니다. 사용자 정의 지침은 기본 프롬프트를 보완하지 않습니다. 완전히 대체합니다:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

컴팩션 후 일시 중지

pause_after_compaction을 사용하여 컴팩션 요약 생성 후 API를 일시 중지할 수 있습니다. 이를 통해 API가 응답을 계속하기 전에 추가 콘텐츠 블록(예: 최근 메시지 또는 특정 지침 지향 메시지 보존)을 추가할 수 있습니다.

활성화되면 API는 compaction 블록을 생성한 후 compaction 중지 이유와 함께 메시지를 반환합니다:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# 압축(compaction)이 일시 중지를 트리거했는지 확인합니다
if response.stop_reason == "compaction":
    # 응답에 압축 블록만 포함되어 있습니다
    messages.append({"role": "assistant", "content": response.content})

    # 요청을 계속합니다
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

총 토큰 예산 적용

모델이 많은 도구 사용 반복이 포함된 긴 작업을 수행할 때 총 토큰 소비량이 크게 증가할 수 있습니다. pause_after_compaction을 컴팩션 카운터와 결합하여 누적 사용량을 추정하고 예산에 도달하면 작업을 원활하게 마무리할 수 있습니다.

이 예제는 SDK 언어에서만 제공됩니다. 그 가치는 요청을 둘러싼 예산 추적 로직에 있습니다. 원시 요청은 트리거 구성의 trigger와 컴팩션 후 일시 중지의 pause_after_compaction을 결합합니다.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # 소비된 총 토큰 수를 추정하고, 예산 초과 시 마무리를 요청합니다
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

compaction 블록 다루기

컴팩션이 트리거되면 API는 어시스턴트 응답의 시작 부분에 compaction 블록을 반환합니다.

장기 실행 대화에서는 여러 번의 컴팩션이 발생할 수 있습니다. 마지막 compaction 블록은 프롬프트의 최종 상태를 반영하며, 그 이전의 콘텐츠를 생성된 요약으로 대체합니다.

Output

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

compaction 블록 다시 전달하기

단축된 프롬프트로 대화를 계속하려면 후속 요청에서 compaction 블록을 API에 다시 전달해야 합니다. 가장 간단한 방법은 전체 응답 콘텐츠를 메시지에 추가하는 것입니다:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# 압축 블록이 포함된 응답을 받은 후
messages.append({"role": "assistant", "content": response.content})

# 대화 계속하기
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

API가 compaction 블록을 받으면 그 이전의 모든 콘텐츠 블록은 무시됩니다. 다음 중 하나를 선택할 수 있습니다:

원본 메시지를 목록에 유지하고 API가 컴팩션된 콘텐츠 제거를 처리하도록 하기
컴팩션된 메시지를 수동으로 제거하고 compaction 블록 이후만 포함하기

스트리밍

compaction 블록은 텍스트 블록과 다르게 스트리밍됩니다. content_block_start 이벤트를 받은 후, 전체 요약 콘텐츠가 포함된 단일 content_block_delta(중간 스트리밍 없음)를 받고, 그다음 content_block_stop 이벤트를 받습니다.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # 최종 누적된 메시지 가져오기
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

프롬프트 캐싱

컴팩션은 프롬프트 캐싱과 잘 작동합니다. compaction 블록에 cache_control 중단점을 추가하여 요약된 콘텐츠를 캐시할 수 있습니다.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

시스템 프롬프트로 캐시 적중률 극대화

컴팩션이 발생하면 요약은 캐시에 기록되어야 하는 새로운 콘텐츠가 됩니다. 추가 캐시 중단점이 없으면 캐시된 시스템 프롬프트도 무효화되어 컴팩션 요약과 함께 다시 캐시해야 합니다.

캐시 적중률을 극대화하려면 시스템 프롬프트 끝에 cache_control 중단점을 추가하세요. 이렇게 하면 시스템 프롬프트가 대화와 별도로 캐시되므로 컴팩션이 발생할 때:

시스템 프롬프트 캐시는 유효하게 유지되고 캐시에서 읽힙니다
컴팩션 요약만 새 캐시 항목으로 기록하면 됩니다

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

이렇게 하면 대화 전반에 걸쳐 여러 컴팩션 이벤트가 발생해도 긴 시스템 프롬프트가 캐시된 상태로 유지됩니다.

사용량 이해하기

컴팩션에는 추가 샘플링 단계가 필요하며, 이는 속도 제한과 청구에 반영됩니다. API는 응답에 자세한 사용량 정보를 반환합니다:

Output

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

iterations 배열은 각 샘플링 반복의 사용량을 보여줍니다. 컴팩션이 발생하면 compaction 반복 다음에 메인 message 반복이 표시됩니다. 이 예제에서는 컴팩션이 아닌 반복이 하나뿐이므로 최상위 input_tokens와 output_tokens가 message 반복과 정확히 일치합니다. 마지막 반복의 토큰 수는 컴팩션 후의 유효 컨텍스트 크기를 반영합니다.

최상위 input_tokens와 output_tokens에는 컴팩션 반복 사용량이 포함되지 않습니다. 이들은 컴팩션이 아닌 모든 반복의 합계를 반영합니다. 요청에 대해 소비되고 청구된 총 토큰을 계산하려면 usage.iterations 배열의 모든 항목을 합산하세요.

이전에 비용 추적이나 감사를 위해 usage.input_tokens와 usage.output_tokens에 의존했다면, 컴팩션이 활성화된 경우 usage.iterations 전체를 집계하도록 추적 로직을 업데이트해야 합니다. 컴팩션 베타가 활성화되면 컴팩션이 발생하지 않았더라도 모든 응답에 usage.iterations가 포함됩니다. compaction 항목은 요청 중에 새로운 컴팩션이 트리거된 경우에만 나타납니다. 이전 compaction 블록을 다시 적용하는 것은 추가 컴팩션 비용을 발생시키지 않으며, 이 경우 최상위 사용량 필드는 정확하게 유지됩니다.

다른 기능과 결합하기

서버 도구

서버 도구(예: 웹 검색)를 사용할 때 컴팩션 트리거는 각 샘플링 반복 시작 시 확인됩니다. 트리거 임계값과 생성된 출력량에 따라 단일 요청 내에서 컴팩션이 여러 번 발생할 수 있습니다.

토큰 계산

토큰 계산 엔드포인트(/v1/messages/count_tokens)는 프롬프트에 있는 기존 compaction 블록을 적용하지만 새로운 컴팩션을 트리거하지는 않습니다. 이전 컴팩션 이후의 유효 토큰 수를 확인하는 데 사용하세요:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

예제

다음은 컴팩션을 사용한 장기 실행 대화의 전체 예제입니다:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # 응답 추가 (압축 블록은 자동으로 포함됩니다)
    messages.append({"role": "assistant", "content": response.content})

    # 텍스트 콘텐츠 반환
    return next(block.text for block in response.content if block.type == "text")


# 긴 대화 실행
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 대화가 필요한 만큼 chat()을 계속 호출

다음은 pause_after_compaction을 사용하여 이전 대화와 현재 사용자 메시지(총 세 개의 메시지)를 요약하는 대신 그대로 보존하는 예제입니다:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # 압축이 발생하여 일시 중지되었는지 확인
    if response.stop_reason == "compaction":
        # 응답에서 압축 블록 가져오기
        compaction_block = response.content[0]

        # 이전 교환 + 현재 사용자 메시지(메시지 3개)를
        # 압축 블록 뒤에 포함하여 보존
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # 새 메시지 목록 구성: 압축 + 보존된 메시지
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # 압축된 컨텍스트 + 보존된 메시지로 요청 계속
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # 압축을 반영하도록 메시지 목록 업데이트
        messages.clear()
        messages.extend(messages_after_compaction)

    # 최종 응답 추가
    messages.append({"role": "assistant", "content": response.content})

    # 텍스트 콘텐츠 반환
    return next(block.text for block in response.content if block.type == "text")


# 긴 대화 실행
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 대화에 필요한 만큼 chat()을 계속 호출

현재 제한 사항

요약에 동일한 모델 사용: 요청에 지정된 모델이 요약에 사용됩니다. 요약에 다른(예: 더 저렴한) 모델을 사용하는 옵션은 없습니다.
도구가 정의된 경우 컴팩션이 실패할 수 있음: 요청에 tools가 포함된 경우, 모델이 내부 요약 단계에서 요약을 작성하는 대신 도구를 호출하는 경우가 간혹 있습니다. 이 경우 응답에는 content: null인 compaction 블록이 포함됩니다. 이를 방지하려면 instructions를 모델에게 도구를 호출하지 말라고 명시적으로 지시하는 프롬프트로 설정하세요. 예를 들면:
```
Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
```

다음 단계

컨텍스트 편집

컨텍스트 편집으로 대화 컨텍스트가 증가함에 따라 자동으로 관리하세요.

컨텍스트 윈도우

컨텍스트 윈도우 크기와 관리 전략에 대해 알아보세요.

세션 메모리 컴팩션 쿡북

백그라운드 스레딩과 프롬프트 캐싱을 사용하여 즉각적인 세션 메모리 컴팩션으로 장기 실행 대화를 관리하는 실용적인 구현을 살펴보세요.

Was this page helpful?

메시지컨텍스트 관리

컴팩션

컨텍스트 윈도우 한도에 근접하는 긴 대화를 관리하기 위한 서버 측 컨텍스트 컴팩션입니다.

"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지는 API 및 데이터 보존을 참조하세요.

긴 컨텍스트가 품질을 저하시키는 이유와 컴팩션이 어떻게 도움이 되는지에 대한 자세한 내용은 효과적인 컨텍스트 엔지니어링을 참조하세요.

다음과 같은 경우에 이상적입니다:

사용자가 하나의 채팅을 오랜 기간 사용하기를 원하는 채팅 기반의 멀티턴 대화
컨텍스트 윈도우를 초과할 수 있는 많은 후속 작업(주로 도구 사용)이 필요한 작업 지향 프롬프트

컴팩션은 베타 버전입니다. 이 기능을 사용하려면 API 요청에 베타 헤더 compact-2026-01-12를 포함하세요.

지원되는 모델

컴팩션은 다음 모델에서 지원됩니다:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

컴팩션 작동 방식

컴팩션이 활성화되면 Claude는 대화가 구성된 토큰 임계값에 도달할 때 자동으로 대화를 요약합니다. API는 다음과 같이 동작합니다:

입력 토큰이 지정된 트리거 임계값에 도달하는 시점을 감지합니다.
현재 대화의 요약을 생성합니다.
요약을 포함하는 compaction 블록을 생성합니다.
컴팩션된 컨텍스트로 응답을 계속합니다.

후속 요청에서는 응답을 메시지에 추가하세요. API는 compaction 블록 이전의 모든 콘텐츠 블록을 자동으로 제거하고 요약에서부터 대화를 계속합니다.

기본 사용법

Messages API 요청의 context_management.edits에 compact_20260112 전략을 추가하여 컴팩션을 활성화하세요.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# 대화를 계속하려면 응답(압축 블록 포함)을 추가합니다
messages.append({"role": "assistant", "content": response.content})

매개변수

매개변수	타입	기본값	설명
`type`	string	필수	`"compact_20260112"`여야 합니다
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	컴팩션을 트리거할 시점입니다. `input_tokens`가 유일하게 지원되는 트리거 타입입니다. `value`는 최소 50,000 토큰이어야 합니다.
`pause_after_compaction`	boolean	`false`	컴팩션 요약 생성 후 일시 중지할지 여부
`instructions`	string	`null`	사용자 정의 요약 프롬프트입니다. 제공되면 기본 프롬프트를 완전히 대체합니다.

트리거 구성

trigger 매개변수를 사용하여 컴팩션이 트리거되는 시점을 구성하세요:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

사용자 정의 요약 지침

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

instructions 매개변수를 통해 사용자 정의 지침을 제공할 수 있습니다. 사용자 정의 지침은 기본 프롬프트를 보완하지 않습니다. 완전히 대체합니다:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

컴팩션 후 일시 중지

활성화되면 API는 compaction 블록을 생성한 후 compaction 중지 이유와 함께 메시지를 반환합니다:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# 압축(compaction)이 일시 중지를 트리거했는지 확인합니다
if response.stop_reason == "compaction":
    # 응답에 압축 블록만 포함되어 있습니다
    messages.append({"role": "assistant", "content": response.content})

    # 요청을 계속합니다
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

총 토큰 예산 적용

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # 소비된 총 토큰 수를 추정하고, 예산 초과 시 마무리를 요청합니다
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

compaction 블록 다루기

컴팩션이 트리거되면 API는 어시스턴트 응답의 시작 부분에 compaction 블록을 반환합니다.

Output

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

compaction 블록 다시 전달하기

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# 압축 블록이 포함된 응답을 받은 후
messages.append({"role": "assistant", "content": response.content})

# 대화 계속하기
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

API가 compaction 블록을 받으면 그 이전의 모든 콘텐츠 블록은 무시됩니다. 다음 중 하나를 선택할 수 있습니다:

원본 메시지를 목록에 유지하고 API가 컴팩션된 콘텐츠 제거를 처리하도록 하기
컴팩션된 메시지를 수동으로 제거하고 compaction 블록 이후만 포함하기

스트리밍

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # 최종 누적된 메시지 가져오기
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

프롬프트 캐싱

컴팩션은 프롬프트 캐싱과 잘 작동합니다. compaction 블록에 cache_control 중단점을 추가하여 요약된 콘텐츠를 캐시할 수 있습니다.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

시스템 프롬프트로 캐시 적중률 극대화

시스템 프롬프트 캐시는 유효하게 유지되고 캐시에서 읽힙니다
컴팩션 요약만 새 캐시 항목으로 기록하면 됩니다

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

이렇게 하면 대화 전반에 걸쳐 여러 컴팩션 이벤트가 발생해도 긴 시스템 프롬프트가 캐시된 상태로 유지됩니다.

사용량 이해하기

컴팩션에는 추가 샘플링 단계가 필요하며, 이는 속도 제한과 청구에 반영됩니다. API는 응답에 자세한 사용량 정보를 반환합니다:

Output

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

다른 기능과 결합하기

서버 도구

토큰 계산

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

예제

다음은 컴팩션을 사용한 장기 실행 대화의 전체 예제입니다:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # 응답 추가 (압축 블록은 자동으로 포함됩니다)
    messages.append({"role": "assistant", "content": response.content})

    # 텍스트 콘텐츠 반환
    return next(block.text for block in response.content if block.type == "text")


# 긴 대화 실행
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 대화가 필요한 만큼 chat()을 계속 호출

다음은 pause_after_compaction을 사용하여 이전 대화와 현재 사용자 메시지(총 세 개의 메시지)를 요약하는 대신 그대로 보존하는 예제입니다:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # 압축이 발생하여 일시 중지되었는지 확인
    if response.stop_reason == "compaction":
        # 응답에서 압축 블록 가져오기
        compaction_block = response.content[0]

        # 이전 교환 + 현재 사용자 메시지(메시지 3개)를
        # 압축 블록 뒤에 포함하여 보존
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # 새 메시지 목록 구성: 압축 + 보존된 메시지
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # 압축된 컨텍스트 + 보존된 메시지로 요청 계속
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # 압축을 반영하도록 메시지 목록 업데이트
        messages.clear()
        messages.extend(messages_after_compaction)

    # 최종 응답 추가
    messages.append({"role": "assistant", "content": response.content})

    # 텍스트 콘텐츠 반환
    return next(block.text for block in response.content if block.type == "text")


# 긴 대화 실행
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 대화에 필요한 만큼 chat()을 계속 호출

현재 제한 사항

요약에 동일한 모델 사용: 요청에 지정된 모델이 요약에 사용됩니다. 요약에 다른(예: 더 저렴한) 모델을 사용하는 옵션은 없습니다.
도구가 정의된 경우 컴팩션이 실패할 수 있음: 요청에 tools가 포함된 경우, 모델이 내부 요약 단계에서 요약을 작성하는 대신 도구를 호출하는 경우가 간혹 있습니다. 이 경우 응답에는 content: null인 compaction 블록이 포함됩니다. 이를 방지하려면 instructions를 모델에게 도구를 호출하지 말라고 명시적으로 지시하는 프롬프트로 설정하세요. 예를 들면:
```
Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
```

다음 단계

컨텍스트 편집

컨텍스트 편집으로 대화 컨텍스트가 증가함에 따라 자동으로 관리하세요.

컨텍스트 윈도우

컨텍스트 윈도우 크기와 관리 전략에 대해 알아보세요.

세션 메모리 컴팩션 쿡북

백그라운드 스레딩과 프롬프트 캐싱을 사용하여 즉각적인 세션 메모리 컴팩션으로 장기 실행 대화를 관리하는 실용적인 구현을 살펴보세요.

Was this page helpful?

지원되는 모델

컴팩션 작동 방식

기본 사용법

매개변수

트리거 구성

사용자 정의 요약 지침

컴팩션 후 일시 중지

총 토큰 예산 적용

compaction 블록 다루기

compaction 블록 다시 전달하기

스트리밍

프롬프트 캐싱

시스템 프롬프트로 캐시 적중률 극대화

사용량 이해하기

다른 기능과 결합하기

서버 도구

토큰 계산

예제

현재 제한 사항

다음 단계

지원되는 모델

컴팩션 작동 방식

기본 사용법

매개변수

트리거 구성

사용자 정의 요약 지침

컴팩션 후 일시 중지

총 토큰 예산 적용

compaction 블록 다루기

compaction 블록 다시 전달하기

스트리밍

프롬프트 캐싱

시스템 프롬프트로 캐시 적중률 극대화

사용량 이해하기

다른 기능과 결합하기

서버 도구

토큰 계산

예제

현재 제한 사항

다음 단계

지원되는 모델

컴팩션 작동 방식

기본 사용법

매개변수

트리거 구성

사용자 정의 요약 지침

컴팩션 후 일시 중지

총 토큰 예산 적용

compaction 블록 다루기

compaction 블록 다시 전달하기

스트리밍

프롬프트 캐싱

시스템 프롬프트로 캐시 적중률 극대화

사용량 이해하기

다른 기능과 결합하기

서버 도구

토큰 계산

예제

현재 제한 사항

다음 단계

지원되는 모델

컴팩션 작동 방식

기본 사용법

매개변수

트리거 구성

사용자 정의 요약 지침

컴팩션 후 일시 중지

총 토큰 예산 적용

compaction 블록 다루기

compaction 블록 다시 전달하기

스트리밍

프롬프트 캐싱

시스템 프롬프트로 캐시 적중률 극대화

사용량 이해하기

다른 기능과 결합하기

서버 도구

토큰 계산

예제

현재 제한 사항

다음 단계