요약 설정

개요

summarization 구성은 대화 요약 및 컨텍스트 가지치기에 대한 중앙 집중식 제어를 제공합니다. 이는 이전에 사용자 지정 및 Azure OpenAI 엔드포인트에서 사용할 수 있었던 엔드포인트별 summarize 및 summaryModel 필드를 대체합니다.

대화가 모델의 컨텍스트 윈도우를 초과하면, 요약 시스템이 자동으로 이전 메시지들을 간결한 체크포인트 요약으로 압축합니다. 이를 통해 중요한 컨텍스트를 잃지 않으면서 대화를 무기한으로 이어갈 수 있습니다. 또한 이 시스템에는 컨텍스트 프루닝(context pruning) 기능이 포함되어 있어, 요약이 필요하기 전에 이전 메시지의 대규모 도구 결과를 점진적으로 축소하여 토큰 공간을 확보합니다.

요약 턴 이후, 컨텍스트 사용량 게이지는 폐기된 요약 이전 기록을 다시 계산하는 대신 유지된 요약 기준점과 요약 이후의 턴을 사용합니다. 누적 사용량 및 비용 합계에는 여전히 전체 브랜치 지출이 포함됩니다.

예시

summarization:
  provider: 'openAI'
  model: 'gpt-4o-mini'
  maxSummaryTokens: 4096
  reserveRatio: 0.05
  trigger:
    type: 'token_ratio'
    value: 0.8
  contextPruning:
    enabled: true
    keepLastAssistants: 3
    softTrimRatio: 0.3
    hardClearRatio: 0.5
    minPrunableToolChars: 50000
    softTrim:
      maxChars: 4000
      headChars: 1500
      tailChars: 1500
    hardClear:
      enabled: true
      placeholder: '[Old tool result content cleared]'

provider

기본값: 에이전트 자체 제공자

model

기본값: 에이전트 자체 모델

parameters

prompt

기본값(Default): 목표(Goal), 제약 사항 및 선호도(Constraints & Preferences), 진행 상황(Progress), 주요 결정 사항(Key Decisions), 다음 단계(Next Steps), 중요 맥락(Critical Context)에 대한 섹션을 생성하는 구조화된 체크포인트 프롬프트입니다.

updatePrompt

기본값(Default): 새 메시지를 기존 체크포인트에 병합하고, 오래된 세부 정보를 압축하며, 최근 작업에 더 많은 세부 정보를 제공하는 내장 프롬프트입니다.

maxSummaryTokens

reserveRatio

기본값: 0.05 (5% 헤드룸)

trigger

trigger 하위 키

트리거 유형

예시:

summarization:
  trigger:
    type: 'remaining_tokens'
    value: 8000

contextPruning

Context pruning은 요약(summarization)과는 독립적으로 작동하는 선택적 기능입니다. 이 기능은 이전 메시지에 포함된 대규모 도구 호출(tool call) 결과를 대상으로 하며, 두 가지 단계적 과정을 적용합니다:

1. Soft trim — 도구 결과의 앞부분과 뒷부분만 남기고 중간을 생략 부호로 대체하여 자릅니다.
2. Hard clear — 전체 도구 결과를 짧은 자리 표시자로 대체합니다

두 단계 모두 위치 기반입니다. 대화의 시작 부분에 가까운(오래된) 메시지부터 먼저 정리됩니다.

contextPruning 하위 키

기본값:

softTrim 하위 키

기본값: maxChars: 4000, headChars: 1500, tailChars: 1500

hardClear 하위 키

기본값: enabled: true, placeholder: "[Old tool result content cleared]"

예시:

summarization:
  contextPruning:
    enabled: true
    keepLastAssistants: 5
    softTrimRatio: 0.25
    hardClearRatio: 0.6
    minPrunableToolChars: 30000
    softTrim:
      maxChars: 6000
      headChars: 2500
      tailChars: 2500
    hardClear:
      enabled: true
      placeholder: '[Content removed for context management]'

전체 구성 예시

version: 1.3.10
cache: true

summarization:
  provider: 'openAI'
  model: 'gpt-4o-mini'
  maxSummaryTokens: 4096
  reserveRatio: 0.05
  trigger:
    type: 'token_ratio'
    value: 0.8
  contextPruning:
    enabled: true
    keepLastAssistants: 3
    softTrimRatio: 0.3
    hardClearRatio: 0.5
    minPrunableToolChars: 50000
    softTrim:
      maxChars: 4000
      headChars: 1500
      tailChars: 1500
    hardClear:
      enabled: true
      placeholder: '[Old tool result content cleared]'

엔드포인트별 설정에서의 마이그레이션

이전에 사용자 지정 또는 Azure OpenAI endpoint에서 summarize 및 summaryModel을 사용했다면:

endpoints:
  custom:
    - name: 'My Endpoint'
      summarize: true
      summaryModel: 'gpt-3.5-turbo'

이 필드들은 제거되었습니다. 대신 최상위 summarization 설정을 사용하세요:

summarization:
  model: 'gpt-4o-mini'

참고 사항

• 요약(Summarization)은 엔드포인트별이 아닌 전역적으로 구성됩니다.
• 사용자 지정 endpoint 및 Azure OpenAI endpoint의 summarize 및 summaryModel 필드는 더 이상 지원되지 않습니다.
• provider와 model이 생략되면, 에이전트 자체의 provider와 model이 요약에 사용됩니다.
• Context pruning은 기본적으로 비활성화되어 있으며 contextPruning.enabled: true를 통해 명시적으로 활성화해야 합니다.
• Context pruning은 minPrunableToolChars를 초과하는 도구 호출 결과에만 영향을 미치며, 더 작은 결과는 절대 pruning되지 않습니다.
• keepLastAssistants 설정은 trim/clear 비율과 관계없이 최근 턴이 삭제되지 않도록 보호합니다.
• 사용자 지정 prompt 및 updatePrompt 값은 내장 프롬프트를 완전히 대체하므로 주의해서 사용하세요.
• .env 파일에 AGENT_DEBUG_LOGGING=true를 설정하여 토큰 수 및 컨텍스트 정리 진단에 대한 상세 로깅을 활성화하세요.