Compress agent context for performance

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

Supported in ADKPython v1.16.0

As an ADK agent runs it collects context information, including user instructions, retrieved data, tool responses, and generated content. As size of this context data grows, agent processing times typically also increase. More and more data is sent to the generative AI model used by the agent, increasing processing time and slowing down responses. The ADK Context Compaction feature is designed to reduce the size of context as an agent is running by summarizing older parts of agent workflow event history.

当 ADK 智能体运行时,它会收集上下文信息,包括用户指令、检索到的数据、工具响应和生成的内容。随着此上下文数据大小的增长,智能体处理时间通常也会增加。越来越多的数据被发送到智能体使用的生成式 AI 模型,增加了处理时间并减慢了响应速度。ADK 上下文压缩功能旨在通过总结智能体工作流事件历史的较旧部分来减少智能体运行时上下文的大小。

The Context Compaction feature uses a sliding window approach for collecting and summarizing agent workflow event data within a Session. When you configure this feature in your agent, it summarizes data from older events once it reaches a threshold of a specific number of workflow events, or invocations, with the current Session.

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

Configure context compaction

配置上下文压缩

Add context compaction to your agent workflow by adding an Events Compaction Configuration setting to the App object of your workflow. As part of configuration, you must specify a compaction interval and overlap size, as shown in the following sample code:

通过将事件压缩配置设置添加到工作流的 App 对象,将上下文压缩添加到您的智能体工作流中。作为配置的一部分,您必须指定压缩间隔和重叠大小,如以下示例代码所示:

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,  # Trigger compaction every 3 new invocations.
        # 每 3 次新调用触发压缩。
        overlap_size=1          # Include last invocation from the previous window.
        # 包含上一个窗口中的最后一次调用。
    ),
)

Once configured, the ADK Runner handles the compaction process in the background each time the session reaches the interval.

配置完成后,ADK Runner 每次会话达到间隔时会在后台处理压缩过程。

Example of context compaction

上下文压缩示例

If you set compaction_interval to 3 and overlap_size to 1, event data is compressed upon completion of events 3, 6, 9, and so on. The overlap setting increases the size of the second summary compression, and each summary afterwards, as shown in Figure 1.

如果您将 compaction_interval 设置为 3,将 overlap_size 设置为 1,则会在事件 3、6、9 等完成后压缩事件数据。重叠设置会增加第二次摘要压缩的大小,以及之后的每次摘要,如图 1 所示。

Figure 1. Ilustration of event compaction configuration with a interval of 3 and overlap of 1. 图 1. 事件压缩配置的示意图,间隔为 3,重叠为 1。

With this example configuration, context compression tasks happen as follows:

使用此示例配置,上下文压缩任务按以下方式进行:

1. Event 3 completes: All 3 events are compressed into a summary 事件 3 完成: 所有 3 个事件被压缩成一个摘要
2. Event 6 completes: Events 3 to 6 are compressed, including the overlap of 1 prior event 事件 6 完成: 事件 3 到 6 被压缩,包括 1 个先前事件的重叠
3. Event 9 completes: Events 6 to 9 are compressed, including the overlap of 1 prior event 事件 9 完成: 事件 6 到 9 被压缩,包括 1 个先前事件的重叠

Configuration settings

配置设置

The configuration settings for this feature control how frequently event data is compressed and how much data is retained as the agent workflow runs. Optionally, you can configure a compactor object.

此功能的配置设置控制事件数据压缩的频率以及智能体工作流运行时保留的数据量。您可以选择配置压缩器对象。

• compaction_interval: Set the number of completed events that triggers compaction of the prior event data. 设置触发先前事件数据压缩的已完成事件数。
• overlap_size: Set how many of the previously compacted events are included in a newly compacted context set. 设置在新的压缩上下文集中包含多少个先前压缩的事件。
• summarizer: (Optional) Define a summarizer object including a specific AI model to use for summarization. For more information, see Define a Summarizer. (可选)定义一个摘要器对象,包括用于摘要的特定 AI 模型。有关更多信息,请参阅定义摘要器。

Define a Summarizer

定义摘要器

You can customize the process of context compression by defining a summarizer. The LlmEventSummarizer class allows you to specify a particular model for summarization. The following code example demonstrates how to define and configure a custom summarizer:

您可以通过定义摘要器来自定义上下文压缩过程。LlmEventSummarizer 类允许您指定用于摘要的特定模型。以下代码示例演示了如何定义和配置自定义摘要器:

from google.adk.apps.app import App, EventsCompactionConfig
from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
from google.adk.models import Gemini

# Define the AI model to be used for summarization:
# 定义用于摘要的 AI 模型:
summarization_llm = Gemini(model="gemini-2.5-flash")

# Create the summarizer with the custom model:
# 使用自定义模型创建摘要器:
my_summarizer = LlmEventSummarizer(llm=summarization_llm)

# Configure the App with custom summarizer and compaction settings:
# 使用自定义摘要器和压缩设置配置 App:
app = App(
    name='my-agent',
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=my_summarizer,
    ),
)

You can further refine the operation of SlidingWindowCompactor by modifying its summarizer class LlmEventSummarizer including changing the prompt_template setting of that class. For more details, see the LlmEventSummarizer code.

您可以通过修改其摘要器类 LlmEventSummarizer 来进一步改进 SlidingWindowCompactor 的操作,包括更改该类的 prompt_template 设置。有关更多详细信息,请参阅LlmEventSummarizer 代码。