OpenWikianthropics/anthropic-sdk-typescript

Google Vertex SDK

Purpose and Scope

The Google Vertex SDK package is the Anthropic TypeScript client variant for calling Claude through Google Vertex AI rather than through the direct Anthropic API endpoint. It is published as the public package named @anthropic-ai/vertex-sdk and its README describes it as convenient access to the Claude API via Google Vertex AI. Use this package when your application is already operating inside a Google Cloud project, needs Google authentication, or must send Claude traffic through Vertex AI endpoints. For direct calls to api.anthropic.com, the README points users back to the main @anthropic-ai/sdk package instead. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/package.json

The developer experience intentionally resembles the main Claude SDK. The Vertex client still exposes the familiar messages.create workflow, so application code can construct a conversation with user messages, set a Claude model, choose max_tokens, and receive a message result. The important difference is where transport and authentication are handled. The Vertex package adapts the underlying Anthropic request to Google Cloud’s endpoint shape and obtains Google authorization headers, while the caller continues to work with the SDK’s TypeScript resource interface. This keeps the application-level Claude workflow stable while moving cloud identity, routing, and project scoping into the client configuration. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/src/client.ts, packages/vertex-sdk/tests/client.test.ts

Relevant Source Files

  • packages/vertex-sdk/README.md - User-facing installation, basic usage, authentication examples, and runtime requirements for the Vertex package.
  • packages/vertex-sdk/package.json - Package name, version, build entrypoints, exports, scripts, and dependencies, including the main SDK and google-auth-library.
  • packages/vertex-sdk/src/index.ts - Public entrypoint that re-exports the client and provides AnthropicVertex as the default export.
  • packages/vertex-sdk/src/client.ts - Implementation and public options for AnthropicVertex, including region, project ID, access token, GoogleAuth, AuthClient, base URL, and request adaptation constants.
  • packages/vertex-sdk/tests/client.test.ts - Behavioral tests for endpoint selection, missing region errors, explicit base URL precedence, and middleware observation of Vertex request adaptation.

Installation and Package Shape

Install the Vertex package directly from npm when you want the Google Cloud integration rather than the direct API client. The package metadata identifies @anthropic-ai/vertex-sdk as version 0.19.0, with CommonJS packaging, generated distribution declarations, and public npm publishing enabled. It depends on the main SDK through @anthropic-ai/sdk and on google-auth-library, which matches the authentication examples in the README and the client’s option types. This means the Vertex package is not a separate hand-written API surface; it extends the core SDK behavior while replacing authentication and endpoint details for Google Vertex AI. Sources: packages/vertex-sdk/package.json, packages/vertex-sdk/src/client.ts

npm install @anthropic-ai/vertex-sdk

The public import is deliberately small. The entrypoint exports everything from the client module and also exports AnthropicVertex as the default export. In practice, most examples use a named import, but both styles are supported by the package entrypoint. The package exports map also provides root import support plus wildcard JavaScript and module outputs from the built dist directory, so TypeScript and JavaScript consumers can import the package through the normal package name rather than reaching into source files. Sources: packages/vertex-sdk/src/index.ts, packages/vertex-sdk/package.json

import { AnthropicVertex } from '@anthropic-ai/vertex-sdk';
 
const client = new AnthropicVertex({
  region: 'us-central1',
  projectId: 'my-project-id',
});

Authentication, Project, and Region Configuration

The client can be constructed with explicit region and projectId values, or it can read environment configuration. The README states that a default new AnthropicVertex() reads CLOUD_ML_REGION and ANTHROPIC_VERTEX_PROJECT_ID, then goes through the standard Google authentication flow. The client option type also allows accessToken, which is useful when a caller has already obtained a token and wants to bypass credential discovery. Region is required either as an option or from CLOUD_ML_REGION; tests assert that construction fails with a clear error when no region is available. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/src/client.ts, packages/vertex-sdk/tests/client.test.ts

Authentication has three documented levels. The simplest path relies on default Google Cloud authentication, where local application default credentials, service account credentials, or environment-provided credentials are handled by Google’s standard libraries. The next level accepts a custom GoogleAuth instance through the googleAuth option, allowing callers to set scopes such as the Cloud Platform scope or provide a service account key file. The most advanced path accepts a pre-configured AuthClient, which the README and client comments highlight for impersonation-style workflows. These options are alternatives for fitting the same SDK surface into different Google Cloud identity models. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/src/client.ts

