컨텍스트 및 압축 관리

컨텍스트 및 압축 관리 (Managing Context & Compaction)

오래 실행되는 세션이 모델의 컨텍스트 창을 채우지 않게 유지하는 방법을 알아봐요.

출처: 문서

본문

왜 긴 세션이 컨텍스트 창을 채우나 (Why long sessions fill the context window)

모든 모델은 고정된 컨텍스트 창 — 요청당 읽을 수 있는 최대 토큰 수 — 을 가져요. 세션이 커지면 시스템 프롬프트, 도구 정의, 프롬프트 파일, 전체 메시지 기록(모든 도구 호출과 그 결과 포함)이 모두 그 예산에 포함돼요. 오래 실행되는 에이전트 — 많은 파일을 읽거나, 많은 명령을 실행하거나, 한동안 계속 채팅하는 것 — 는 결국 한계에 가까워져요. 요청이 더 이상 맞지 않으면 모델 제공자가 거부하고 세션이 멈춰요.

Docker Agent는 압축(compaction)으로 이에 대응해요: 대화의 오래된 부분을 컴팩트한 AI 생성 요약으로 대체해, 세션이 계속될 공간을 확보해요. 이 가이드는 당신이 가진 레버 — 자동 압축, 온디맨드 압축, 개별 도구 결과 다듬기 — 와 컨텍스트 게이지를 읽어 세션이 어디에 있는지 아는 법을 다뤄요.

Docker Agent가 자동으로 압축하게 하기 (Let Docker Agent compact automatically)

기본적으로 모든 에이전트는 추정 토큰 사용량이 모델 컨텍스트 창의 90%를 넘으면 자신의 세션을 사전 예방적으로 압축해요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A long-running research assistant
    instruction: You are a helpful assistant.

이 동작을 얻기 위해 구성할 것은 없어요 — 기본으로 켜져 있어요. 세 필드로 조율할 수 있어요:

Field	Where	Description
`session_compaction`	agent	`false` 로 설정하면 이 에이전트의 자동 압축을 완전히 비활성화(사전 예방적 임계값 트리거와 오버플로 후 자동 복구 모두). 수동 `/compact` 명령은 여전히 동작. 기본값: `true`.
`compaction_threshold`	agent 또는 model	사전 예방적 압축이 발동하는 컨텍스트 창의 비율(`0` 보다 크고 최대 `1`). 모델에 설정된 값이 에이전트 레벨 값보다 우선. 기본값: `0.9`.
`compaction_model`	agent, model, 또는 provider	압축(요약 생성) 호출을 다른, 보통 더 저렴하고 빠른, 모델에 위임. 에이전트 레벨 값이 이기고, 그다음 모델 레벨 값, 그다음 제공자 레벨 기본값.

임계값을 낮춰 더 일찍 압축하고 개별 요청을 더 작고 저렴하게 유지하거나, 첫 요약 전에 더 많은 축어적 기록을 컨텍스트에 유지하려면 높여요:

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-5
    # Compact at 80% of the window instead of the default 90%.
    compaction_threshold: 0.8

압축 자체는 모델 호출이에요 — 전체 대화를 모델에 공급하고 요약을 요청하는 것 — 그리고 세션에서 가장 비싼 호출이에요, 단지 컨텍스트가 가장 클 때 실행되는 것이기 때문이에요. 기본 추론 모델을 여기에 쓰는 이유가 거의 없어요. 대신 compaction_model 을 더 작은 것으로 가리키세요; 다른 모든 호출은 여전히 기본 모델에서 실행돼요:

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-5
    compaction_model: fast
  fast:
    provider: anthropic
    model: claude-haiku-4-5

