@ diepagents/ compaction (签名)

将AI SDK对话的快照简化为摘要和近期历史. 这个 软件包直接使用 AI SDK v7 类型,不依赖 @deepagents/context 或者苏克鲁夫 它不拥有商店,调度员, 或谈话状态.

执行决定和核查记录在 相位文件。 。 。 .

import { compact } from '@deepagents/compaction';

const result = await compact({
  messages, // AI SDK ModelMessage[]
  model: summaryModel, // Your explicitly configured summarization model
  targetTokens: 20_000,
  keepLastMessages: 4, // Optional; defaults to 4
  instructions: 'Preserve exact customer commitments and record IDs.',
  abortSignal,
});

switch (result.status) {
  case 'compacted':
    // Persist the result and its source-message mapping before adopting it.
    // result.replacedRange contains half-open indices into the input snapshot.
    break;
  case 'cannot-fit':
    // result.reason explains the failure. result.messages still holds the input.
    break;
}

结果合同

• messages: 已准备好的关于成功的信息,否则,一份未修改的复印件 输入数组。 输入信息及其提供者元数据从未变异.
• tokens.before 编号 : tokens.after: 输入和返回信件的估计值.
• usage: 原生AI SDK LanguageModelUsage 当总和运行时,包括 当其输出被拒绝时; 否则 undefined。 。 。 .
• 打开 compacted, (中文(简体) ), summary 包含生成的文本和 replacedRange 准确识别 messages.slice(start, end) 从输入快照.
• 打开 cannot-fit, (中文(简体) ), reason 实值 no-safe-boundary, (中文(简体) ), protected-history, (中文(简体) ), incomplete-summary, (中文(简体) ), empty-summary,或 summary-too-large。 。 。 .

索引描述的是这个调用输入,而不是永久历史ID. 呼叫者将其映射到 他们自己的稳定识别特征,坚持绘制地图和汇总,并保持 用于显示或检索的原始记录。 保留信件对象为 复用不变. 将输入和输出都视为不可改变的快照.

何等为一字不差

压缩以普通用户信息取代一个相接的旧范围 标签 Previous conversation summary。它从不宣传历史内容 到系统指令.

后四条消息默认保留. keepLastMessages 更改此选项 最小值, 但保留后缀扩展为包含未解决的工具调用/ 批准 和完整的工具/核准关系。 已完成 交换可在用户回合内进行总结。 当最新的用户请求落下时 在被替换的区域内,在摘要和 在保留步骤之前。 完全在被替换范围内的闭合交换是: 与汇总模型一起提供.

主要系统信息仍然有效。 后来的系统消息、文件、媒体和 不透明的提供者内容保护从他们的位置开始的后缀. 他们是 未转换为丢失的文本。 如果保护历史没有留下空间 汇总,结果为 cannot-fit;包裹从不默默地丢弃.

预算和模式呼吁

targetTokens 仅覆盖提供的消息。 打电话的人必须分开 允许外部指令、工具定义、提供者间接费用和输出 头室. 默认估计每四条按一令牌排序的短信 字符,四舍五入(空数组为零)。 这是热心症,不是 保证任何供应商的代币或账单.

对于媒体或不透明的提供者内容,提供能理解 选中的对话模式 。 这也允许只使用文本的呼叫者使用更精确的 供应商专用计数器 :

const result = await compact({
  messages,
  model: summaryModel,
  targetTokens: 20_000,
  countTokens: async (candidateMessages) => {
    return countForConversationModel(candidateMessages);
  },
});

estimateTokens(messages) 显示与调用者相同的默认文本计数器 需要先检查自动触发器,然后再援引 compact()。 。 。 .

计数器接收完整的候选信件数组,包括摘要 包装 它必须返回一个非负式的安全整数,并且不得改变其输入. 包裹在返回成功前用同样的计数器检查最终结果.

一通电话最多发出一次汇总请求,SDK复写被禁用. 其产出津贴是估计的剩余预算,上限为2 048先令. 不采用空的、短的、非文本的或超预算摘要. 提供者出错,输入/计数器无效,取消则拒绝承诺. 汇总模型本身必须支持序列历史的输入大小; 此软件包不会将一个超大小的历史分割成多个模型调用 .