import { AnthropicVertex } from '@anthropic-ai/vertex-sdk';
import { GoogleAuth } from 'google-auth-library';
 
const client = new AnthropicVertex({
  googleAuth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
    keyFile: '/path/to/service-account.json',
  }),
  region: 'us-central1',
  projectId: 'my-project-id',
});

Endpoint Selection and Vertex Request Adaptation

Endpoint selection is driven by the region unless baseURL is explicitly supplied. The client documentation describes a default base URL based on the region, and the tests make the mapping concrete: global uses https://aiplatform.googleapis.com/v1, us uses https://aiplatform.us.rep.googleapis.com/v1, eu uses https://aiplatform.eu.rep.googleapis.com/v1, and ordinary regional values such as us-central1, europe-west1, or asia-southeast1 use the pattern https://${region}-aiplatform.googleapis.com/v1. Tests also confirm that an explicit baseURL takes precedence over region-derived URLs. Sources: packages/vertex-sdk/src/client.ts, packages/vertex-sdk/tests/client.test.ts

The Vertex client adapts Anthropic-style message calls to the Vertex wire format. The client source defines DEFAULT_VERSION as vertex-2023-10-16 and tracks model endpoints such as /v1/messages and /v1/messages?beta=true. This aligns with the official Vertex AI behavior where Claude’s model is represented in the Google endpoint and the Anthropic version is sent in the request body. The tests describe the middleware boundary as well: user middleware observes a canonical request without Google credentials, while the actual wire request receives the Vertex shape. That distinction helps middleware stay portable while the client handles provider-specific transformation. Sources: packages/vertex-sdk/src/client.ts, packages/vertex-sdk/tests/client.test.ts

Messages Usage Pattern

A first request follows the same high-level Messages API shape used by the main SDK. Create an AnthropicVertex client, then call client.messages.create with a messages array, model, and max_tokens. The README example sends a single user message with the content Hey Claude! and uses a Vertex-style model identifier such as claude-3-5-sonnet-v2@20241022. The example logs the result as JSON, which is a practical pattern when validating credentials, project access, endpoint routing, and model availability in a new Google Cloud environment. Sources: packages/vertex-sdk/README.md

import { AnthropicVertex } from '@anthropic-ai/vertex-sdk';
 
const client = new AnthropicVertex({
  region: 'us-central1',
  projectId: 'my-project-id',
});
 
const result = await client.messages.create({
  messages: [{ role: 'user', content: 'Hey Claude!' }],
  model: 'claude-3-5-sonnet-v2@20241022',
  max_tokens: 300,
});
 
console.log(JSON.stringify(result, null, 2));

When moving code from the direct Anthropic SDK, keep the conversation-building code mostly intact but revisit configuration. The direct SDK centers on an Anthropic API key, while this package omits the core apiKey and authToken options from its client option type and replaces them with Google-oriented credentials. The project and region also matter because Vertex AI authorization and model serving are scoped through Google Cloud. If a request fails before reaching the model, check that the Google credential can access the selected project, that the region matches where the model is available, and that no custom base URL is accidentally overriding the intended endpoint. Sources: packages/vertex-sdk/src/client.ts, packages/vertex-sdk/tests/client.test.ts

Runtime Support and Next Steps

The Vertex README lists TypeScript >= 4.5 and supports Node.js 18 LTS or later, Deno through npm:@anthropic-ai/vertex-sdk, Bun 1.0 or later, Cloudflare Workers, Vercel Edge Runtime, Jest with the Node environment, and Nitro. It also notes that React Native is not supported. For tests, the package uses Jest and mocks google-auth-library so credential loading is not required during client behavior checks. That separation is useful when adding application tests: mock Google credential resolution for unit tests, then reserve real Google Cloud credentials for integration tests. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/package.json, packages/vertex-sdk/tests/client.test.ts

Use this page together with the core Messages documentation when implementing application behavior and with authentication documentation when preparing deployment credentials. A recommended next step is to run the small messages.create example with explicit region and projectId, then switch to the authentication mode that matches your deployment platform: application default credentials for Google-hosted workloads, a scoped GoogleAuth for service account key files, or a pre-built AuthClient for impersonation. After the first successful call, keep provider-specific configuration near client construction so the rest of the codebase can continue using the standard SDK resource methods. Sources: packages/vertex-sdk/README.md, packages/vertex-sdk/src/client.ts

Ask a question...