压缩智能体上下文以提高性能¶
随着 ADK 智能体的运行，它会收集上下文信息，包括用户指令、检索到的数据、工具响应和生成的内容。随着上下文数据量的增长，智能体的处理时间通常也会增加。越来越多的数据被发送到智能体使用的生成式 AI 模型，从而增加了处理时间并减慢了响应速度。ADK 上下文压缩功能旨在通过汇总较旧的会话历史（包括指令、输入和模型响应）来减少运行中智能体的上下文大小。通过维护紧凑的上下文窗口，此过程优化延迟并降低成本，同时确保智能体保留对关键近期交互的访问权限。
压缩通过 CompactionRequestProcessor 直接集成到 SingleFlow 中，允许根据你在 EventsCompactionConfig 中设置的规则自动进行事件压缩。
选择你的策略¶
你可以使用 EventsCompactionConfig 中的以下策略管理会话的数据：
- 基于令牌（主要）：根据实际消耗的令牌量触发清理。这作为绝对安全网，适用于不可预测的工作负载，例如用户粘贴大量代码块或上传大文件时。
- 滑动窗口（基于轮次）：在固定数量的对话轮次后触发清理。这适用于常规、可预测的文本聊天。
如果你同时配置了两种压缩策略，系统会优先执行基于令牌的压缩。当会话长度超过你定义的令牌阈值时，系统会触发基于令牌的压缩，并在该轮次跳过滑动窗口压缩。
基于令牌的压缩¶
基于令牌的压缩根据令牌或数据量（而非事件或轮次数量）触发上下文管理。
配置设置¶
通过向 App 对象添加 EventsCompactionConfig 设置，为你的智能体工作流添加基于令牌的压缩。你必须指定以下内容：
token_threshold：自动触发保留尾部压缩的令牌安全限制。event_retention_size：触发压缩时以原始未压缩格式保留的最近事件/交互数量。这有助于保持即时对话上下文和代词指代消解。
要在你的项目中实现此功能，请使用以下配置：
# 1. 修正导入路径以使用 google.adk 命名空间
from google.adk.apps.app import App, EventsCompactionConfig
from google.adk.agents import Agent
# 2. 初始化你的根智能体（App 设置所需）
root_agent = Agent(
name="my_root_agent",
description="Main coordinating agent for the workflow."
)
# 3. 基于令牌的配置：激活优先/预调用层
compaction_config = EventsCompactionConfig(
token_threshold=4000, # 当实际令牌数超过此值时触发压缩
event_retention_size=5 # 触发压缩时保留的最近原始事件数量
)
# 4. 使用必需的 name 和 root_agent 字段以及配置对象进行注册
app = App(
name="my_compacting_agent_app",
root_agent=root_agent,
events_compaction_config=compaction_config
)
滑动窗口压缩¶
上下文压缩功能使用滑动窗口方法来收集和汇总会话内的智能体工作流事件数据。当你在智能体中配置此功能时，一旦达到当前会话中特定数量的工作流事件或调用的阈值，它就会汇总来自较旧事件的数据。
# （可选）基于事件的滑动窗口作为补充设置
compaction_config = EventsCompactionConfig(
compaction_interval=10, # 标准压缩之间的轮次间隔
overlap_size=2 # 作为重叠上下文保留的事件数量
)
配置上下文压缩¶
通过向 App 对象添加压缩配置（Python/Java/Kotlin）或在 LlmAgent 上配置 contextCompactors（TypeScript），为你的智能体工作流添加上下文压缩。作为配置的一部分，你必须指定压缩间隔和重叠大小（Python/Java）或令牌阈值和事件保留大小（TypeScript/Kotlin），如以下示例代码所示：
import com.google.adk.apps.App;
import com.google.adk.summarizer.EventsCompactionConfig;
App app = App.builder()
.name("my-agent")
.rootAgent(rootAgent)
.eventsCompactionConfig(EventsCompactionConfig.builder()
.compactionInterval(3) // 每 3 次新调用触发一次压缩。
.overlapSize(1) // 包含来自上一个窗口的最后一次调用。
.build())
.build();
import {Gemini, LlmAgent, LlmSummarizer, TokenBasedContextCompactor} from '@google/adk';
const agent = new LlmAgent({
name: 'my-agent',
model: 'gemini-flash-latest',
contextCompactors: [
new TokenBasedContextCompactor({
tokenThreshold: 1000, // 当会话超过 1000 个令牌时触发压缩。
eventRetentionSize: 1, // 保留至少 1 个原始事件（重叠）。
summarizer: new LlmSummarizer({
llm: new Gemini({model: 'gemini-flash-latest'}),
}),
}),
],
});
import com.google.adk.kt.apps.App
import com.google.adk.kt.summarizer.EventsCompactionConfig
// tokenThreshold 和 eventRetentionSize 必须同时设置；单独设置任一个会抛出异常。
// Kotlin 也接受其他标签页中使用的 compactionInterval/overlapSize 组合。
val app =
App(
appName = "my-agent",
rootAgent = rootAgent,
eventsCompactionConfig =
EventsCompactionConfig(
tokenThreshold = 1000, // 当最近一次提示超过 1000 个令牌时触发压缩。
eventRetentionSize = 1, // 保留至少 1 个原始事件。
),
)
配置完成后，ADK Runner 会在每次会话达到间隔时在后台处理压缩过程。
上下文压缩示例¶
如果你将 compaction_interval 设置为 3，将 overlap_size 设置为 1，则事件数据会在完成第 3、6、9 次等事件时被压缩。重叠设置会增加第二次汇总压缩的大小，以及之后的每次汇总，如图 1 所示。
图 1. 间隔为 3 且重叠为 1 的事件压缩配置图示。
使用此示例配置，上下文压缩任务按以下方式发生：
- 事件 3 完成：所有 3 个事件都被压缩成一个汇总。
- 事件 6 完成：事件 3 到 6 被压缩，包括 1 个先前事件的重叠。
- 事件 9 完成：事件 6 到 9 被压缩，包括 1 个先前事件的重叠。
配置设置¶
此功能的配置设置控制事件数据压缩的频率以及智能体工作流运行时保留多少数据。你可以选择配置压缩器对象：
compaction_interval: 设置触发先前事件数据压缩的已完成事件数量。overlap_size: 设置在新压缩的上下文集中包含多少先前压缩的事件。compactor: (可选) 定义压缩器对象，包括用于汇总的特定 AI 模型。 有关更多信息，请参阅定义汇总器。
定义汇总器¶
你可以通过定义汇总器来自定义上下文压缩的过程。
LlmEventSummarizer（Python、Java 和 Kotlin）或 LlmSummarizer（TypeScript）
类允许你指定用于汇总的特定模型。
以下代码示例演示了如何定义和配置自定义汇总器：
from google.adk.apps.app import App, EventsCompactionConfig
from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
from google.adk.models import Gemini
# 定义用于汇总的 AI 模型：
summarization_llm = Gemini(model="gemini-flash-latest")
# 使用自定义模型创建汇总器：
my_summarizer = LlmEventSummarizer(llm=summarization_llm)
# 为 App 配置自定义汇总器和压缩设置：
app = App(
name='my-agent',
root_agent=root_agent,
events_compaction_config=EventsCompactionConfig(
compaction_interval=3,
overlap_size=1,
summarizer=my_summarizer,
),
)
import com.google.adk.apps.App;
import com.google.adk.models.Gemini;
import com.google.adk.summarizer.EventsCompactionConfig;
import com.google.adk.summarizer.LlmEventSummarizer;
// 定义用于汇总的 AI 模型：
Gemini summarizationLlm = Gemini.builder()
.model("gemini-flash-latest")
.build();
// 使用自定义模型创建汇总器：
LlmEventSummarizer mySummarizer = new LlmEventSummarizer(summarizationLlm);
// 为 App 配置自定义汇总器和压缩设置：
App app = App.builder()
.name("my-agent")
.rootAgent(rootAgent)
.eventsCompactionConfig(EventsCompactionConfig.builder()
.compactionInterval(3)
.overlapSize(1)
.summarizer(mySummarizer)
.build())
.build();
import {Gemini, LlmAgent, LlmSummarizer, TokenBasedContextCompactor} from '@google/adk';
// 定义用于汇总的 AI 模型：
const summarizationLlm = new Gemini({model: 'gemini-flash-latest'});
// 使用自定义模型创建汇总器：
const mySummarizer = new LlmSummarizer({llm: summarizationLlm});
// 使用自定义汇总器和压缩设置配置智能体：
const agent = new LlmAgent({
name: 'my-agent',
model: 'gemini-flash-latest',
contextCompactors: [
new TokenBasedContextCompactor({
tokenThreshold: 1000,
eventRetentionSize: 1,
summarizer: mySummarizer,
}),
],
});
import com.google.adk.kt.apps.App
import com.google.adk.kt.models.Gemini
import com.google.adk.kt.summarizer.EventsCompactionConfig
import com.google.adk.kt.summarizer.LlmEventSummarizer
// 定义用于汇总的 AI 模型：
val summarizationLlm = Gemini(name = "gemini-flash-latest")
// 使用自定义模型创建汇总器：
val mySummarizer = LlmEventSummarizer(model = summarizationLlm)
// 为 App 配置自定义汇总器和压缩设置：
val app =
App(
appName = "my-agent",
rootAgent = rootAgent,
eventsCompactionConfig =
EventsCompactionConfig(
compactionInterval = 3,
overlapSize = 1,
summarizer = mySummarizer,
),
)
你可以通过修改汇总器来进一步优化压缩器。在 Python、Java 和 Kotlin 中，自定义 LlmEventSummarizer 上的提示模板——在 Python 中属性名为 prompt_template，在 Java 和 Kotlin 中为 promptTemplate。在 TypeScript 中，自定义 LlmSummarizer 上的 prompt。更多详情请参阅 LlmEventSummarizer 代码 或 LlmSummarizer 代码。