# How to Use the Anthropic SDK with Google Vertex AI: Complete Setup Guide

> Integrate the Anthropic SDK with Google Vertex AI using AnthropicVertex client classes. Authenticate easily with Application Default Credentials and deploy Claude models today.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Use the `AnthropicVertex` or `AsyncAnthropicVertex` client classes from the `anthropic[vertex]` extra to authenticate with Google Application Default Credentials and call Claude models hosted on Vertex AI.**

The `anthropics/anthropic-sdk-python` repository provides specialized client classes that bridge the standard Anthropic API interface with Google Vertex AI's model-hosting infrastructure. These clients handle the complex request transformation, authentication, and URL rewriting required to communicate with Vertex AI endpoints, allowing you to use familiar SDK patterns while targeting Google's managed infrastructure.

## Installing the Vertex AI Extension

The Vertex AI integration requires additional dependencies not included in the base SDK installation. You must install the `vertex` extra to access the Google authentication libraries and Vertex-specific client implementations.

```bash
pip install "anthropic[vertex]"

```

If you attempt to use the Vertex clients without this extra, the SDK raises a helpful error in [`src/anthropic/lib/vertex/_auth.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/vertex/_auth.py) directing you to install with `pip install anthropic[vertex]`.

## Authentication and Client Initialization

The `AnthropicVertex` and `AsyncAnthropicVertex` classes extend `BaseVertexClient` (located in [`src/anthropic/lib/vertex/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/vertex/_client.py)) to manage Google Cloud authentication and regional endpoint configuration.

### Environment Variable Configuration

The client automatically detects configuration from environment variables, following Google's standard patterns:

- **`CLOUD_ML_REGION`** – Specifies the Vertex AI region (e.g., `us-central1`, `us-east5`)
- **`ANTHROPIC_VERTEX_PROJECT_ID`** – Your Google Cloud project ID
- **`ANTHROPIC_VERTEX_BASE_URL`** – Optional override for the generated endpoint URL

```python
from anthropic import AnthropicVertex

# Reads CLOUD_ML_REGION and ANTHROPIC_VERTEX_PROJECT_ID from environment

client = AnthropicVertex()

```

### Explicit Configuration

You can bypass environment variables by passing `region` and `project_id` directly to the constructor:

```python
client = AnthropicVertex(
    region="us-central1",
    project_id="my-gcp-project-123"
)

```

When the `project_id` is not provided via argument or environment variable, the client attempts to infer it from the loaded Google credentials in [`src/anthropic/lib/vertex/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/vertex/_client.py).

### Custom Credentials

For advanced use cases, supply a pre-configured Google credentials object to bypass Application Default Credentials:

```python
from google.auth.credentials import Credentials
from anthropic import AnthropicVertex

creds = Credentials(
    token="ya29.a0ARrdaM...",
    expired=False,
    refresh_token=None
)

client = AnthropicVertex(credentials=creds)

```

The [`_auth.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/_auth.py) module handles token refresh automatically, injecting a bearer token into the `Authorization` header before each request.

## Making API Calls

Once initialized, the Vertex clients expose the same `messages` and `beta` resources as the standard Anthropic client. The SDK handles request translation transparently.

### Synchronous Requests

Use `AnthropicVertex` for standard synchronous operations. The example below demonstrates calling a model hosted on Vertex AI:

```python
from anthropic import AnthropicVertex

client = AnthropicVertex()

response = client.messages.create(
    model="claude-sonnet-4@20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

print(response.content)

```

*See the complete example in [`examples/vertex.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/vertex.py) for additional context.*

### Asynchronous Requests

For high-concurrency applications, use `AsyncAnthropicVertex` with `async`/`await` patterns:

```python
import asyncio
from anthropic import AsyncAnthropicVertex

async def main():
    client = AsyncAnthropicVertex()
    
    response = await client.messages.create(
        model="claude-sonnet-4@20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello from async!"}]
    )
    
    print(response.to_json())

asyncio.run(main())

```

Both sync and async implementations reuse the existing `Stream` and `AsyncStream` infrastructure for handling streaming responses.

## How Request Rewriting Works

The Vertex client transforms standard Anthropic API calls into Vertex AI-compatible requests through the `_prepare_options` method in [`src/anthropic/lib/vertex/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/vertex/_client.py).

**URL Transformation**

Standard Anthropic paths like `/v1/messages` or `/v1/messages/count_tokens` are rewritten to Vertex's publishing format:

```

projects/{project_id}/locations/{region}/publishers/anthropic/models/{model}:rawPredict

```

For streaming requests, the endpoint uses `:streamRawPredict` instead of `:rawPredict`.

**Request Flow**

1. The client loads Google credentials and generates an access token
2. `_prepare_options` validates that `project_id` is available (raising an error if missing)
3. The method constructs the full Vertex AI URL using the region and project ID
4. The request executes via `httpx` with standard retry logic inherited from `BaseClient`

This translation layer allows you to use standard SDK parameters (`max_tokens`, `messages`, `system` prompts) without modifying your code for Vertex-specific requirements.

## Error Handling and Dependencies

The Vertex client relies on the SDK's standard exception hierarchy defined in [`src/anthropic/_exceptions.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_exceptions.py). When Vertex AI returns HTTP errors (such as authentication failures or quota limits), the client maps these to familiar Anthropic exception types.

**Important Dependencies**

- **google-auth** – Handles OAuth2 token generation and refresh cycles
- **httpx** – Underlying HTTP client for all requests

If `google-auth` is not installed, the initialization fails with a clear message pointing to the `anthropic[vertex]` installation requirement.

## Summary

- **Install** the Vertex extension using `pip install "anthropic[vertex]"` to access `AnthropicVertex` and `AsyncAnthropicVertex`
- **Authenticate** using Google Application Default Credentials, environment variables (`CLOUD_ML_REGION`, `ANTHROPIC_VERTEX_PROJECT_ID`), or explicit constructor arguments
- **Initialize** clients identically to standard Anthropic clients—they share the same `messages.create()` interface
- **Understand** that requests automatically rewrite to Vertex's `rawPredict` endpoints via `_prepare_options` in [`src/anthropic/lib/vertex/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/vertex/_client.py)
- **Reuse** existing async patterns and streaming infrastructure without code changes

## Frequently Asked Questions

### Do I need to modify my existing Anthropic SDK code to use Vertex AI?

No. The `AnthropicVertex` client maintains API parity with the standard `Anthropic` client. Your existing code for creating messages, handling streaming, and managing token counts works without modification. The client intercepts requests in `_prepare_options` and translates them to Vertex AI's format automatically.

### What authentication methods does the Vertex client support?

The client supports Google Application Default Credentials (ADC) via the `google-auth` library, explicit credential objects passed to the `credentials` parameter, and implicit project detection from your GCP environment. If no credentials are provided, the SDK attempts to load them from your environment using standard Google Cloud authentication chains.

### Which Vertex AI regions support Anthropic models?

The region must be specified via the `CLOUD_ML_REGION` environment variable or the `region` constructor argument. Common valid regions include `us-central1`, `us-east5`, and `europe-west1`, though availability depends on your Google Cloud project and model provisioning. The client constructs the endpoint URL as `projects/{project_id}/locations/{region}/publishers/anthropic/models/{model}`.

### Can I use streaming and tool use with the Vertex client?

Yes. The `AnthropicVertex` and `AsyncAnthropicVertex` clients fully support streaming responses via `stream=True` and the beta tools API. The streaming infrastructure reuses the SDK's standard `Stream` class, routing through Vertex's `:streamRawPredict` endpoint while maintaining identical response parsing to direct Anthropic API calls.