도구(tool use)를 붙인 Claude 에이전트를 돌려보면 금방 마주치는 문제가 있다. 대화가 길어질수록 토큰이 눈덩이처럼 불어난다.
원인은 단순하다. Messages API는 상태를 저장하지 않으니까 매 턴마다 전체 대화 히스토리를 다시 보내야 한다. 그런데 그 히스토리 안에는 웹 검색 결과, 파일 읽기 출력 같은 tool_result 블록이 통째로 쌓여 있다. 20번째 턴쯤 되면 이미 세 턴 전에 읽고 버린 검색 결과를 매번 다시 실어 보내고 있는 셈이다. 비용도 오르고, 결국 컨텍스트 윈도우 한계에 부딪힌다.
컨텍스트 편집이 하는 일
Claude에는 이걸 서버 쪽에서 자동으로 처리해주는 컨텍스트 편집(context editing) 기능이 있다. 오래된 도구 실행 결과를 모델에 보내기 전에 대화에서 비워버린다(clear). 요약하는 게 아니라 그냥 지운다는 게 핵심이다. (요약해서 압축하는 건 compaction이라는 별도 기능이다.)
베타라서 client.beta.messages.*를 쓰고 베타 헤더 하나만 붙이면 된다.
from anthropic import Anthropic
client = Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["context-management-2025-06-27"],
context_management={
"edits": [{"type": "clear_tool_uses_20250919"}]
},
tools=tools,
messages=messages,
)
clear_tool_uses_20250919가 오래된 tool_result를 비운다. 옵션으로 clear_tool_inputs: true를 주면 도구를 호출할 때 넘긴 파라미터(tool_use의 input)까지 같이 지워진다. 생각 블록을 정리하고 싶으면 clear_thinking_20251015를 추가하면 된다.
"edits": [
{"type": "clear_tool_uses_20250919", "clear_tool_inputs": True},
{"type": "clear_thinking_20251015"},
]
언제 켜야 할까
내 기준은 이렇다. 한두 번 도구를 부르고 끝나는 요청이면 굳이 안 쓴다. 오히려 매 요청 헤더만 늘어난다. 반면 파일을 여러 개 읽고, 검색을 반복하고, 수십 턴을 도는 자율 에이전트 루프라면 거의 필수다. 오래된 도구 출력은 대부분 다시 볼 일이 없는데, 그게 컨텍스트를 가장 많이 잡아먹기 때문이다.
주의할 점 하나. 편집은 히스토리를 바꾸니까, 모델이 세 턴 전 검색 결과를 다시 참조해야 하는 흐름이라면 지워진 뒤엔 그 정보가 사라진다. 정말 계속 필요한 맥락은 별도 파일이나 메모리 도구로 빼두고, 컨텍스트 편집은 "쓰고 버리는" 도구 출력에만 맡기는 게 안전하다.
세팅은 헤더 한 줄과 context_management 필드 하나가 전부다. 긴 에이전트를 돌리는데 토큰이 계속 새는 느낌이면, 압축을 고민하기 전에 이걸 먼저 켜보는 걸 추천한다.