Repository navigation
Add explicit ttl / expire_time parameter to AdkApp.async_create_session for remote Agent Engine deployments #4594
Description
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
-
Using
**kwargspass-through:adk_app.async_create_session(user_id="u_123", expire_time="7200s"). This works locally becauseVertexAiSessionService.create_session()merges kwargs into config. However, it's undocumented for the remote proxy path and may silently fail (session created without TTL). -
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 inasyncio.to_thread()for async backends.
Additional context
- The Manage sessions with ADK documentation shows TTL support via
VertexAiSessionService.create_session(ttl=...)but not viaAdkApp.async_create_session(). - The Use an ADK agent documentation does not mention TTL at all for the remote
adk_appAPI. - Source reference:
VertexAiSessionService.create_sessionalready documentsexpire_timein its kwargs docstring, but this is not surfaced throughAdkApp.
Activity
rahulmansharamani14 commentedon Mar 1, 2026
@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 commentedon Mar 1, 2026
@ivanparra-servi the
async_create_sessionschema incli_deploy.py:247-255only exposesuser_id,session_id, andstate, sottl/expire_timeare 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 thatpropertiesdict; the server-sideVertexAiSessionService.create_session()already handles both viaconfig.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 commentedon Mar 1, 2026
@yeesian Please have a look into it once.
rahulmansharamani14 commentedon Mar 4, 2026
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 treatexpire_timeas an absolute ISO 8601 timestamp:adk-python/src/google/adk/sessions/vertex_ai_session_service.py
Lines 97 to 99 in 2780ae2
But the issue's proposed usage shows
expire_time="7200s"(a duration string), which is semantically whatttlwould 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_timeas well?Also @yeesian - any additional concerns from the team review before I proceed?
yeesian commentedon Jun 1, 2026
Hi @rahulmansharamani14 so sorry for my slow response, no concerns from the team for you to proceed, thank you so much!