持续对话

来电者选择何时收紧. 例如,运行时间可能触发60,000 估计输入令牌,并通过可得到的电文指标为20 000个令牌。 A 类 扳机比目标高,为以后的转弯留有余地.

保存成功结果后, 重复使用 result.messages 并附加新信件. 不要在每个回合重编一个摘要 。 以后的收缩可以消耗 前一个摘要和新的历史。 简表之间保持不变 因此重放的压缩件保持稳定; 提供者缓存保留 供应商的责任.

苏克鲁夫整编

在代理声明上配置自动收缩,同时使用其模型和 指令:

import {
  cacheLikelyCold,
  messagesExceed,
  tokensExceed,
} from '@deepagents/compaction';

const root = defineAgent({
  name: 'assistant',
  model,
  sandbox,
  instructions,
  compaction: {
    model: summaryModel,
    triggers: [tokensExceed(60_000), messagesExceed(100)],
    targetTokens: 20_000,
    keepLastMessages: 4,
  },
});

defineAgent 来自 @deepagents/experimental/zukhruf供应 明确归纳模型. triggers 是一种非空的上游阵列; Zukhruf按顺序评价它们,并在首场对决(OR)时止步. 门槛 帮助者需要一个正的安全整数,并严格地与阈值相匹配, 而不是在平等. messagesExceed 计数所有当前模式信件,包括 摘要和工具消息,不由用户翻转或原始存储的记录.

触发器只接收一个读取 { messages, tokens, cacheAgeMs, cacheRetentionMs } 检查站后快照 重放和上下文准备. tokens 估计完整的模型输入 : 信件、指示、工具定义和任何结构化输出计划. 运行时间对消息和请求信封使用相同的字符heuristic. 提供方框架、代码-模式包装和服务器工具仍然大致相同. 自定义上方可以返回布尔或承诺; 采样前错误会停止转弯 。 这些帮助者不需要网络访问.

使用 cacheLikelyCold() 当观察到的快速缓存到达 提供者请求的保留窗口 :

import { cacheLikelyCold } from '@deepagents/compaction';

const triggers = [cacheLikelyCold()];

Zukhruf 读取本地 SDK 请求元数据 include.requestBody,在模型之后 中间软件应用了其设置。 它把假设的窗口与 ; 不需要额外的提供者 API 调用.

• OpenAI GPT-5.6,后使用所记录的30分钟政策. 较早的模型 明确 in_memory 或者说 24h 设置使用保守的上限 1小时或24小时。 省略的旧模式政策不详,因为 组织可以确定默认. OpenAI 缓存寿命。 。 。 .
• Anthropic(包括本地的 Claude 提供者) 使用请求的缓存 控制:5分钟 ttl 删除或 5m,一个小时 1h。 。 。 . 所观察的缓存-写用法区分了五分钟和一小时的写作. 没有足够使用证据的混合断点有一个未知窗口; 请求更长的 TTL 不确定它的前缀被缓存 . Athropic 缓存持续时间。 。 。 .
• OpenRouter使用报告的上游提供者和解答模式. OpenAI和Anthropic路线使用这些政策。 未经承认的上游地区依然存在 未知;该型号的供应商前缀本身不足.

未经确认的提供者、缺少请求机构、没有支持的政策以及双子座 隐性缓存没有推断出保留窗口。 触发器仍未激活. 对自定义提供者来说,有明确的覆盖: cacheLikelyCold({ retentionMs: yourProviderRetentionMs })。强制必须是一个 以毫秒计的正安全整数。 平等相对.

Zukhruf 记录了主模型报告为阳性的启动请求时间 缓存读取或写出,包括最后一步。 写作零读取建立 一个新的基线。 用于远程测量的录制工作被禁用,在新鲜设备中存活 主持人。 没有正缓存计数器的成功反应可以清除基线.

