BUG: ContextFilterPlugin num_invocations_to_keep counts model turns, not actual invocations

[Hor1zonZzz]

🔴 Required Information

Describe the Bug:

The num_invocations_to_keep parameter in ContextFilterPlugin is misleading. According to the official InvocationContext definition, an invocation is:

"Starts with a user message and ends with a final response. Can contain one or multiple agent calls."

However, ContextFilterPlugin actually counts model turns (every role == "model" content), not complete invocations. This means if a single invocation contains multiple LLM calls (e.g., function_call + final response), they are counted as multiple "invocations".

Steps to Reproduce:

1. Create an agent with tools
2. Configure ContextFilterPlugin(num_invocations_to_keep=1)
3. Send a user message that triggers a tool call
4. Observe the context filtering behavior

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.plugins import ContextFilterPlugin

# Assume we have a weather tool
agent = LlmAgent(
    model=model,
    name="assistant",
    tools=[get_weather],
)

app = App(
    name="test_app",
    root_agent=agent,
    plugins=[
        ContextFilterPlugin(num_invocations_to_keep=1),
    ],
)

# User asks: "What's the weather in Beijing?"
# This creates ONE invocation but TWO model turns:
#   1. model: function_call(get_weather)
#   2. model: "The weather in Beijing is sunny, 25°C"

Expected Behavior:

With num_invocations_to_keep=1, the entire invocation should be preserved:

[user: "What's the weather?"]
[model: function_call]
[user: function_response]  
[model: "It's sunny"]

Observed Behavior:

The implementation in context_filter_plugin.py (lines 98-112) counts by role == "model":

num_model_turns = sum(1 for c in contents if c.role == "model")
if num_model_turns >= self._num_invocations_to_keep:
    model_turns_to_find = self._num_invocations_to_keep
    ...
    if contents[i].role == "model":  # Counts every model response
        model_turns_to_find -= 1

This means num_invocations_to_keep=1 actually keeps only the last model turn, potentially breaking the invocation.

Note: _adjust_split_index_to_avoid_orphaned_function_responses partially mitigates this by keeping function_call/response pairs together, but the fundamental counting logic still differs from the official invocation definition.

Evidence - Official Invocation Definition:

From invocation_context.py (lines 98-136):

class InvocationContext(BaseModel):
  """An invocation context represents the data of a single invocation of an agent.

  An invocation:
    1. Starts with a user message and ends with a final response.
    2. Can contain one or multiple agent calls.
    3. Is handled by runner.run_async().
  
  ...
  
     ┌─────────────────────── invocation ──────────────────────────┐
     ┌──────────── llm_agent_call_1 ────────────┐ ┌─ agent_call_2 ─┐
     ┌──── step_1 ────────┐ ┌───── step_2 ──────┐
     [call_llm] [call_tool] [call_llm] [transfer]

"""

The diagram clearly shows **one invocation can contain multiple `[call_llm]`** operations.

**Environment Details:**

- ADK Library Version: 1.23.0
- Desktop OS: Windows 11
- Python Version: 3.13.5

**Model Information:**

- Are you using LiteLLM: Yes
- Which model is being used: deepseek/deepseek-chat (but this is model-agnostic)

---

## 🟡 Optional Information

**Suggested Fix:**

