Google Cloud Vertex AI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Google Cloud Vertex AI integration provides a specialized transport layer within the Anthropic Go SDK to interact with Anthropic models hosted on Google Cloud's Vertex AI platform. This integration abstracts the complexities of Google Cloud authentication and the specific REST API path structures required by Vertex AI, allowing developers to use the standard Anthropic client interface while targeting Google-managed infrastructure.
The core of this integration lies in the vertex package, which provides request options to configure authentication using Application Default Credentials (ADC) and a middleware that intercepts and rewrites outgoing HTTP requests to match the Vertex AI endpoint specifications.
Authentication and Configuration
The integration supports two primary ways to configure authentication: using the environment's default credentials or providing explicit Google credentials. Both methods return an sdkoption.RequestOption that can be passed to the Anthropic client constructor.
Authentication Methods
| Function | Description | Sources |
|---|---|---|
WithGoogleAuth | Automatically finds and uses [Application Default Credentials]. Requires region and project ID. | vertex/vertex.go:21-30 |
WithCredentials | Uses a provided *google.Credentials object for authentication. | vertex/vertex.go:33-58 |
The WithCredentials function is the underlying mechanism for both methods. It creates a specialized HTTP client using the Google OAuth2 token source and determines the base URL based on the specified region.
Sources: vertex/vertex.go:21-58
Regional Endpoint Mapping
The SDK maps specific region strings to corresponding Google Cloud AI Platform hostnames.
| Region | Base URL |
|---|---|
global | https://aiplatform.googleapis.com/ |
us | https://aiplatform.us.rep.googleapis.com/ |
Other (e.g., us-central1) | https://{region}-aiplatform.googleapis.com/ |
Sources: vertex/vertex.go:42-50, vertex/vertex_test.go:16-43
Request Transformation Middleware
The vertexMiddleware is the architectural component responsible for converting standard Anthropic API requests into Vertex AI-compatible requests. It performs three critical transformations: versioning, model path rewriting, and body modification.
Data Flow Transformation
The following diagram illustrates how the middleware intercepts a standard SDK request and modifies it for Vertex AI.
The diagram shows the sequence of operations performed on the HTTP request before it is sent to Google Cloud.
Sources: vertex/vertex.go:61-105
Path Rewriting Logic
Vertex AI requires a specific URL structure that includes the project ID, location, and a "publisher" specifier. The middleware dynamically constructs these paths based on the request type and parameters.
| Request Type | Original Path | Vertex AI Target Path |
|---|---|---|
| Non-Streaming Message | /v1/messages | /v1/projects/{projectID}/locations/{region}/publishers/anthropic/models/{model}:rawPredict |
| Streaming Message | /v1/messages | /v1/projects/{projectID}/locations/{region}/publishers/anthropic/models/{model}:streamRawPredict |
| Token Counting | /v1/messages/count_tokens | /v1/projects/{projectID}/locations/{region}/publishers/anthropic/models/count-tokens:rawPredict |
Sources: vertex/vertex.go:76-94
Implementation Examples
Standard Message Request
To use Vertex AI, a client is initialized with vertex.WithGoogleAuth. The model name used in the request corresponds to the Vertex AI model identifier.
client := anthropic.NewClient(
vertex.WithGoogleAuth(context.Background(), "us-central1", "my-project-id"),
)
message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello Vertex!")),
},
Model: "claude-sonnet-4-v1@20250514",
})
Sources: examples/vertex/main.go:13-33
Streaming Message Request
The streaming implementation uses the same client configuration but calls NewStreaming. The middleware automatically detects the stream: true parameter in the JSON body and updates the URL suffix to :streamRawPredict.
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Explain quantum physics.")),
},
Model: "claude-sonnet-4-v1@20250514",
})
for stream.Next() {
// Process events...
}
Sources: examples/vertex-streaming/main.go:16-58, vertex/vertex.go:85-88
Internal Logic and Constraints
Versioning
If a request does not contain an anthropic_version field, the middleware automatically injects the DefaultVersion (currently vertex-2023-10-16).
Sources: vertex/vertex.go:17, vertex/vertex.go:72-74
Body Modification
Unlike the standard Anthropic API where the model is part of the JSON payload, Vertex AI expects the model ID in the URL path. Consequently, the middleware deletes the "model" key from the request body before transmission to prevent API errors.
Sources: vertex/vertex.go:83
Error Handling
The middleware enforces that a projectID must be available. If a project ID is missing and cannot be resolved from credentials during request interception, the middleware returns an error immediately.
Sources: vertex/vertex.go:78-80, vertex/vertex.go:92-94
Summary
The Google Cloud Vertex AI Integration enables the Anthropic Go SDK to function as a bridge to Google's generative AI infrastructure. By utilizing a custom middleware to handle SigV4-like complexities and path transformations, it allows for a seamless developer experience where the model's location (Vertex vs. Anthropic Direct) is a configuration detail rather than a code-logic change.