Vertex AI SDK for Node.js

@google-cloud/vertexai is Google’s official Node.js and TypeScript client for calling Gemini models through the Vertex AI API. It exposes a VertexAI entry point that authenticates against a Google Cloud project and location, then hands back GenerativeModel instances for streamed or non-streamed text generation, multi-turn chat sessions, function calling, and cached content, all typed against the Gemini request/response shapes.

The SDK is formally deprecated as of June 24, 2025 and scheduled for removal on June 24, 2026; internally it now delegates to the newer @google/genai package, and Google’s own README points integrators at the Gen AI SDK for new work. It remains useful for understanding or maintaining existing Vertex AI integrations built before the migration, but is not recommended for new projects.

What You Get

• A VertexAI client that wires up Google Cloud auth (ADC, service accounts, or custom GoogleAuthOptions) without hand-rolling OAuth token refresh
• GenerativeModel and GenerativeModelPreview classes for streamed (generateContentStream) and non-streamed (generateContent) Gemini calls
• A ChatSession abstraction (startChat()) that keeps conversation history and re-sends it on each turn
• Function calling / tool-use types (FunctionDeclaration, Tool, safety settings, generation config) shared with the rest of Google’s Gemini tooling
• A CachedContent resource client for creating and referencing server-side cached context to cut down repeated token costs

Common Use Cases

• Maintaining an existing Node.js backend that already calls Gemini through Vertex AI and isn’t ready to migrate to @google/genai
• Building server-side chat features with multi-turn context via ChatSession
• Streaming Gemini responses to a frontend for perceived-latency-sensitive UX
• Calling Gemini with function/tool definitions for structured, agentic responses

Under The Hood

Architecture - The package is organized as a thin client layer over Vertex AI’s REST endpoints: src/vertex_ai.ts defines the VertexAI entry class, src/models/generative_models.ts and src/models/chat_session.ts implement the model and chat abstractions, and src/functions/ (generate_content.ts, count_tokens.ts, pre_fetch_processing.ts, post_fetch_processing.ts, post_request.ts) handles request construction, execution, and response normalization (including SSE stream parsing for generateContentStream). src/resources/cached_contents.ts implements the cached-content resource, and src/types/ centralizes the request/response and error type definitions shared across the client.

Tech Stack - Written in TypeScript, compiled to CommonJS (build/src/index.js), targeting Node.js 20+. Runtime dependencies are minimal: google-auth-library for Application Default Credentials and OAuth, and, notably, @google/genai — the successor SDK the package now wraps internally rather than talking to Vertex AI’s REST API directly in newer releases. Dev tooling is Google’s standard gts (Google TypeScript Style) preset, ESLint 9 with the flat config, Prettier, and JSDoc for API docs.

Code Quality - Tests live under test/ and run through Jasmine (vertex_ai_test.ts, index_test.ts), covering the top-level VertexAI class and module exports; a separate system_test/ directory covers integration-level scenarios, and src/testing/fake_google_auth.ts provides a fake credentials provider for isolating auth from network calls in unit tests. Coverage is generated via nyc. The codebase is small and single-purpose (~12k lines including tests), consistent with a client library rather than an application.

API Design - The public surface mirrors Google’s other generative AI SDKs (constructor takes project/location, getGenerativeModel() returns a model handle, generateContent/generateContentStream take a GenerateContentRequest), which keeps the learning curve low for anyone who has used @google/generative-ai or the Python equivalents. The most notable ergonomic issue is now structural: the constructor logs a deprecation warning on every instantiation, and the README leads with a migration notice rather than usage instructions, signalling that new integrations should look elsewhere.