?

providers

Google Vertex AI Provider

Configure the Vertex AI provider: Application Default Credentials or an explicit service-account JSON, region and model ID, required IAM roles.

When to use Vertex

The vertex provider is the right choice when:

  • You are on Google Cloud and want Claude billed through Vertex AI.
  • You want to authenticate via a service-account JSON or Application Default Credentials (ADC).
  • You need data residency inside a specific GCP region.
  • You want to route via Private Google Access and never touch the public internet.
  • You already have Workload Identity Federation set up for GKE workloads.

Configuration

provider: vertex

vertex:
  project: my-gcp-project
  region: us-central1
  model: claude-sonnet-4-6@20260101
  credentials_file: ~/.config/gcloud/vertex-key.json
  max_tokens: 4096
Field Default Effect
project required GCP project ID (not the numeric project number).
region required Vertex region. Anthropic-on-Vertex is available in a subset of regions; check the GCP console.
model required Anthropic-on-Vertex model ID, e.g. claude-sonnet-4-6@20260101. Note the @date suffix.
credentials_file empty Path to a service-account or authorized-user JSON key. Empty uses ADC.
max_tokens 4096 Caps output tokens.

Endpoint layout

Requests hit:

https://<region>-aiplatform.googleapis.com/v1/
    projects/<project>/locations/<region>/publishers/anthropic/
    models/<model>:rawPredict

rousseau builds this URL from project, region, and model; do not override.

Credentials

Two supported paths:

1. Explicit credentials_file

Point at a service-account JSON key or an authorized-user JSON (from gcloud auth application-default login):

vertex:
  credentials_file: /home/rousseau/.config/gcloud/vertex-sa.json

The provider calls google.CredentialsFromJSONWithParams under the hood because the file may be either a service_account or an authorized_user shape. CredentialsParams{Scopes: [cloud-platform]} is fixed.

2. Application Default Credentials

Leave credentials_file empty and the provider walks ADC:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable.
  2. ~/.config/gcloud/application_default_credentials.json (from gcloud auth application-default login).
  3. GCE / GKE metadata server (Workload Identity is the recommended pattern in-cluster).

Required IAM

Grant the calling identity roles/aiplatform.user — or the narrower aiplatform.endpoints.predict permission — on the project.

Workload Identity example for a GKE service account:

gcloud projects add-iam-policy-binding my-gcp-project \
  --member "serviceAccount:my-gcp-project.svc.id.goog[default/rousseau-sa]" \
  --role   "roles/aiplatform.user"

Streaming

The provider implements agent.StreamingProvider using the same rawPredict endpoint with the SSE variant.

Tool use

Tool definitions from the Registry are converted to Vertex's Anthropic-tool JSON in internal/llm/vertex/client.go. Approval policies apply.

Service-account setup, step by step

The simplest pattern for on-prem or non-GKE hosts. Create a dedicated service account, grant the minimum role, download a JSON key, and point rousseau at the file.

PROJECT=my-gcp-project
SA_NAME=rousseau-vertex

gcloud iam service-accounts create $SA_NAME \
  --display-name "rousseau-agent Vertex caller" \
  --project $PROJECT

gcloud projects add-iam-policy-binding $PROJECT \
  --member "serviceAccount:${SA_NAME}@${PROJECT}.iam.gserviceaccount.com" \
  --role   "roles/aiplatform.user"

gcloud iam service-accounts keys create ~/vertex-sa.json \
  --iam-account "${SA_NAME}@${PROJECT}.iam.gserviceaccount.com"



vertex:
  project: my-gcp-project
  region: europe-west4
  model: claude-sonnet-4-6@20260101
  credentials_file: /etc/rousseau/vertex-sa.json

Region matrix

Anthropic models on Vertex are region-scoped. Availability shifts as Google rolls out new snapshots. As of mid-2026:

Model us-central1 us-east5 europe-west1 europe-west4 asia-southeast1
claude-sonnet-4-6 yes yes yes yes yes
claude-opus-4-6 yes limited limited yes no
claude-haiku-4-6 yes yes yes yes yes

The authoritative source is the Vertex Model Garden — Model Garden > Anthropic > Region availability. Requesting access is instant; there is no manual approval step (unlike Bedrock).

Private connectivity

For deployments that must not egress to the public internet, use Private Google Access on the VPC and configure DNS to resolve *-aiplatform.googleapis.com to restricted.googleapis.com. The Vertex endpoint URL rousseau builds still works, but traffic stays on Google's backbone.

See GCP Private Google Access docs for the DNS zone setup.

Gotchas

  • Model ID format. Vertex uses @date (claude-sonnet-4-6@20260101), Bedrock uses -<date>-v1:0, direct Anthropic uses claude-sonnet-4-6. Do not paste one into the other.
  • Region availability. Not every Anthropic model is in every region. us-central1 and europe-west4 are the common ones.
  • Quota. Vertex quota is per-project per-region per-model. Trip a quota and requests will 429; enable exponential backoff at the caller.
  • anthropic_version string. rousseau sends vertex-2023-10-16 (see buildVertexBody in internal/llm/vertex/client.go). If Anthropic bumps the Vertex anthropic_version, older rousseau builds will 400.
  • User-agent required. Some Vertex endpoints reject requests without a User-Agent. The Go SDK sets one automatically; if you inject a custom HTTPClient, preserve the User-Agent header.

Troubleshooting

vertex: HTTP 401 unauthorized

The credential chain returned no valid credentials. Common causes: credentials_file path unreadable inside the container, GOOGLE_APPLICATION_CREDENTIALS env pointing at a missing file, or gcloud auth application-default login never run. Verify with gcloud auth application-default print-access-token.

vertex: HTTP 403 permission denied on resource

The identity is authenticated but lacks aiplatform.endpoints.predict on the project. Grant roles/aiplatform.user (or the narrower permission) and wait ~30 seconds for IAM propagation.

vertex: HTTP 404 not found

The model ID does not exist in the region. Double-check the @date suffix from Vertex Model Garden and confirm the region shows the model in the availability matrix.

vertex: HTTP 429 resource exhausted

Quota exceeded. Options: (1) request a quota increase via the IAM console, (2) queue calls in the caller with backoff, (3) split traffic across multiple regions.

vertex: credentials: could not find default credentials

ADC has nothing to walk. Either set credentials_file explicitly, export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json, or (for GKE) confirm Workload Identity is enabled on the cluster and the KSA is annotated correctly.

Related pages

Further reading

  • internal/llm/vertex/client.go — endpoint URL construction, ADC handling, wire types.
  • internal/llm/vertex/oauth2.go — OAuth2 HTTP-client construction.
  • internal/config/config.go — VertexConfig struct.
  • GCP docs: Anthropic on Vertex AI.
  • GCP docs: Workload Identity Federation.
Esc

Type to search 150+ pages. Ranking: BM25 with title/description boost.