Add explicit ttl / expire_time parameter to AdkApp.async_create_session for remote Agent Engine deployments

[ivanparra-servi]

Feature request

Problem

When interacting with a deployed ADK agent via the Vertex AI SDK (client.agent_engines.get()), there is no documented or explicit way to set a session TTL through adk_app.async_create_session().

The current signature is:

async_create_session(*, user_id, session_id=None, state=None, **kwargs)

While VertexAiSessionService.create_session() does support expire_time via **kwargs (which merges them into the config dict), this only works in the local execution path. When calling async_create_session on a remote AgentEngine instance (obtained via client.agent_engines.get()), the call goes through a REST proxy (reasoningEngines/{id}:query), and there is no guarantee or documentation that arbitrary kwargs like expire_time or ttl are forwarded correctly to the server-side session service.

As a result, to set session TTL on a deployed agent, users must bypass adk_app.async_create_session() entirely and use the lower-level Sessions API:

session = client.agent_engines.sessions.create(
    name=agent_resource_name,
    user_id=user_id,
    config={"expire_time": "7200s"},
)
session_id = session.name.split("/")[-1]

This works but breaks the consistency of the adk_app.* API surface and requires mixing two different APIs (adk_app for querying, client.agent_engines.sessions for session creation).

"Solution"

Add explicit ttl and/or expire_time parameters to AdkApp.async_create_session():

session = await adk_app.async_create_session(
    user_id="user_123",
    ttl="7200s",          # Session auto-deletes after 2 hours
    # or
    expire_time="2026-03-01T00:00:00Z",  # Session expires at this time
)

This should work both locally (direct call) and remotely (through the REST proxy), ensuring the TTL parameter is included in the serialized input payload and properly forwarded to the underlying VertexAiSessionService.

Alts

1. Using **kwargs pass-through: adk_app.async_create_session(user_id="u_123", expire_time="7200s"). This works locally because VertexAiSessionService.create_session() merges kwargs into config. However, it's undocumented for the remote proxy path and may silently fail (session created without TTL).

2. Using the Sessions API directly: client.agent_engines.sessions.create(config={"expire_time": "7200s"}). This works but requires mixing two API surfaces and wrapping the synchronous call in asyncio.to_thread() for async backends.

Additional context

• The Manage sessions with ADK documentation shows TTL support via VertexAiSessionService.create_session(ttl=...) but not via AdkApp.async_create_session().
• The Use an ADK agent documentation does not mention TTL at all for the remote adk_app API.
• Source reference: VertexAiSessionService.create_session already documents expire_time in its kwargs docstring, but this is not surfaced through AdkApp.

[rahulmansharamani14]

@ivanparra-servi this makes total sense. @surajksharma07 could you take a look and let us know if this is something worth pursuing? Happy to pick it up and open a PR!

[surajksharma07]

@ivanparra-servi the async_create_session schema in cli_deploy.py:247-255 only exposes user_id, session_id, and state, so ttl/expire_time are silently dropped when the call goes through the remote Agent Engine REST proxy.

The fix is to add 'ttl': {'type': 'string', 'nullable': True} and 'expire_time': {'type': 'string', 'nullable': True} to that properties dict; the server-side VertexAiSessionService.create_session() already handles both via config.update(kwargs) so no other changes are needed.

@rahulmansharamani14 go ahead and open the PR — that one-file change is the right landing spot.

Team is looking more into it.

[surajksharma07]

@yeesian Please have a look into it once.

[rahulmansharamani14]

Thanks @surajksharma07 for the confirmation. Planning to open the PR!

Before I do, one quick clarification on parameter semantics. The existing VertexAiSessionService.create_session() docstring and its unit test treat expire_time as an absolute ISO 8601 timestamp:

adk-python/src/google/adk/sessions/vertex_ai_session_service.py

Lines 97 to 99 in 2780ae2

	**kwargs: Additional arguments to pass to the session creation. E.g. set
	expire_time='2025-10-01T00:00:00Z' to set the session expiration time.
	See https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1beta1/projects.locations.reasoningEngines.sessions

But the issue's proposed usage shows expire_time="7200s" (a duration string), which is semantically what ttl would be. Should we add both as separate typed fields:

• ttl : string - duration (e.g., "7200s")
• expire_time : string - absolute timestamp (e.g., "2026-03-01T00:00:00Z")

Or does the underlying Vertex AI sessions API accept duration-style values under expire_time as well?

Also @yeesian - any additional concerns from the team review before I proceed?

[yeesian]

Hi @rahulmansharamani14 so sorry for my slow response, no concerns from the team for you to proceed, thank you so much!