压缩智能体上下文以提高性能¶

Supported in ADKPython v1.16.0Java v0.2.0TypeScript v0.6.0

随着 ADK 智能体的运行，它会收集上下文信息，包括用户指令、检索到的数据、工具响应和生成的内容。随着上下文数据量的增长，智能体的处理时间通常也会增加。越来越多的数据被发送到智能体使用的生成式 AI 模型，从而增加了处理时间并减慢了响应速度。ADK 上下文压缩功能旨在通过汇总较旧的会话历史（包括指令、输入和模型响应）来减少运行中智能体的上下文大小。通过维护紧凑的上下文窗口，此过程优化延迟并降低成本，同时确保智能体保留对关键近期交互的访问权限。

压缩通过 CompactionRequestProcessor 直接集成到 SingleFlow 中，允许根据你在 EventsCompactionConfig 中设置的规则自动进行事件压缩。

选择你的策略¶

你可以使用 EventsCompactionConfig 中的以下策略管理会话的数据：

基于令牌（主要）：根据实际消耗的令牌量触发清理。这作为绝对安全网，适用于不可预测的工作负载，例如用户粘贴大量代码块或上传大文件时。
滑动窗口（基于轮次）：在固定数量的对话轮次后触发清理。这适用于常规、可预测的文本聊天。

如果你同时配置了两种压缩策略，系统会优先执行基于令牌的压缩。当会话长度超过你定义的令牌阈值时，系统会触发基于令牌的压缩，并在该轮次跳过滑动窗口压缩。

基于令牌的压缩¶

基于令牌的压缩根据令牌或数据量（而非事件或轮次数量）触发上下文管理。

配置设置¶

通过向 App 对象添加 EventsCompactionConfig 设置，为你的智能体工作流添加基于令牌的压缩。你必须指定以下内容：

token_threshold：自动触发保留尾部压缩的令牌安全限制。
event_retention_size：触发压缩时以原始未压缩格式保留的最近事件/交互数量。这有助于保持即时对话上下文和代词指代消解。

要在你的项目中实现此功能，请使用以下配置：

# 1. Correct the import path to use the google.adk namespace
from google.adk.apps.app import App, EventsCompactionConfig
from google.adk.agents import Agent

# 2. Initialize your root agent (required for App setup)
root_agent = Agent(
    name="my_root_agent",
    description="Main coordinating agent for the workflow."
)

# 3. Token-based configuration: Activates the priority/pre-call layer
compaction_config = EventsCompactionConfig(
    token_threshold=4000,     # Triggers compaction when actual token count exceeds this
    event_retention_size=5    # Number of recent raw events to keep intact when token limit is hit
)

# 4. Register with required name and root_agent fields, and the config object
app = App(
    name="my_compacting_agent_app",
    root_agent=root_agent,
    events_compaction_config=compaction_config
)

滑动窗口压缩¶

上下文压缩功能使用滑动窗口方法来收集和汇总会话内的智能体工作流事件数据。当你在智能体中配置此功能时，一旦达到当前会话中特定数量的工作流事件或调用的阈值，它就会汇总来自较旧事件的数据。

# (Optional) Event-based, sliding window as supplementary setting
compaction_config = EventsCompactionConfig(
    compaction_interval=10,   # Number of turns between standard compactions
    overlap_size=2,           # Number of events to retain as overlapping context

Configure context compaction¶

通过在 App 对象 (Python/Java) 上添加事件压缩配置设置，或在 LlmAgent (TypeScript) 上配置 contextCompactors，为你的智能体工作流添加上下文压缩。作为配置的一部分，你必须指定压缩间隔和重叠大小 (Python/Java) 或令牌阈值和事件保留大小 (TypeScript)，如下面的示例代码所示：

PythonJavaTypeScript

from google.adk.apps.app import App
from google.adk.apps.app import EventsCompactionConfig

app = App(
    name='my-agent',
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,  # 每 3 次新调用触发一次压缩。
        overlap_size=1          # 包含来自上一个窗口的最后一次调用。
    ),
)

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, // Trigger compaction when session exceeds 1000 tokens.
      eventRetentionSize: 1, // Keep at least 1 raw event (overlap).
      summarizer: new LlmSummarizer({
        llm: new Gemini({model: 'gemini-flash-latest'}),
      }),
    }),
  ],
});

一旦配置完成，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) 或 LlmSummarizer (TypeScript) 类允许你指定用于汇总的特定模型。以下代码示例演示了如何定义和配置自定义汇总器：

PythonJavaTypeScript

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,
    }),
  ],
});

你可以通过修改其汇总器来进一步优化压缩器。在 Python 和 Java 中，自定义 LlmEventSummarizer 上的 prompt_template。在 TypeScript 中，自定义 LlmSummarizer 上的 prompt。有关更多详情，请参阅 LlmEventSummarizer 代码或 LlmSummarizer 代码。