Vertex AI

Use Google’s Gemini models through Vertex AI — Google Cloud’s enterprise ML platform. Same models as the Gemini API, but with Google Cloud IAM authentication, VPC support, and enterprise compliance.

Use vertex() when you need Google Cloud authentication (service accounts, ADC). Use google() when you have a simple API key.

Setup

Install
Authentication

Vertex AI uses the same SDK as Gemini:

npm install @google/genai

Vertex AI uses Application Default Credentials (ADC). Authenticate via one of:

# Option 1: gcloud CLI (development)
gcloud auth application-default login

# Option 2: Service account key (production)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Set your project and region:

export GOOGLE_CLOUD_PROJECT="my-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"  # optional, defaults to us-central1

Factory

import { vertex } from "@agentium/core";

const model = vertex("gemini-2.0-flash", {
  project: "my-gcp-project",
  location: "us-central1",
});

string

required

The Gemini model identifier (same model IDs as the Gemini API).

object

Optional configuration. See Config below.

Supported Models

Model ID	Description
`gemini-2.5-flash`	Fast, efficient. Great for high-throughput and latency-sensitive apps.
`gemini-2.5-pro`	Highest capability. Best for complex reasoning and long-context tasks.
`gemini-2.0-flash`	Previous generation flash model.

All Gemini models available in your Vertex AI region can be used.

Config

string

required

Google Cloud project ID. Falls back to GOOGLE_CLOUD_PROJECT env var.

string

default:"us-central1"

Google Cloud region. Falls back to GOOGLE_CLOUD_LOCATION env var.

string

Service account key JSON string or file path. If omitted, uses Application Default Credentials.

Example

const model = vertex("gemini-2.5-flash", {
  project: "my-project-id",
  location: "europe-west4",
});

Vertex AI vs Gemini API

Feature	`google()` (Gemini API)	`vertex()` (Vertex AI)
Auth	API key	Google Cloud IAM / ADC
Pricing	Pay-per-use	GCP billing
VPC / Private	No	Yes
Enterprise compliance	Limited	SOC2, HIPAA, etc.
Same models	Yes	Yes
Multi-modal	Yes	Yes

Vertex AI supports the same multi-modal capabilities as the Gemini API — images, audio, and files (including XLSX). All content is processed via inlineData.

Images

import { Agent, vertex, type ContentPart } from "@agentium/core";
import { readFileSync } from "node:fs";

const agent = new Agent({
  name: "vision-agent",
  model: vertex("gemini-2.5-flash", {
    project: "my-project",
    location: "us-central1",
  }),
  instructions: "Describe images in detail.",
});

const imageData = readFileSync("photo.jpg").toString("base64");
const result = await agent.run([
  { type: "text", text: "What's happening in this photo?" },
  { type: "image", data: imageData, mimeType: "image/jpeg" },
] as ContentPart[]);

Audio

const audioData = readFileSync("meeting.mp3").toString("base64");
const result = await agent.run([
  { type: "text", text: "Transcribe this meeting recording and list action items." },
  { type: "audio", data: audioData, mimeType: "audio/mp3" },
] as ContentPart[]);

Files & Documents

Vertex AI supports PDF, CSV, XLSX, and other formats natively:

const result = await agent.run([
  { type: "text", text: "Analyze the quarterly revenue trends." },
  {
    type: "file",
    data: readFileSync("financials.xlsx").toString("base64"),
    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    filename: "financials.xlsx",
  },
] as ContentPart[]);

All multi-modal features work identically to the google() provider. See the Google Gemini docs for the full supported file type list.

Reasoning

Vertex AI Gemini models support thinking/reasoning via the same reasoning config:

const agent = new Agent({
  name: "analyst",
  model: vertex("gemini-2.5-pro", {
    project: "my-project",
    location: "us-central1",
  }),
  reasoning: { enabled: true, budgetTokens: 4000 },
  instructions: "You are a precise financial analyst.",
});

const result = await agent.run("Calculate the IRR of a $10K investment returning $3K/year for 5 years.");
console.log(result.thinking); // Model's step-by-step reasoning
console.log(result.text);     // Final answer

Full Example

import { Agent, vertex, defineTool } from "@agentium/core";
import { z } from "zod";

const agent = new Agent({
  name: "enterprise-assistant",
  model: vertex("gemini-2.5-flash", {
    project: "my-project",
    location: "us-central1",
  }),
  instructions: "You are an enterprise assistant with access to internal tools.",
  tools: [
    defineTool({
      name: "lookup_employee",
      description: "Look up an employee by name",
      parameters: z.object({
        name: z.string().describe("Employee name"),
      }),
      execute: async (args) => `Employee ${args.name} found in Engineering.`,
    }),
  ],
  logLevel: "info",
});

const output = await agent.run("Look up John Smith");
console.log(output.text);

Environment Variables

Variable	Description
`GOOGLE_CLOUD_PROJECT`	Default GCP project ID
`GOOGLE_CLOUD_LOCATION`	Default GCP region (default: `us-central1`)
`GOOGLE_APPLICATION_CREDENTIALS`	Path to service account key JSON

​Vertex AI

​Setup

​Factory

​Supported Models

​Config

​Example

​Vertex AI vs Gemini API

​Multi-Modal Support

​Images

​Audio

​Files & Documents

​Reasoning

​Full Example

​Environment Variables

Vertex AI

Setup

Factory

Supported Models

Config

Example

Vertex AI vs Gemini API

Multi-Modal Support

Images

Audio

Files & Documents

Reasoning

Full Example

Environment Variables