One-shot Gemini (or Claude) prompt via GCP Vertex AI (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).

vertex-bot

One-shot Gemini (or Claude) prompt via GCP Vertex AI (@theokit/sdk Adoption Roadmap #8; ADRs D286-D302).

Setup

Enable Vertex AI API in your GCP project: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com.
Grant your principal the Vertex AI User role (roles/aiplatform.user).

Authenticate via ADC (Application Default Credentials):

gcloud auth application-default login
gcloud config set project <your-gcp-project>

(Optional, production) Use a service account instead:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

Copy .env.example to .env and set GOOGLE_CLOUD_PROJECT.

Run

cp .env.example .env
# fill GOOGLE_CLOUD_PROJECT
pnpm install
pnpm run run                                            # default question
pnpm run run "What's 2+2?"
VERTEX_MODEL=vertex/anthropic/claude-sonnet-4-5@20250929 pnpm run run  # Claude on Vertex

Model IDs

Gemini (OpenAI-compat path, D291): vertex/google/gemini-2.0-flash-001
Claude (:rawPredict path, D292): vertex/anthropic/claude-sonnet-4-5@20250929

Locations

us-central1, europe-west4, asia-southeast1, etc — regional routing.
global — cross-region for Anthropic (Vertex global endpoint with D293 baseUrl fix).

v1 limitations (documented)

google-auth-library required peer dep (D288) — repo archived Nov 2025 but security-patched.
OpenAI-compat path drops unsupported params silently (D291) — e.g. recursive JSON schemas in response_format. Documented in Vertex's own docs.
Anthropic on Vertex is non-streaming in v1 — :streamRawPredict deferred to v1.x; v1 always uses :rawPredict.
No Workload Identity Federation walkthrough in v1 (D297) — ADC chain resolves it transparently, but the GCP-side setup is out of scope.
No Service Account JSON file generation tooling (D299) — user provides via GOOGLE_APPLICATION_CREDENTIALS.

Code

run.ts

/**
 * GCP Vertex AI demo (Adoption Roadmap #8; ADRs D286-D302).
 *
 * Sends a one-shot prompt to Gemini (or Claude on Vertex) and prints the reply.
 * Uses Application Default Credentials via `google-auth-library`.
 *
 * Run:
 *   gcloud auth application-default login
 *   cp .env.example .env  # fill GOOGLE_CLOUD_PROJECT
 *   pnpm install
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

if (process.env.GOOGLE_CLOUD_PROJECT === undefined) {
  console.error(
    "GOOGLE_CLOUD_PROJECT is required. Set it in .env or run " +
      "`gcloud config set project <id>`.",
  );
  process.exit(1);
}

const modelId =
  process.env.VERTEX_MODEL ?? "vertex/google/gemini-2.0-flash-001";

// For Vertex, apiKey isn't strictly used — ADC resolves the OAuth token
// lazily inside the client. We pass an empty placeholder.
const agent = await Agent.create({
  apiKey: "vertex-adc",
  model: { id: modelId },
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
  name: "vertex-bot",
  systemPrompt: "You are a concise assistant. Reply in one short sentence.",
});

const question = process.argv[2] ?? "Qual é a capital do Brasil?";
console.log(
  `[vertex] model=${modelId} project=${process.env.GOOGLE_CLOUD_PROJECT} ` +
    `location=${process.env.GOOGLE_CLOUD_LOCATION ?? "us-central1"} question="${question}"`,
);

const run = await agent.send(question);
const result = await run.wait();
console.log(`[vertex] status=${result.status} resultLen=${(result.result ?? "").length}`);
console.log(result.result ?? "(no reply)");

await agent.dispose();

Run

cd examples/vertex-bot
cp .env.example .env  # fill in keys
pnpm install
pnpm run run

Repository

examples/vertex-bot

vertex-bot

On this page