Important 컨텍스트 창 불일치 compaction_model 이 기본 모델보다 더 작은 컨텍스트 창을 가지면, Docker Agent는 더 작은 창에 대해 압축을 트리거해 요약 호출이 항상 전체 대화를 소화할 수 있게 해요. 기본 모델의 창과 정렬을 유지하려면 창이 적어도 같은 크기인 압축 모델과 기본 모델을 짝지으세요. /context 헤더와 사이드바의 컨텍스트 게이지는 이 상한이 적용될 때 그것을 표면화해요: /context 헤더는 "compaction cap: • tokens" 라고 읽히는 두 번째 줄을 보여주고, 사이드바는 짧은 "⚠ capped" 마커를 보여줘요. Live-sessions 행에는 cap 문구가 없어요; 사이드바 마커는 의도적으로 모델 이름이나 수치를 반복하지 않아요 — 보고된 한도가 기본 모델의 창보다 작은 이유에 대한 유일한 권위는 /context 헤더예요.

완전하고 축약되지 않은 기록을 유지하고 컨텍스트 한도에 닿을 위험을 감수하길 구체적으로 원할 때만 압축을 비활성화해요:

agents:
  archivist:
    model: anthropic/claude-sonnet-4-5
    description: An assistant that never auto-compacts its sessions.
    instruction: You keep full conversation history and never lose context.
    session_compaction: false

완전한 구성은 examples/compaction_model.yaml 과 examples/compaction_threshold.yaml 을, 전체 필드 레벨 상세는 Model Config 참조의 Delegating Session Compaction 을 참고하세요.

온디맨드 압축 (Compact on demand)

자동 임계값까지 기다릴 필요가 없어요. 두 가지 TUI 명령이 직접 제어를 줘요:

/compact — 컨텍스트 창이 얼마나 가득 찼는지와 무관하게 지금 현재 세션의 기록을 요약하고 압축. 이전 세부 사항이 필요 없는 새 작업 단계를 시작하기 전에 유용.
/context — 컨텍스트 창 분해를 엽니다: 카테고리별 추정 토큰(시스템 프롬프트, 도구 정의, 프롬프트 파일, 메시지, 도구 결과, 압축 요약), 각각의 컨텍스트 버짓과 함께 현재 세션 + 모든 실행 중인 하위 에이전트 세션을 나열하는 Live sessions 보기, 첨부 파일과 프롬프트 파일의 파일별 인벤토리. 압축이 발생했으면 대화상자는 가장 최근 압축 요약의 축어적 텍스트도 표시하며, 하드 줄바꿈 보존과 대화상자 너비로 긴 줄 소프트 래핑을 수행.

/context 에서 화살표 키로 아무 live 세션을 선택하고 Enter를 눌러 그것을 명시적으로 압축해요 — 메인 세션뿐 아니라 하위 에이전트의 세션도 포함. 이것은 교차 에이전트 압축이 일어나는 유일한 방법이에요: 유휴 트리거 자동 압축이 없는 하위 에이전트 세션의 자동 압축이 없으므로, 오래 실행되는 백그라운드 에이전트가 당신의 통제 아래 유지돼요. 요청은 대상 세션의 자체 실행 루프에 큐잉되어 모델 턴 사이의 다음 안전 지점에서 적용되므로, 진행 중인 턴을 절대 손상시키지 않아요.

$ docker agent run agent.yaml
# ... work for a while ...
# Type /context to see the current breakdown, or /compact to summarize now

도구 결과 다듬어 공간 확보 (Trim tool results to save room)

압축은 한 번에 전체 대화를 다뤄요. 몇 개의 과대 도구 결과 — 전체 빌드 로그, 큰 파일 덤프 — 가 지배하는 세션의 경우, 세 가지 에이전트 레벨 필드로 압축에 도달하기 전에 피해를 상한 짓게 해요:

