feat: Introduce app abstraction, contents_strategy and compaction_strategy

src/google/adk/agents/app.py

@@ -0,0 +1,40 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import Union
+from pydantic import BaseModel, Field
+from ..plugins.base_plugin import BasePlugin
+from .base_agent import BaseAgent
+from .base_compaction_strategy import BaseCompactionStrategy
+from .base_contents_strategy import BaseContentsStrategy
+from ..events.event import Event
+
+class App(BaseModel):
+  """Agentic application."""
+
+  name: str
+  """The name of the application."""
+
+  root_agent: BaseAgent = None
+  """The root agent in the application."""
+
+  plugins: list[BasePlugin] = Field(default_factory=list)
+  """The plugins in the application."""
+
+  include_contents: Union[str, BaseContentsStrategy] = None
+  """The strategy to include contents in the application."""
+
+  compaction_strategy: Union[str, BaseCompactionStrategy] = None
+  """The strategy to compact the contents in the application."""

src/google/adk/agents/base_compaction_strategy.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from ..events.event import Event
+
+
+class BaseCompactionStrategy(BaseModel):
+  """Base interface for compacting events."""
+
+  def compact_events(
+      self,
+      current_branch: Optional[str],
+      events: list[Event],
+      agent_name: str = '',
+  ) -> Event:
+    """Compacts the events.
+
+      This method will summarize the events and return a new summray event
+      indicating the range of events it summarized.
+
+    When sending events to the LLM, if a summary event is present, the events it
+    replaces (those identified in itssummary_range) should not be included.
+
+      Args:
+        current_branch: The current branch of the agent.
+        events: Events to compact.
+        agent_name: The name of the agent.
+
+      Returns:
+        The new compaction event.
+    """
+    raise NotImplementedError()

src/google/adk/agents/base_contents_strategy.py

@@ -0,0 +1,42 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import List, Optional
+from pydantic import BaseModel
+from ..events.event import Event
+
+
+class BaseContentsStrategy(BaseModel):
+  """Base interface for handling event filtering or select logics."""
+
+  def get_events(
+      self,
+      current_branch: Optional[str],
+      events: list[Event],
+      agent_name: str = '',
+  ) -> List[Event]:
+    """Get the contents for the LLM request.
+
+    Applies filtering, rearrangement, and content processing to events.
+
+    Args:
+      current_branch: The current branch of the agent.
+      events: Events to process.
+      agent_name: The name of the agent.
+
+    Returns:
+      A list of returned contents.
+    """
+    raise NotImplementedError()

src/google/adk/events/event.py

@@ -77,6 +77,15 @@ class Event(LlmResponse):
   conversation history.
   """
 
+  sequence_id: Optional[int] = None
+  """The sequence id of the event."""
+
+  # TODO: we can support continuous range if we are certain the range is always continous
+  #       or discrete items if we want to support non-continuous range.
+  #       The sequence ID range of the events that are summarized, in the form(start_sequence_id, end_sequence_id)`
+  summary_range: Optional[tuple[int, int]] = None
+  """The range of events to summarize."""
+
   # The following are computed fields.
   # Do not assign the ID. It will be assigned by the session.
   id: str = ''