feat(sessions): Add session title management functionality

src/google/adk/cli/adk_web_server.py

@@ -29,6 +29,7 @@
 from typing import Literal
 from typing import Optional
 
+from fastapi import Body
 from fastapi import FastAPI
 from fastapi import HTTPException
 from fastapi import Query
@@ -868,6 +869,21 @@ async def create_session(
 
       return session
 
+    @app.patch(
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/title",
+        response_model_exclude_none=True,
+    )
+    async def update_session_title(
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        title: Optional[str] = Body(None, embed=True),
+    ) -> dict[str, str]:
+      await self.session_service.update_session_title(
+          app_name=app_name, user_id=user_id, session_id=session_id, title=title
+      )
+      return {"status": "success"}
+
     @app.delete("/apps/{app_name}/users/{user_id}/sessions/{session_id}")
     async def delete_session(
         app_name: str, user_id: str, session_id: str

src/google/adk/cli/utils/local_storage.py

@@ -157,13 +157,15 @@ async def create_session(
       user_id: str,
       state: Optional[dict[str, object]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     service = await self._get_service(app_name)
     return await service.create_session(
         app_name=app_name,
         user_id=user_id,
         state=state,
         session_id=session_id,
+        title=title,
     )
 
   @override
@@ -206,6 +208,23 @@ async def delete_session(
         app_name=app_name, user_id=user_id, session_id=session_id
     )
 
+  @override
+  async def update_session_title(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      title: Optional[str],
+  ) -> None:
+    service = await self._get_service(app_name)
+    await service.update_session_title(
+        app_name=app_name,
+        user_id=user_id,
+        session_id=session_id,
+        title=title,
+    )
+
   @override
   async def append_event(self, session: Session, event: Event) -> Event:
     service = await self._get_service(session.app_name)

src/google/adk/sessions/base_session_service.py

@@ -56,6 +56,7 @@ async def create_session(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     """Creates a new session.
 
@@ -102,6 +103,24 @@ async def delete_session(
   ) -> None:
     """Deletes a session."""
 
+  @abc.abstractmethod
+  async def update_session_title(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      title: Optional[str],
+  ) -> None:
+    """Updates the title of a session.
+
+    Args:
+      app_name: The name of the app.
+      user_id: The id of the user.
+      session_id: The id of the session.
+      title: The new title for the session. If None, clears the title.
+    """
+
   async def append_event(self, session: Session, event: Event) -> Event:
     """Appends an event to a session object."""
     if event.partial:

src/google/adk/sessions/database_session_service.py

@@ -222,6 +222,7 @@ async def create_session(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     # 1. Populate states.
     # 2. Build storage session object
@@ -268,12 +269,15 @@ async def create_session(
         storage_user_state.state = storage_user_state.state | user_state_delta
 
       # Store the session
-      storage_session = schema.StorageSession(
-          app_name=app_name,
-          user_id=user_id,
-          id=session_id,
-          state=session_state,
-      )
+      storage_session_kwargs = {
+          "app_name": app_name,
+          "user_id": user_id,
+          "id": session_id,
+          "state": session_state,
+      }
+      if hasattr(schema.StorageSession, "title"):
+        storage_session_kwargs["title"] = title
+      storage_session = schema.StorageSession(**storage_session_kwargs)
       sql_session.add(storage_session)
       await sql_session.commit()
 
@@ -408,6 +412,30 @@ async def delete_session(
       await sql_session.execute(stmt)
       await sql_session.commit()
 
+  @override
+  async def update_session_title(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      title: Optional[str],
+  ) -> None:
+    await self._prepare_tables()
+    schema = self._get_schema_classes()
+    async with self.database_session_factory() as sql_session:
+      storage_session = await sql_session.get(
+          schema.StorageSession, (app_name, user_id, session_id)
+      )
+      if storage_session is None:
+        raise ValueError(
+            f"Session not found: app_name={app_name}, user_id={user_id},"
+            f" session_id={session_id}"
+        )
+      if hasattr(storage_session, "title"):
+        storage_session.title = title
+        await sql_session.commit()
+
   @override
   async def append_event(self, session: Session, event: Event) -> Event:
     await self._prepare_tables()

src/google/adk/sessions/in_memory_session_service.py

@@ -58,12 +58,14 @@ async def create_session(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     return self._create_session_impl(
         app_name=app_name,
         user_id=user_id,
         state=state,
         session_id=session_id,
+        title=title,
     )
 
   def create_session_sync(
@@ -73,13 +75,15 @@ def create_session_sync(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     logger.warning('Deprecated. Please migrate to the async method.')
     return self._create_session_impl(
         app_name=app_name,
         user_id=user_id,
         state=state,
         session_id=session_id,
+        title=title,
     )
 
   def _create_session_impl(
@@ -89,6 +93,7 @@ def _create_session_impl(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      title: Optional[str] = None,
   ) -> Session:
     if session_id and self._get_session_impl(
         app_name=app_name, user_id=user_id, session_id=session_id
@@ -116,6 +121,7 @@ def _create_session_impl(
         id=session_id,
         state=session_state or {},
         last_update_time=time.time(),
+        title=title,
     )
 
     if app_name not in self.sessions:
@@ -286,6 +292,23 @@ def _delete_session_impl(
 
     self.sessions[app_name][user_id].pop(session_id)
 
+  @override
+  async def update_session_title(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      title: Optional[str],
+  ) -> None:
+    session = self.sessions.get(app_name, {}).get(user_id, {}).get(session_id)
+    if session is None:
+      raise ValueError(
+          f'Session not found: app_name={app_name}, user_id={user_id},'
+          f' session_id={session_id}'
+      )
+    session.title = title
+
   @override
   async def append_event(self, session: Session, event: Event) -> Event:
     if event.partial:

src/google/adk/sessions/migration/migrate_from_sqlalchemy_sqlite.py

@@ -91,13 +91,14 @@ def migrate(source_db_url: str, dest_db_path: str):
     sessions = source_session.query(v0_schema.StorageSession).all()
     for item in sessions:
       dest_cursor.execute(
-          "INSERT INTO sessions (app_name, user_id, id, state, create_time,"
-          " update_time) VALUES (?, ?, ?, ?, ?, ?)",
+          "INSERT INTO sessions (app_name, user_id, id, state, title,"
+          " create_time, update_time) VALUES (?, ?, ?, ?, ?, ?, ?)",
           (
               item.app_name,
               item.user_id,
               item.id,
               json.dumps(item.state),
+              item.title,
               item.create_time.replace(tzinfo=timezone.utc).timestamp(),
               item.update_time.replace(tzinfo=timezone.utc).timestamp(),
           ),

src/google/adk/sessions/schemas/v1.py

@@ -88,6 +88,9 @@ class StorageSession(Base):
   state: Mapped[MutableDict[str, Any]] = mapped_column(
       MutableDict.as_mutable(DynamicJSON), default={}
   )
+  title: Mapped[Optional[str]] = mapped_column(
+      String(DEFAULT_MAX_VARCHAR_LENGTH), nullable=True
+  )
 
   create_time: Mapped[datetime] = mapped_column(
       PreciseTimestamp, default=func.now()
@@ -139,6 +142,7 @@ def to_session(
         state=state,
         events=events,
         last_update_time=self.update_timestamp_tz,
+        title=self.title,
     )
 
 

src/google/adk/sessions/session.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 from typing import Any
+from typing import Optional
 
 from pydantic import alias_generators
 from pydantic import BaseModel
@@ -48,3 +49,5 @@ class Session(BaseModel):
   call/response, etc."""
   last_update_time: float = 0.0
   """The last update time of the session."""
+  title: Optional[str] = None
+  """The title of the session."""