Field	What it bounds	Behavior
`max_tool_result_tokens`	각 도구 결과, 세션에 추가될 때	과대 결과는 중간부터 잘려요(middle-out): 앞과 뒤(보통 가장 정보가 많은 부분)는 유지되고 제거된 중간은 잘림 마커로 대체돼요.
`max_old_tool_call_tokens`	이전 도구 호출 인자와 결과의 총 예산	오래된 도구 호출이 예산을 넘으면 그 내용은 플레이스홀더로 전체 대체돼요 — 여전히 관련 있는 최근 호출을 건드리지 않고 컨텍스트 공간을 확보.
`num_history_items`	기록에 유지되는 비시스템 대화 메시지 수	토큰 예산이 아닌 메시지 수 한도. 수를 넘으면 가장 오래된 비보호 메시지가 먼저 버려져요; 시스템과 사용자 메시지는 항상 보호되고 이 한도에 대해 세거나 제거되지 않으므로, 조립된 기록이 `num_history_items` 를 넘을 수 있고 모든 사용자 메시지가 긴 단일 턴 에이전트 루프에서도 살아남아요.

max_tool_result_tokens 과 max_old_tool_call_tokens 은 len/4 토큰(토큰당 ~4문자 산업 경험칙)으로 근사되고, num_history_items 는 토큰이 아니라 메시지를 셉니다. 세 개 모두 기본적으로 비활성화(0)예요. 양수 값을 설정해 활성화해요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: An assistant whose tool results are capped at ~2000 tokens each.
    instruction: |
      You are a helpful assistant with shell access. Very large command
      outputs are truncated in the middle — the beginning and end are
      always preserved, and a marker shows where content was removed.
    max_tool_result_tokens: 2000
    toolsets:
      - type: shell

Tip 둘을 함께 사용 max_tool_result_tokens 는 각 결과가 기록되는 그 순간 상한 짓고, max_old_tool_call_tokens 는 더 이상 신선하지 않은 호출에서 공간을 되찾아요. 도구가 많은 에이전트(셸, 파일시스템)에서 결합해 압축 임계값에 근접하기 훨씬 전에 세션을 날씬하게 유지하세요. 완전한 예제는 examples/max_tool_result_tokens.yaml, 전체 필드 참조는 Agent Config 참고.

컨텍스트 게이지 읽기 (Read the context gauge)

TUI의 사이드바 토큰 사용 섹션(및 lean TUI 상태 줄의 채우기 바)은 세션이 압축 임계값에 가까워지면서 색이 상향 등급화되어, 요청이 실패하기 전에 문제가 오는 것을 볼 수 있어요:

State	Color	Trigger
Normal	(기본)	압축 임계값의 75% 미만 사용량
Warning	주황	압축 임계값의 75% 이상 사용량
Critical	빨강	압축 임계값의 95% 이상 사용량

압축이 실행되는 동안 백분율은 "compacting…" 표시로 대체되고, 토큰 수는 lean TUI 상태 줄에서 여전히 보여요. 임계값은 에이전트의 구성된 compaction_threshold(기본 0.9)에 따라 조정되므로, 커스텀 값이 예측 가능한 시각적 공간을 유지해요 — 예를 들어 compaction_threshold: 0.8 세션은 60% 사용량(0.8의 75%)에서 67.5% 대신 주황이 돼요.

언제든 /context 를 열어 그 백분율 뒤의 전체 카테고리별 분해를 보세요.

압축 전반에 걸쳐 비용에 무슨 일이 일어나나 (What happens to cost across compaction)

압축은 기록을 요약하지만, 세션이 실제로 쓴 비용을 결코 리셋하지 않아요. 세션 비용 추적은 압축을 가로질러 단조적이에요: 실행 총액은 요약된 대화 자체가 이제 더 작아졌어도 오직 위로만 갑니다. /cost 를 확인해 압축이 실행되기 전이나 후의 현재 분해를 언제든 보세요.

압축과 결과 다듬기는 이미 세션에 있는 컨텍스트를 관리해요. 큰 toolset이 대신 시작 컨텍스트를 부풀리고 있다면 — 많은 MCP 서버, 수백 개의 도구 — 지연 도구 로딩 을 살펴보세요, 그것은 시작 시 열심히 instead of lazily toolset의 도구를 등록해요.

컨텍스트 및 압축 관리