CompactionHook

CompactionHook은 Agent의 컨텍스트가 설정한 임계값을 초과하면 메시지를 압축해, 긴 실행 중 모델의 컨텍스트 윈도우가 소진되지 않도록 하는 후크예요.

출처: 문서

본문

Usage

후크를 before_llm 아래에 등록하고 Agent 모델의 컨텍스트 윈도우를 구성하세요:

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor

compaction_hook = CompactionHook(
    compactor=SlidingWindowCompactor(),
    context_window=400_000,  # gpt-5.4-nano's context window
    compact_at=0.7,
    compact_to=0.4,
)

agent = Agent(
    chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
    tools=[],
    hooks={"before_llm": [compaction_hook]},
    max_agent_steps=50,
)

CompactionHook은 before_llm 아래에서만 등록할 수 있어요. Agent는 다른 후크 지점에 등록하면 ValueError를 발생시킵니다.

Configuration

Parameter	Default	Description
`compactor`	기본값 없음	메시지를 어떻게 줄일지 결정하는 `Compactor` 구현체.
`context_window`	기본값 없음	모델의 전체 컨텍스트 윈도우 크기(토큰). 0보다 커야 해요.
`compact_at`	`0.7`	압축이 시작되는 컨텍스트 윈도우의 비율. 다음 모델 응답과 도구 결과를 위해 그 위에 충분한 공간을 남겨두세요.
`compact_to`	`0.4`	압축이 목표로 하는 컨텍스트 윈도우의 비율. 더 낮은 값은 덜 자주 압축하지만 매번 더 많은 컨텍스트를 제거해요.
`token_counter`	`ApproximateTokenCounter()`	제공 업체가 보고한 사용량에 아직 포함되지 않은 메시지를 추정하는 데 쓰는 카운터.

임계값은 0 < compact_to < compact_at <= 1을 만족해야 해요. 목표가 트리거보다 같거나 높으면 다음 단계에서 대화가 다시 압축될 준비가 되어 있어, 후크가 그 구성을 거부합니다.

How the hook measures context

LLM 호출 후 Agent는 generator가 보고한 prompt-plus-completion 사용량을 state.data["context_tokens"]에 저장해요. 이 개수에는 시스템 프롬프트, 도구 스키마, 제공 업체별 채팅 템플릿 오버헤드가 포함됩니다. 그 호출 이후 추가된 메시지(보통 도구 결과)는 구성된 TokenCounter로 로컬에서 측정됩니다.

generator가 사용량을 보고하지 않아 context_tokens가 0으로 남으면, 후크는 전체 대화와 도구 스키마를 로컬에서 추정합니다. 기본 ApproximateTokenCounter는 추가 의존성이 필요 없어요. 다른 내장 또는 커스텀 카운터를 제공할 수 있습니다:

from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
from haystack.token_counters import TiktokenCounter

compaction_hook = CompactionHook(
    compactor=SlidingWindowCompactor(),
    context_window=128_000,
    token_counter=TiktokenCounter(encoding="o200k_base"),
)

후크는 compactor에 전달하는 목표에서 추정된 비메시지 오버헤드를 뺍니다. 이는 compactor가 도구 스키마나 제공 업체 포맷을 제거할 수 있는 메시지 토큰으로 취급하는 것을 방지해요.

Choosing a compactor

compactor는 어떤 정보가 남는지 제어합니다:

Compactor	Strategy
`SlidingWindowCompactor`	현재 작업과 맞는 만큼의 완전한 최근 대화를 유지하며, 작업 자체 단계를 자르기 전에 완전한 이력 턴을 제거해요.
`SummarizationCompactor`	현재 작업 전에 이력 턴을 점진적으로 요약하면서, 가장 최근에 구성된 Agent 단계를 보존해요.
`ToolResultPruningCompactor`	최근 결과는 그대로 두고, 오래된 대형 도구 결과를 짧은 자리표시자로 교체해요.

커스텀 전략을 위해 Compactor 프로토콜을 직접 구현할 수도 있어요. 요구사항은 Context Compaction 문서를 참고하세요.

Lifecycle and serialization

이 후크는 토큰 카운터와 compactor가 warm_up 메서드를 제공하면 예열하고, 지원하면 close를 compactor에 위임합니다. 비동기 수명주기 메서드는 compactor의 async 구현이 있으면 그것을 선호해요.

to_dict()는 후크를 compactor와 토큰 카운터와 함께 직렬화합니다. from_dict()는 두 중첩 객체를 모두 재구성하므로, 후크로 구성된 Agent를 직렬화하고 복원할 수 있어요.

더 알아보기 (Learn more)

CompactionHook — Haystack 공식 문서