The Claude Agent SDK — the programmable form of Claude Code's agent loop — runs its model calls against Google Cloud when you set CLAUDE_CODE_USE_VERTEX=1. Authentication is standard GCP credentials; billing and quota flow through your Google Cloud project. One naming note before anything else: Anthropic's page for this is titled "Claude Code on Google Cloud's Agent Platform, formerly Vertex AI," while Google's own login prompt still says "Google Vertex AI" — same surface, mid-rebrand. This guide says Vertex for short.
The core setup
Three variables do the work, alongside your GCP Application Default Credentials:
| Variable | Purpose |
|---|---|
CLAUDE_CODE_USE_VERTEX=1 | Route the agent's model calls to Vertex |
ANTHROPIC_VERTEX_PROJECT_ID | The GCP project to bill and authorize against |
CLOUD_ML_REGION | Where requests go: global, multi-region us / eu, or a specific region like us-east5 |
Claude Code also ships a /setup-vertex login wizard and (v2.1.98+) a startup model check that catches misconfiguration before the first task — conveniences that, notably, Foundry lacks. For proxy or gateway architectures, ANTHROPIC_VERTEX_BASE_URL overrides the endpoint, and the gcpAuthRefresh setting handles credential refresh for long-running agents whose tokens would otherwise expire mid-session.
Region strategy, including per-model overrides
CLOUD_ML_REGION=global is the low-friction choice: Google routes each request to available capacity rather than binding you to one region's quota. But enterprises with data-residency or latency requirements often need specific regions — and here Vertex has a wrinkle the other platforms don't: model availability varies by region, so the region that serves your Opus traffic may not serve Haiku. The SDK's answer is per-model overrides: VERTEX_REGION_CLAUDE_* variables (for example VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5) pin individual model families to their own regions while CLOUD_ML_REGION covers the rest. An agent that routes between model tiers can therefore span regions transparently. For the wider context, see global vs. regional endpoints.
The tool-search default: off on Vertex
Here is the platform-specific behavior most likely to puzzle a team porting an agent from Bedrock or the first-party API. The tool search tool lets the agent defer rarely used tool definitions — such as those from large MCP servers — out of its context window and search for them on demand. On Vertex, Claude Code disables MCP tool search by default, loading all MCP tool definitions upfront instead.
The reason is model-generation support: Vertex supports tool search only for Sonnet 4.5+ and Opus 4.5+, and earlier models reject the required beta header outright. A default of "on" would hard-fail sessions pinned to older models, so the default is "off." If your agent runs on qualifying models, re-enable it explicitly:
ENABLE_TOOL_SEARCH=trueWhether to bother depends on your tool count. With a handful of MCP tools, upfront loading is harmless. With MCP servers exposing dozens of tools, upfront loading costs input tokens on every request and degrades tool selection — the exact problem defer_loading exists to solve on the Messages API. Same trade-off, agent-loop edition. (The remote MCP connector itself remains unavailable on Vertex; the Agent SDK sidesteps that by running its own MCP client — including for local command-based servers — which is why MCP works here at all. See the platform split.)
Prompt caching knobs
As on Bedrock and Foundry, prompt caching is enabled automatically — important for agent loops, which resend growing history every turn. DISABLE_PROMPT_CACHING=1 turns it off for testing; ENABLE_PROMPT_CACHING_1H=1 requests the 1-hour cache TTL, billed at a higher write rate than the 5-minute default but often worthwhile for agents that pause between turns. Vertex-specific caching mechanics live in prompt caching on Vertex.
ANTHROPIC_VERTEX_PROJECT_ID set, CLOUD_ML_REGION chosen deliberately (global unless residency says otherwise), per-model region overrides for any model not served in your primary region, and ENABLE_TOOL_SEARCH=true if you run Sonnet 4.5+/Opus 4.5+ with large MCP toolsets.Where to go next
Compare the Bedrock setup and the Foundry setup, or see Vertex model-ID formats and why Vertex has no server tools for the surrounding platform picture.