Manage sessions using Google Cloud console or API calls

This section describes how to use Vertex AI Agent Engine Sessions to manage sessions using the Google Cloud console or direct API calls. You can use the Google Cloud console or direct API calls if you don't want to use an ADK agent to manage sessions.

To manage sessions using the ADK agent, see Manage sessions with Agent Development Kit.

Create a Vertex AI Agent Engine instance

To access Vertex AI Agent Engine Sessions, you need use an Vertex AI Agent Engine instance. You don't need to deploy any code to start using Sessions. Without code deployment, creating a Vertex AI Agent Engine instance only takes a few seconds.

If you don't have an existing Vertex AI Agent Engine instance, create one using the following code:

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with Sessions later on.
print(agent_engine.api_resource.name)

Replace the following:

PROJECT_ID: Your project ID.
LOCATION: Your region. See the supported regions for Sessions.

List sessions

List sessions associated with your Vertex AI Agent Engine instance.

Google Cloud console

For deployed agents, you can use the Google Cloud console to list sessions associated with your agent:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Sessions tab. A list of sessions displays by ID.

Vertex AI SDK for Python

for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
    config={"filter": "user_id=USER_ID"},
):
    print(session)

USER_ID: Choose your own user ID with a character limit of 128. For example, user-123.

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you created your Agent Engine instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.

HTTP method and URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

You should see a list of sessions returned.

Optionally, to list sessions for a specific user, you can add the query parameter ?filter=user_id=\"USER_ID\", where USER_ID is the ID of the user you want to query.

Create a session

Create a session associated with a user ID.

Google Cloud console

For deployed agents, you can use the Google Cloud console to create sessions:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Playground tab.
Click New session to create a new session.

Vertex AI SDK for Python

session = client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
)

where USER_ID is the user ID you defined. For example, user-123.

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you created your Agent Engine instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.
USER_ID: the user ID you defined. For example, sessions-agent.

HTTP method and URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

Request JSON body:

{
  "userId": USER_ID
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

PowerShell

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

You should receive a long-running operation that you can query to check the creation status of your session.

Get a session

Get a specific session associated with your Vertex AI Agent Engine instance.

Google Cloud console

For deployed agents, you can use the Google Cloud console to create sessions:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Playground tab.
Click the Sessions tab. A list of sessions displays by ID.
Click the session you want to view in more detail.

Vertex AI SDK for Python

session = client.agent_engines.sessions.get(
    name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID',  # Required
    user_id=USER_ID, # Required
)
# session.name will correspond to
#   'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID'

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you created your Agent Engine instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.
SESSION_ID: The resource ID of the session you want to retrieve. You can get the session ID from the response you received when you created the session.

HTTP method and URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

In the response, you should see information about your session.

Delete a session

Delete a session associated with your Vertex AI Agent Engine instance.

Google Cloud console

For deployed agents, you can use the Google Cloud console to delete sessions associated with your agent:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Sessions tab. A list of sessions displays by ID.
Click the more actions menu () of the session you want to delete.
Click Delete.
Click Delete session.

Vertex AI SDK for Python

client.agent_engines.sessions.delete(name=session.name)

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you want to create the Example Store instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.
SESSION_ID: The resource ID of the session you want to retrieve.

HTTP method and URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

To send your request, choose one of these options:

curl

Execute the following command:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

List events in a session

List events in a session associated with your Vertex AI Agent Engine instance.

Google Cloud console

For deployed agents, you can use the Google Cloud console to create sessions:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Playground tab.
Click the Sessions tab. A list of sessions displays by ID.
Click the session you want to view in more detail.
Click the Events tab to view the events associated with the session.

Vertex AI SDK for Python

for session_event in client.agent_engines.list_session_events(
    name=session.name,
):
    print(session_event)

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you created your Agent Engine instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.
SESSION_ID: The resource ID of the session you want to retrieve.

HTTP method and URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events" | Select-Object -Expand Content

In the response, you should see a list of events associated with your session.

Append an event to a session

Append an event to a session associated with an Vertex AI Agent Engine instance.

Google Cloud console

For deployed agents, you can use the Google Cloud console to create sessions:

In the Google Cloud console, go to the Vertex AI Agent Engine page.

Go to Agent Engine

Agent Engine instances that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.
Click the name of your Agent Engine instance.
Click the Playground tab.
Click the Sessions tab. A list of sessions displays by ID.
Click the session you want to view in more detail.
Click the Events tab to view the events associated with the session.
Type a message and press Enter to add a new event to the session.

Vertex AI SDK for Python

import datetime

client.agent_engines.sessions.events.append(
    name=session.name,
    author="user",                                              # Required.
    invocation_id="1",                                          # Required.
    timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required.
    config={
        "content": {
            "role": "user",
            "parts": [{"text": "hello"}]
        },
    },
)

REST

Before using any of the request data, make the following replacements:

PROJECT_ID: Your project ID.
LOCATION: The region where you created your Agent Engine instance.
AGENT_ENGINE_ID: The resource ID of your Agent Engine instance.
SESSION_ID: The resource ID of the session you want to append events to.
AUTHOR: The author of the event. This can be 'user', or an agent name.
INVOCATION_ID: An identifier of an invocation.
TIMESTAMP: The timestamp of the event.

HTTP method and URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID:appendEvent

Request JSON body:

{
  "author": AUTHOR,
  "invocationId": INVOCATION_ID,
  "timestamp": TIMESTAMP,
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID:appendEvent"

PowerShell

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID:appendEvent" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

Clean up

To clean up all resources used in this project, you can delete the Vertex AI Agent Engine instance along with its child resources:

agent_engine.delete(force=True)

Manage sessions using Google Cloud console or API calls Stay organized with collections Save and categorize content based on your preferences.

Create a Vertex AI Agent Engine instance

List sessions

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

Create a session

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

Get a session

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

Delete a session

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

List events in a session

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

Append an event to a session

Google Cloud console

Vertex AI SDK for Python

REST

curl

PowerShell

Clean up

Manage sessions using Google Cloud console or API calls