cacheAgeMs 在不匹配证据的情况下未定义:分支、模型、, 指令、工具定义、 SDK 请求设置以及先前发送的信件 前缀必须仍然匹配,而时钟不能向后移动。 追加 信件保存前缀证据. 当证据或保留不明时,帮助者返回虚假. 估计 过期;它不查询提供者缓存状态或预测路由变化. 它不配置提供者缓存 。 无触发需要网络访问.

匹配触发器决定压缩 . targetTokens 限制由此产生的上下文; 它从来不压制比赛。 直接电话: compact() 也尝试减少, 即使输入已经符合目标. 设定超过目标的迹象阈值,以便在收缩间离开前厅. 在Zukhruf中,符号触发器和目标都覆盖了估计的全部输入. 这个 运行时间将指令/工具信封从 targetTokens 打电话前 compact(),然后将其添加到报告的结果中。 如果只有那个信封 使目标耗尽,转弯失败 request-overhead 在总结之前. 独立 compact() 仍然只预算它提供的信息。 储备产出 单间和供应 countTokens 为了媒体.

运行时间持续成功 chat.metadata.zukhruf.inputUsage,独立于遥测。 同样的 模型、分支、指令、工具、设置和未改变的预测消息 前缀,下一个估计数是所测量的输入和附加的估计 留言。 保留了缓存输入;产出和摘要模型使用不包括在内 再说一遍。 协会在东道主重启和检查站恢复后幸存. 更改设置/ 前缀或应用摘要使其无效 。 失踪或无效 使用量和本地公司/汇总迭代使用量回到新的估计数; 他们从未被视为可靠的上下文。 本地供货商压缩 无法使用此特性.

明确 countTokens(messages) 优于计量的使用。 运行时间 然后添加估计信封;独立通话只使用自定义计数. 这两种方法都无法保证一个精确的模型封顶。 不计算终点或模式 联系上目录了.

Zukhruf在每个模式步骤、邮箱输入和上下文提醒之前检查. 它在通过紧凑的元数据之前,坚持对对话进行检查 留言。 原始UI笔录保存完好. 后转和新主机 仅在检查点源前缀仍然匹配时重新使用; 倒带或编辑 更改前缀使其不适用。 压缩失败停止转弯 而不取代历史。 总结用法包括在谈话用法中.

生命周期事件

苏克鲁夫发射AI SDK data-compaction 转弯道上有块 他们打的 有效载荷, CompactionEvent,从 @deepagents/experimental/zukhruf。 。 。 . 同一事件 id 属于一项评价:

新设 started 财务报告和审定财务报表 completed 活动包括: tokenScope: "request"; DevTools 软件 将其计数标记为估计输入符。 没有这个历史事件 标记保留其信息估计含义.

例如,41条短信息,估计总输入量为2 000个信使匹配 messagesExceed(40) 即使有4000个目标: started 随后是 completed 当一个有效的摘要符合条件并保存了检查站时。 保险 边框和输出验证仍然适用:空的或完全被保护的历史 返回时 cannot-fit,以及一个过大的摘要。 无法匹配的触发器会发出否 紧凑尝试.

这些是原生的持久性数据部分。 每个块ID结合其评价ID 和状态,所以重放保留一个保存的每个状态的部分. AI SDK 软件 onData 还是 接收它们; 普通的 UI 语录保存它们重新打开 。 SDK 排除 数据部件来自模型输入,没有自定义转换器。 DevTools 组匹配 将评价ID输入一个可扩展的内入条目,并注明值和检查站 细节. 数据块即使在总和化等待时也会迅速冲出. 取消 使用现有的可持久转弯状态cancelled); 开始尝试,没有 当转弯不再流出时,终端事件似乎中断. 生命周期有效载荷中未包括概要文本或原始提供者出错.

核查

npx nx run @deepagents/compaction:typecheck
npx nx run @deepagents/compaction:test

集成测试使用公用包导出和AI SDK v7的V4模型固定. 他们行使预算成果,下游SDK生成,出处,重复 收缩、触发阈值、受保护的工具/核准边界、媒体计数器、, 错误和中止。 Zukhruf的融合测试 附加锻炼 工具循环、检查点重放、同步决定和触发出错.