Skip to content

feat(sessions): add a client-set title to sessions - #6501

Open
answersamir wants to merge 1 commit into
google:mainfrom
answersamir:session-title
Open

feat(sessions): add a client-set title to sessions#6501
answersamir wants to merge 1 commit into
google:mainfrom
answersamir:session-title

Conversation

@answersamir

Copy link
Copy Markdown

Summary

Adds an optional, client-set title to the Session model and threads it through every built-in session service and the web server, so frontends can show readable titles in session/chat-history lists instead of UUIDs.

This is the manual / client-set variant of #1340 (the service stores a title the caller provides; ADK does not auto-generate it), and builds on the approach of the closed #3703.

What's included

  • Model: Session.title (nullable, defaults to None); surfaced by get_session and list_sessions.
  • Service interface: BaseSessionService.update_session_title(...) as a concrete method that raises NotImplementedError by default — mirroring get_user_state, so existing third-party BaseSessionService subclasses keep working without changes (no new abstract method).
  • Implementations: InMemorySessionService, DatabaseSessionService and SqliteSessionService implement it. VertexAiSessionService raises NotImplementedError, because the managed Agent Engine Session API exposes no client-set title (same precedent as its get_user_state).
  • HTTP: the existing PATCH /apps/{app_name}/users/{user_id}/sessions/{session_id} endpoint accepts an optional title (and state_delta is now optional), so a title can be set with or without a state change — no new route.

Existing-database handling (no schema-version bump)

title is a nullable, additive column, so this does not bump the DB schema version. Because metadata.create_all() never adds a column to an existing table, DatabaseSessionService gains a small additive column reconciler, _ensure_schema_columns_exist, that mirrors the existing _ensure_schema_indexes_exist index healer — an existing database gains the title column in place on the next connect (each ALTER guarded by a SAVEPOINT so concurrent instances don't poison the setup transaction). SqliteSessionService does the same via ALTER TABLE ... ADD COLUMN. Legacy v0 databases are left untouched.

Behavior note

Setting a title preserves the session's update_time — a title is display metadata and must not invalidate an in-flight copy of the session, which would otherwise trip the stale-writer check on the next append_event.

Tests

  • Parametrized update_session_title round-trip, not-found, and "preserves update_time" tests across all four SessionServiceTypes (in-memory, in-memory light-copy, database, sqlite).
  • VertexAiSessionService raises NotImplementedError.
  • Database and Sqlite column-healer tests (an existing DB predating title gains the column; a v0 DB is untouched).
  • Web-server PATCH-with-title and title-only tests.

The full tests/unittests suite passes locally (9567 passed); pyink / isort / ruff / compliance pre-commit checks are clean.

Related

Adds an optional, client-set title to the Session model and threads it
through every built-in session service and the web server, addressing the
long-standing request for readable titles in session/chat-history lists.

- Session.title (nullable, defaults to None); surfaced by get_session and
  list_sessions.
- BaseSessionService.update_session_title is a concrete method that raises
  NotImplementedError by default (mirrors get_user_state), so existing
  third-party subclasses keep working without changes.
- InMemory, Database (SQLAlchemy) and Sqlite services implement it;
  VertexAiSessionService raises NotImplementedError because the managed
  Agent Engine Session API exposes no client-set title.
- DatabaseSessionService adds a nullable title column to the v1 schema and
  reconciles it onto pre-existing databases in place via a new additive
  column healer (_ensure_schema_columns_exist), mirroring the existing index
  healer. SqliteSessionService does the same via ALTER TABLE ADD COLUMN. No
  schema-version bump is needed for a nullable, additive column.
- Setting a title preserves the session's update_time so a rename does not
  invalidate an in-flight session copy (which would trip the stale-writer
  check on the next append_event).
- The existing PATCH .../sessions/{session_id} endpoint accepts an optional
  title (state_delta is now optional as well).

Adds unit tests across all backends, the web server endpoint, and the
database column healer.

Builds on the approach in google#3703 (closed). Addresses google#1340.
@adk-bot adk-bot added the services [Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc label Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

services [Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants