Vertex AI Sessions

Vertex AI Session Service provides cloud-managed session storage using Google Cloud infrastructure. Sessions, events, and state are stored in Google's managed systems without requiring you to set up databases or manage infrastructure.

Best for: Production applications needing enterprise reliability, teams already using Vertex AI services, or applications requiring automatic scaling.

Requirements: Google Cloud account with billing, internet connectivity for API calls.

Using Vertex AI Session Service

ADK-TS offers two ways to configure Vertex AI sessions:

With AgentBuilder (Recommended)

// Initialize Vertex AI session service
const sessionService = new VertexAiSessionService({
  project: "my-project",
  location: "us-central1",
  agentEngineId: "my-reasoning-engine-id",
});

// Build agent with Vertex AI sessions
const { runner } = await AgentBuilder.create("travel-assistant")
  .withModel("gemini-2.0-flash-exp")
  .withSessionService(sessionService, {
    userId: "user123",
    appName: "my-travel-agent",
  })
  .build();

With LlmAgent Directly

// Initialize Vertex AI session service
const sessionService = new VertexAiSessionService({
  project: "my-project",
  location: "us-central1",
  agentEngineId: "my-reasoning-engine-id",
});

// Create agent with Vertex AI sessions
const agent = new LlmAgent({
  name: "travel-assistant",
  description: "Assists users with travel planning and recommendations",
  model: "gemini-2.0-flash-exp",
  sessionService,
  userId: "user123",
  appName: "my-travel-agent",
});

Prerequisites

Before using Vertex AI sessions, ensure you have:

Google Cloud Project with billing enabled and Vertex AI API activated
Reasoning Engine deployed in Vertex AI (you'll need the project ID, region, and engine ID)

Authentication configured via Application Default Credentials:

# For local development
gcloud auth application-default login

IAM Permissions: Your account needs the roles/aiplatform.user role
Environment Variable set to point to your credentials file:
```
export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
```

For production, use service accounts instead of user credentials. See Google Cloud IAM documentation for details.

Configuration

Initialize Service

import { VertexAiSessionService } from "@iqai/adk";

const sessionService = new VertexAiSessionService({
  project: "your-gcp-project-id",
  location: "us-central1",
  agentEngineId: "your-reasoning-engine-id",
});

Options:

project: Google Cloud project ID (optional if using full paths)
location: GCP region like us-central1 (optional if using full paths)
agentEngineId: Reasoning Engine ID (optional if using full paths)

Resource Path Formats

The appName parameter accepts two formats:

Simple ID (requires configured project/location):

await sessionService.createSession("12345", "user123", {});

Full path (overrides configured defaults):

const fullPath =
  "projects/my-project/locations/us-central1/reasoningEngines/12345";
await sessionService.createSession(fullPath, "user123", {});

Working with Sessions

Create Session

Vertex AI generates session IDs automatically—you cannot provide custom IDs.

const session = await sessionService.createSession(
  "my-travel-agent",
  "user123",
  {
    current_step: "welcome",
    "user:language": "en",
    "user:timezone": "America/New_York",
  },
);

Get Session

const session = await sessionService.getSession(
  "my-travel-agent",
  "user123",
  "session-abc-123",
);

List Sessions

Returns session metadata (ID, lastUpdateTime). Use getSession() for full session data including events.

const response = await sessionService.listSessions(
  "my-travel-agent",
  "user123",
);

console.log(`Found ${response.sessions.length} sessions`);

Append Events

import { Event } from "@iqai/adk";

const event = new Event({
  content: {
    role: "user",
    parts: [{ text: "I want to book a flight to Paris" }],
  },
});

await sessionService.appendEvent(session, event);

Delete Session

await sessionService.deleteSession(
  "my-travel-agent",
  "user123",
  "session-abc-123",
);

Managing State

Initial State

Create sessions with state using all ADK-TS prefixes:

const session = await sessionService.createSession("my-agent", "user123", {
  current_page: "checkout",
  "user:theme": "dark",
  "app:version": "2.0.0",
  "temp:calculation": 42, // Not persisted
});

Updating State

Update state using stateDelta in events:

import { Event, EventActions } from "@iqai/adk";

const event = new Event({
  actions: new EventActions({
    stateDelta: {
      current_page: "confirmation",
      "user:last_purchase": new Date().toISOString(),
    },
  }),
});

await sessionService.appendEvent(session, event);

Next Steps

💬 Session

Learn about session lifecycle and management

🗂️ State

Master state storage and scoping

🧠 Memory

Add Vertex AI RAG for long-term memory

Vertex AI Sessions

💬 Session

🗂️ State

🧠 Memory

On this page