API - Context & Compression

ContextManager

import { ContextManager } from 'kagent-ts'

new ContextManager(config: ContextConfig)

interface ContextConfig {
  maxTokens: number               // 上下文窗口最大 Token 数
  compressionThreshold?: number   // 压缩触发阈值 (0-1, 默认: 0.8)
  keepTurns?: number              // 保留最近 N 轮 (默认: 20)
  toolResultMaxAgeMs?: number     // 工具结果最大保留时间 (默认: 300000)
}

方法

class ContextManager {
  addMessage(message: MessageData): void
  getMessages(): MessageData[]
  getTokenCount(): number
  needsCompression(): boolean
  compress(): CompressionResult
  clear(): void
}

---

ContextState

interface ContextState {
  messages: MessageData[]
  tokenCount: number
  compressedRounds: number
  truncatedOutputs: number
  lastCompressionAt: number
}

---

ProgressiveCompressor

import { ProgressiveCompressor } from 'kagent-ts'

new ProgressiveCompressor(config?: CompressionConfig)

interface CompressionConfig {
  maxOutputSize?: number           // 默认: 200KB
  truncatedOutputDir?: string      // 默认: ".kagent-context"
}

策略

type CompressionStrategy =
  | "truncate_large_outputs"     // 第 1 步: 截断大型输出
  | "drop_old_turns"             // 第 2 步: 删除旧轮次
  | "clear_aged_read_results"    // 第 3 步: 清除可重现结果
  | "llm_summarize"              // 第 4 步: LLM 摘要

interface CompressionResult {
  appliedStrategies: CompressionStrategy[]
  tokensSaved: number
  messagesRemoved: number
  truncatedOutputs: number
}

---

使用示例

import { ContextManager, ProgressiveCompressor } from 'kagent-ts'

// ContextManager 自动管理上下文窗口
const ctxManager = new ContextManager({
  maxTokens: 128000,
  compressionThreshold: 0.8,
  keepTurns: 20,
  toolResultMaxAgeMs: 300000,
})

// 添加消息
ctxManager.addMessage({ role: 'user', content: '你好' })

// 检查是否需要压缩
if (ctxManager.needsCompression()) {
  const result = ctxManager.compress()
  console.log(`已压缩: 节省 ${result.tokensSaved} tokens`)
}

// ProgressiveCompressor 提供更细粒度的控制
const compressor = new ProgressiveCompressor({
  maxOutputSize: 100 * 1024,     // 100KB
  truncatedOutputDir: './.context-cache',
})

下一步

• API - Session — Session API
• 上下文管理指南 — 4 步渐进式压缩详解
• API - Agent — Agent 类 API