Option 1: **Rename the parameter** to accurately reflect its behavior:
```python
# Change from
num_invocations_to_keep: int
# To
num_model_turns_to_keep: int

Option 2: Fix the implementation to count actual invocations using invocation_id:

# Count unique invocation_ids instead of model turns
invocation_ids = []
for c in contents:
    if hasattr(c, 'invocation_id') and c.invocation_id not in invocation_ids:
        invocation_ids.append(c.invocation_id)
num_invocations = len(invocation_ids)

Related Issues:

• Smart Context Pruning with Token-Aware Filtering #3829 - Smart Context Pruning with Token-Aware Filtering (mentions limitations of current approach)
• BUG - ContextFilterPlugin sends orphaned tool call message to LLM causing failed API requests. #4027 - Orphaned function response bug (fixed, but related to this counting issue)

How often has this issue occurred?:

• Always (100%) - This is a code logic issue, reproducible every time

[GitMarco27]

Hi! I experienced the same issue long time ago, so I implemented a custom ContextFilterPlugin that actually does the job:

from typing import Callable, List, Optional

from google.adk.agents.callback_context import CallbackContext
from google.adk.events import Event
from google.adk.flows.llm_flows.contents import _should_include_event_in_context
from google.adk.models.llm_request import LlmRequest
from google.adk.models.llm_response import LlmResponse
from google.adk.plugins.base_plugin import BasePlugin
from google.genai.types import Content
from loguru import logger


def _filter_events(events: list[Event]) -> list[Event]:
    """Filters out events that should not be included in the LLM context.

    Args:
      events: The list of events to filter.
    Returns:
      The filtered list of events.
    """
    if not events:
        return events

    current_branch = (
        events[-1].branch if events[-1].branch else None
    )  # assume current branch from last event

    filtered_events = [
        event
        for event in events
        if _should_include_event_in_context(current_branch, event)
    ]

    return filtered_events


class ContextFilterPlugin(BasePlugin):
    """A plugin that filters the LLM context to reduce its size.

    Truncates the conversation history to the specified number of recent turns.

    What is a turn?
    - A turn is defined as the aggregation of all the events between two not user messages flagged as is_final_response().
    - A turn can be also obtained by aggregating all the events having the same invocation_id.
    """

    def __init__(
        self,
        num_turns_to_keep: Optional[int] = None,
        custom_filter: Optional[Callable[[List[Content]], List[Content]]] = None,
        name: str = "context_filter_plugin",
    ):
        """Initializes the context management plugin.

        Args:
          num_turns_to_keep (Optional[int]): The number of last turns to keep.
          custom_filter (Optional[Callable[[List[Event]], List[Event]]]): A function to filter the context.
          name (str): The name of the plugin instance.
        """
        super().__init__(name)
        self._num_turns_to_keep = num_turns_to_keep
        self._custom_filter = custom_filter

    async def before_model_callback(
        self, *, callback_context: CallbackContext, llm_request: LlmRequest
    ) -> Optional[LlmResponse]:
        """Filters the LLM request's context before it is sent to the model."""
        if not self._num_turns_to_keep:
            return None

        if not llm_request.contents:
            logger.warning(
                "No conversation history to trim, llm_request.contents is empty."
            )
            return None

        events = (
            callback_context._invocation_context.session.events  # pylint: disable=protected-access
        )

        events = _filter_events(events)

        # important assumption: the length of the session events and the llm_request.contents must be the same
        if len(events) != len(llm_request.contents):
            raise ValueError(
                f"Length mismatch between session events: {len(events)} and llm_request.contents: {len(llm_request.contents)}"
            )

        # let's extract the indexes of the first event of each turn
        turn_start_indexes = [0]  # always keep the first event
        for idx, event in enumerate(events):
            if (
                event.is_final_response() and event.author != "user"
            ):  # for some reason, user messages have is_final_response() set to True
                turn_start_indexes.append(idx + 1)

        # Now we can determine the starting index to keep
        if len(turn_start_indexes) <= self._num_turns_to_keep:
            logger.trace(
                f"Current number of turns is {len(turn_start_indexes)}, which is within the max history length of {self._num_turns_to_keep}. No trimming needed."
            )
            return None

        logger.debug(
            f"Trimming conversation history to the last {self._num_turns_to_keep} turns from {len(turn_start_indexes)} total turns."
        )
        start_idx = turn_start_indexes[-self._num_turns_to_keep]

        contents = llm_request.contents[start_idx:]

        if self._custom_filter:
            contents = self._custom_filter(contents)

        llm_request.contents = contents

        # Returning None signals ADK to continue normally
        return None