Agent Engine session state update: how to modify state after session creation?

[rohan-kavari]

I am using Vertex AI Agent Engine and creating a session via the synchronous query API.

I create the session using:

Endpoint

POST https://aiplatform.googleapis.com/v1/{name}:query

Payload

{
  "class_method": "create_session",
  "input": {
    "user_id": "<USER_ID>",
    "state": {
      "auth_token": "INITIAL_TOKEN"
    }
  }
}

This successfully creates the session, and the agent can access state.auth_token during execution.

---

Problem

The auth_token stored in state can expire. I want to update or refresh this token later during the same session lifecycle.

When I try to send an updated state while sending messages using the streaming API:

Endpoint

POST https://aiplatform.googleapis.com/v1/{name}:streamQuery

and include state again in the payload, I get the following error:

{
  "code": 498,
  "message": "Runner.run_async() got an unexpected keyword argument 'state'"
}

This suggests that state is not accepted during streamQuery.

---

Questions

1. Is session state immutable after create_session?
2. Is there any supported API or mechanism to update session state after creation?

---

Context

• Agent Engine (Vertex AI)
• Using both query and streamQuery
• Auth token is required by downstream tools invoked by the agent

Any guidance or recommended best practices would be appreciated.

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: Session state is not designed to be overwritten in every API call. The error you're seeing is expected because the streamQuery endpoint does not accept a state argument. The recommended approach for handling expiring credentials is to pass the latest token in the input of each request.

---

Hello @rohan-kavari,

Thank you for the detailed question. I can clarify how session state is managed in the ADK and why you are encountering this behavior.

The error Runner.run_async() got an unexpected keyword argument 'state' occurs because the streamQuery method is not designed to accept the session state. The session state can only be initialized once, at the beginning of a session, via the create_session method. [1, 2]

To answer your questions directly:

1. Is session state immutable after create_session?
   From the perspective of an external caller, you can think of it this way. The state object cannot be replaced by passing a new one in subsequent query or streamQuery calls. The intended mechanism for updating state is for the agent's internal logic (i.e., a tool) to return a state_delta, which is then applied to the existing state by the ADK runtime. [3, 4]

2. Is there any supported API or mechanism to update session state after creation?
   Yes, but the mechanism is internal to the agent's execution. A tool can return an EventActions object containing a state_delta. The ADK runner processes this event and updates the state. [3] There is no public-facing API endpoint for a client to arbitrarily overwrite the session state mid-conversation.

Recommended Best Practice for Expiring Tokens

For your use case of handling an expiring auth_token, the recommended best practice is to manage the token's lifecycle in your client application and pass the most current token with every request.

Instead of storing the token in the session state, include it in the input object for each streamQuery call. Your tools should be designed to retrieve the token from the current turn's input rather than from the session state.

Here’s an example payload for streamQuery:

{
  "input": {
    "user_query": "The user's actual message to the agent",
    "auth_token": "LATEST_UPDATED_TOKEN"
  }
}

This approach ensures that your agent's tools always have access to a valid token for downstream API calls without needing to modify the session state.

I hope this clarifies things!

---

[1] sessions/state.html
[2] vertex_ai_session_service.py
[3] runtime/index.html
[4] adk_web_server.py

[rohan-kavari]

I found out that the payload should be as follows
{ "user_id": user_id, "session_id": session_id, "message": message, "state_delta": { "auth_token": "UPDATED_TOKEN" } }
We need to use state_delta instead of state while updating the state