컨텍스트 편집은 현재 도구 결과 지우기 지원과 함께 베타 버전입니다. 이를 활성화하려면 API 요청에서 베타 헤더 context-management-2025-06-27을 사용하세요. 추가적인 컨텍스트 편집 전략은 향후 릴리스에서 추가될 예정입니다.이 기능에 대한 피드백을 공유하려면 피드백 양식을 통해 문의해 주세요.

​
작동 방식

clear_tool_uses_20250919 전략은 대화 컨텍스트가 구성된 임계값을 초과할 때 도구 결과를 지웁니다. 활성화되면 API는 시간순으로 가장 오래된 도구 결과를 자동으로 지우고, 이를 자리 표시자 텍스트로 대체하여 Claude가 도구 결과가 제거되었음을 알 수 있도록 합니다. 기본적으로 도구 결과만 지워집니다. clear_tool_inputs를 true로 설정하여 도구 결과와 도구 호출(도구 사용 매개변수) 모두를 선택적으로 지울 수 있습니다. 컨텍스트 편집은 콘텐츠를 지우는 것이 프롬프트 구조를 수정하여 캐시 히트에 필요한 일치 요구사항을 깨뜨리기 때문에 캐시된 프롬프트 접두사를 무효화합니다. 이를 고려하여 캐시 무효화가 가치 있도록 충분한 토큰을 지우는 것을 권장합니다. clear_at_least 매개변수를 사용하여 매번 최소한의 토큰 수가 지워지도록 보장하세요. 컨텍스트 편집과 함께 프롬프트 캐싱을 사용할 때, 콘텐츠가 지워질 때마다 캐시 쓰기 비용이 발생하지만, 후속 요청은 새로 캐시된 접두사를 재사용할 수 있습니다.

​
지원되는 모델

컨텍스트 편집은 다음에서 사용할 수 있습니다:
  • 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)

​
기본 사용법

컨텍스트 편집을 활성화하는 가장 간단한 방법은 전략 유형만 지정하는 것입니다. 다른 모든 구성 옵션은 기본값을 사용합니다: 
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-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "AI의 최근 발전 사항을 검색해주세요"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

​
고급 구성

추가 매개변수로 컨텍스트 편집 동작을 사용자 정의할 수 있습니다: 
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-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "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"]
                }
            ]
        }
    }'

​
구성 옵션

구성 옵션기본값설명
trigger100,000 입력 토큰컨텍스트 편집 전략이 활성화되는 시점을 정의합니다. 프롬프트가 이 임계값을 초과하면 지우기가 시작됩니다. 이 값을 input_tokens 또는 tool_uses로 지정할 수 있습니다.
keep3개 도구 사용지우기가 발생한 후 유지할 최근 도구 사용/결과 쌍의 수를 정의합니다. API는 가장 오래된 도구 상호작용을 먼저 제거하고 가장 최근 것들을 보존합니다.
clear_at_least없음전략이 활성화될 때마다 최소한의 토큰 수가 지워지도록 보장합니다. API가 지정된 양만큼 지울 수 없으면 전략이 적용되지 않습니다. 이는 컨텍스트 지우기가 프롬프트 캐시를 깨뜨릴 가치가 있는지 판단하는 데 도움이 됩니다.
exclude_tools없음도구 사용과 결과가 절대 지워지지 않아야 하는 도구 이름 목록입니다. 중요한 컨텍스트를 보존하는 데 유용합니다.
clear_tool_inputsfalse도구 결과와 함께 도구 호출 매개변수도 지울지 여부를 제어합니다. 기본적으로 Claude의 원래 도구 호출은 보이도록 유지하면서 도구 결과만 지워집니다.

​
응답 형식

context_management 응답 필드를 사용하여 요청에 적용된 컨텍스트 편집과 지워진 콘텐츠 및 입력 토큰에 대한 유용한 통계를 확인할 수 있습니다.
Response
{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,
                "cleared_input_tokens": 50000
            }
        ]
    }
}
스트리밍 응답의 경우 컨텍스트 편집이 최종 message_delta 이벤트에 포함됩니다:
Streaming Response
{
    "type": "message_delta",
    "delta": {
        "stop_reason": "end_turn",
        "stop_sequence": null
    },
    "usage": {
        "output_tokens": 1024
    },
    "context_management": {
        "applied_edits": [...]
    }
}

​
토큰 계산

/v1/messages/count_tokens 엔드포인트는 컨텍스트 관리를 지원하여 컨텍스트 편집이 적용된 후 프롬프트가 사용할 토큰 수를 미리 볼 수 있습니다. 
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-sonnet-4-5",
        "messages": [
            {
                "role": "user",
                "content": "대화를 계속해주세요..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'
Response
{
    "input_tokens": 25000,
    "context_management": {
        "original_input_tokens": 70000
    }
}
응답은 컨텍스트 관리가 적용된 후의 최종 토큰 수(input_tokens)와 지우기가 발생하기 전의 원래 토큰 수(original_input_tokens)를 모두 보여줍니다.