Claude on Vertex / GCP

1 · Three front doors, one Claude essential

Imagine your company just signed a big Google Cloud contract, and legal has ruled that customer data may not leave GCP. You already have a Claude-powered feature humming along on the direct Anthropic API — and now someone asks, "Can we keep it, but run it inside Google Cloud?" The panic-inducing assumption is that you'll rewrite the whole thing against some foreign Google API. You won't. This chapter is the reassuring answer: it's the same Claude, reached through a different lobby, and the rewrite is about three lines.

Here's the mental model that makes the rest of the chapter click. Think of Claude as a single artist whose paintings you want to buy. You can walk into the artist's own gallery (the Anthropic API), or you can buy the exact same painting through two big department stores that resell it — Amazon's (Bedrock) and Google's (Vertex AI). The painting is identical no matter where you buy it. What changes is whose till you pay at, which membership card you show at the door, and which loading dock the delivery comes from. That's billing, authentication, and region — nothing about the art itself.

Why would anyone use a reseller instead of the gallery? Because big organizations don't buy on convenience, they buy on governance. If your company already runs on Google Cloud, then routing Claude through Vertex means the AI spend shows up on the same invoice you already reconcile, access is controlled by the same Google IAM roles your security team already audits, and — the clincher for regulated industries — the data stays inside the GCP project and region you've already had approved for compliance. None of that makes Claude smarter; it makes Claude adoptable inside an enterprise that has already drawn its trust boundaries around one cloud.

The common mistake is to treat these three as three different products to learn. They aren't. Every prompt you've written, every streaming loop, every tool-use schema from the earlier chapters transfers verbatim. Internalize that now and you'll read the rest of this page as "spot the two things that differ" rather than "learn a new SDK." So, the precise version:

You've reached Claude via the Anthropic API and Bedrock. Vertex AI is the third — Claude on Google Cloud, billed through GCP with Google's auth, IAM, and data residency. Same model, same Messages concepts; different plumbing.

2 · Authenticate with ADC essential

The single most common way a Vertex integration fails on day one is authentication — and almost always because someone goes looking for the "Vertex API key," doesn't find one, and assumes something is broken. There is no key. That absence is not a bug; it's the whole design, and once you understand why, ADC stops feeling mysterious and starts feeling safer than what you were doing before.

Think about how a hotel used to work versus how it works now. The old way is a physical brass key you carry around: lose it, and whoever finds it can open your room forever. An API key is exactly that brass key — a long secret string that grants access to anyone holding it, which is why keys leaked in Git commits are such a recurring disaster. Google's Application Default Credentials (ADC) are the modern keycard system instead: you prove who you are at the front desk once, and the building quietly issues short-lived, automatically-refreshed passes to your code behind the scenes. Your program never holds a permanent secret; it just says "I'm the process running as this identity," and Google's libraries find and present the right credential for you.

Concretely, ADC means the same code works in two very different places without change. On your laptop, you run one gcloud login command and Google caches a credential in a well-known file on your machine; the SDK finds it automatically. In production — a Cloud Run service, a GKE pod, a Compute Engine VM — there's no login at all: the machine has a service account attached to it, and the SDK picks that up instead. Your code literally doesn't know or care which of the two it's running under, because in both cases it just asks the environment "who am I?" and gets an answer.

The mistake to avoid is trying to "help" ADC by pasting a downloaded service-account JSON key file into your repo or an environment variable in your source. That reintroduces the exact brass-key problem ADC was built to eliminate. If you did the boto3 work in W1, this is the identical discipline — no long-lived secrets in code, ever — just spelled in Google's dialect. Now the precise mechanics:

Vertex uses Google Application Default Credentials — no API key. Locally you authenticate once with gcloud; on GCP compute you use the attached service account. Same "no keys in code" discipline as boto3 (W1).

setup.shpip install "anthropic[vertex]"
gcloud auth application-default login
gcloud config set project my-gcp-project
gcloud services enable aiplatform.googleapis.com

3 · Call Claude on Vertex intermediate

This is the moment the chapter's promise pays off, and it's almost anticlimactic — which is exactly the point. If you were bracing for a new request format, new parameters, a new way to read the response, relax: there isn't one. The call you're about to write is the call you already know from C2, with two small substitutions. When people say "porting to Vertex is easy," this section is the proof.

Picture a wall socket. In your home country you plug an appliance straight into the wall. Travel abroad and the appliance still works identically — you just clip on a plug adapter first. AnthropicVertex is that adapter. The appliance (your messages.create call, your prompts, your response handling) is unchanged; you've only swapped the thing that connects it to the wall. Instead of Anthropic(), which reads an API key, you build AnthropicVertex(region=..., project_id=...), which quietly reaches for the ADC credentials from the previous section. Same appliance, different plug.

The one genuinely new detail worth slowing down for is the model ID format, because it's where a first attempt usually errors out. On the direct API a model is named plainly, like claude-3-5-sonnet-v2. On Vertex the same model carries an @ and a date-stamped version suffix — claude-3-5-sonnet-v2@20241022. That @date is Vertex's way of pinning you to an exact, immutable version so a model update can't silently change your outputs. It's the same idea as pinning a package version in requirements.txt rather than grabbing "latest": predictability over surprise.

The classic mistake here is copying a model ID from the wrong place — pasting the direct-API name into a Vertex call, or an old date suffix that the region no longer serves — and then reading the resulting error as an auth problem. It usually isn't; it's a model-ID mismatch. When a Vertex call fails, check the model string against the current Vertex docs before you go re-running gcloud logins. With that caveat noted, here's the real thing:

The AnthropicVertex client mirrors the base SDK — set region + project, then use the same messages.create from C2. Model IDs use Vertex naming (an @ version suffix).

vertex_call.pyfrom anthropic import AnthropicVertex
client = AnthropicVertex(region="us-east5", project_id="my-gcp-project")

resp = client.messages.create(
    model="claude-3-5-sonnet-v2@20241022",
    max_tokens=300,
    system="You are a concise SRE assistant.",
    messages=[{"role": "user", "content": "In one sentence, what is Vertex AI?"}])
print(resp.content[0].text)

4 · Map concepts across all three doors intermediate

Six months from now, someone on your team will ask "how hard would it be to move this off Vertex?" — and your answer decides whether that's a weekend or a quarter. The difference comes down to a habit you can build right now: knowing, precisely, which parts of your code are provider-specific and which parts are universal. This section draws that line so sharply that the migration answer becomes "change one config value."

Here's a way to feel it. Think of driving a rental car in a new city. Everything that matters to actually driving — the steering wheel, the pedals, reading road signs — is identical to your own car; that knowledge transfers completely. What differs is trivial and local: which slot the key goes in, where the fuel cap release hides, which side the indicator stalk is on. If you catalogue those three quirks up front, you drive away in thirty seconds. If you don't, you sit in the parking lot hunting for the handbrake. The three Claude front doors are exactly this: the "driving" (your Messages request, streaming, tools) is shared, and only a tiny, enumerable set of quirks differs — the client class, the auth mechanism, and the model-ID string.

Making that mapping explicit — writing it down as data, as the lab below does — is what turns a scary rewrite into a lookup. When the three differences live in one small table instead of scattered across your codebase, swapping providers means editing that table, not hunting through business logic for hard-coded assumptions. This is the same instinct behind a good config file: pull the things that vary into one obvious place so the code that uses them can stay ignorant of the choice.

The trap to watch for is quietly assuming more transfers than actually does. The core Messages surface is genuinely identical — but not every server-side feature is available on every door (you'll map those capability gaps in the ladder exercises). So "everything transfers" is true of the request shape, and you should still verify individual features per provider before you promise them. With that honest caveat, the mapping itself:

Everything transfers — only the client construction and model id change. Model the mapping so switching front doors is a config change, not a rewrite.

front_doors.pydef client_config(door):
    return {
        "api":     {"client": "Anthropic()",       "auth": "ANTHROPIC_API_KEY",
                    "model": "claude-opus-4-8"},
        "bedrock": {"client": "boto3 bedrock-runtime","auth": "IAM role",
                    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0"},
        "vertex":  {"client": "AnthropicVertex()",  "auth": "gcloud ADC",
                    "model": "claude-3-5-sonnet-v2@20241022"},
    }[door]

for door in ["api", "bedrock", "vertex"]:
    c = client_config(door)
    print(f"{door:8} {c['client']:26} auth={c['auth']}")
print("messages shape is IDENTICAL across all three")

api      Anthropic()                auth=ANTHROPIC_API_KEY
bedrock  boto3 bedrock-runtime       auth=IAM role
vertex   AnthropicVertex()           auth=gcloud ADC
messages shape is IDENTICAL across all three

5 · Advanced — streaming & tool use on Vertex advanced

It's tempting to assume the "hard" features — streaming responses, tool use — are where the provider abstraction finally breaks down. That's the natural fear: the basic call ports easily, sure, but surely the fancy stuff has provider-specific catches? Here's the payoff of everything you've read so far — it doesn't. Streaming and tool use on Vertex are byte-for-byte the same code as on the direct API. This section exists mainly to convince you of that, because believing it is what lets you commit to the abstraction in the next section.

Streaming is worth a plain-language beat first, since it's easy to mis-picture. A normal call is like ordering a coffee and waiting at the counter until the whole drink is done before it's handed to you. Streaming is like watching the barista pour — you get the response as it's produced, token by token, so a user sees words appear in real time instead of staring at a spinner. That matters enormously for perceived speed: the total time is similar, but the experience of a chatbot that types feels dramatically more responsive than one that goes blank and then dumps a paragraph. The magic that makes this ergonomic in Python is the with ... as stream context manager, which opens the live connection and — crucially — guarantees it gets closed cleanly even if your loop throws halfway through.

Tool use is the other "advanced" capability, and the same reassurance holds: you hand Claude a tools=[...] schema describing functions it may call, and you run the same request/response loop you built in C2. The definitions, the loop structure, the way you feed tool results back — all identical across doors. The point being hammered, again, is that the only Vertex-specific lines are the client constructor and the model ID.

The one honest asterisk — and the mistake would be to forget it — is that "the SDK surface is identical" is not the same as "every server-side tool is enabled on every door." The client-side patterns transfer perfectly; whether a specific built-in server tool is actually available on Vertex is a per-provider fact to check against the capability map, not to assume from the code looking the same. Keeping those two ideas separate (identical code shape vs. per-door feature availability) is what stops you promising a feature that isn't there. Now the code:

Streaming uses the same with client.messages.stream(...) context manager; tool use uses the same tools=[...] schema and loop from C2. Only client + model id differ.

vertex_stream.pyfrom anthropic import AnthropicVertex
client = AnthropicVertex(region="us-east5", project_id="my-gcp-project")
with client.messages.stream(
    model="claude-3-5-sonnet-v2@20241022", max_tokens=200,
    messages=[{"role": "user", "content": "Count to five slowly."}]) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
print()

6 · Professional — choosing a front door professional

Sooner or later you'll be in a room where someone asks "so which one should we actually use?" — and the wrong instinct is to answer with a benchmark. New engineers reach for "which door is fastest / cheapest / most capable?" as if this were a performance bake-off. It isn't, and answering that way marks you as someone who's missed the point. The model is the same through every door, so the decision has almost nothing to do with the AI and almost everything to do with your organization's existing plumbing.

Think of it like choosing which bank to route a payment through when the recipient is the same either way. You don't pick based on "which bank has better money" — the money is identical. You pick based on which bank you already hold an account with, whose statements your accountant already knows how to read, and which one your compliance rules already bless. That's the whole shape of this choice: pick the door that matches the cloud your company already lives in, because it collapses three separate governance problems — billing, access control, and data residency — into ones you've already solved.

So the real inputs to the decision are things like: are you already an AWS shop or a GCP shop? Does a contract or regulation pin your data to a specific cloud or region? Do you want AI spend consolidated onto an invoice your finance team already reconciles, and access governed by the IAM roles your security team already audits? A team deep in GCP naturally reaches for Vertex; a team deep in AWS reaches for Bedrock; a small team or a prototype with no such constraints is usually best served by the simplest path — the direct API. The value of writing this as an explicit decision function, as the lab does, is that it forces the criteria into the open where they can be reviewed, rather than living as one senior engineer's gut feeling.

The mistake to avoid is letting a single feature quietly override the whole framework without saying so. If your workload genuinely needs a capability that only the direct API offers, that requirement trumps the "match your existing cloud" rule — and a good decision function makes that override visible and ordered, not buried. Watch how the lab's rules read top-to-bottom, first-match-wins, so the ordering itself encodes the priority. Here's the framing:

Enterprises pick Bedrock or Vertex to keep AI spend and data in the cloud they already use — one bill, one IAM model, one data-residency story. Model the decision.

choose_door.pydef choose_door(on_aws, on_gcp, wants_simplest, data_residency):
    if data_residency == "aws" or (on_aws and not on_gcp): return "bedrock"
    if data_residency == "gcp" or (on_gcp and not on_aws): return "vertex"
    if wants_simplest: return "api (direct)"
    return "api (direct)"

print(choose_door(on_aws=True, on_gcp=False, wants_simplest=False, data_residency=None))
print(choose_door(on_aws=False, on_gcp=True, wants_simplest=False, data_residency=None))
print(choose_door(on_aws=False, on_gcp=False, wants_simplest=True, data_residency=None))

bedrock
vertex
api (direct)

7 · Tech-lead — abstract the provider tech-lead

Here's the difference between an engineer and a tech lead, in one design decision. An engineer gets Claude working on Vertex and ships it. A tech lead gets it working and then asks the uncomfortable question: "what happens to every call site in our codebase the day we have to move providers?" If the answer is "we grep for AnthropicVertex and pray," the team has quietly signed up for a painful migration later. This section is about spending a little design effort now so that day is a config change instead.

The idea is an old and reliable one: put the thing that varies behind a single door, and make everyone knock on that door instead of reaching around it. Think of the electrical outlets in your walls. Your lamp doesn't know or care whether the electricity comes from a coal plant, a solar farm, or a nuclear station — it just plugs into a standard socket, and the utility handles all the messy provider-specific detail behind that socket. You can swap the entire power source and not one appliance in the house needs rewiring. A provider abstraction is that socket: your application code calls something plain like llm.complete(...), and a single small adapter decides — from config — whether that resolves to the API, Bedrock, or Vertex, applying the right client and the right model-ID prefix along the way.

What makes this cheap to build is precisely the discovery of this whole chapter: only two things actually differ between doors — the client constructor and the model-ID convention. So the abstraction doesn't have to be clever or large; it just has to isolate those two facts in one place. Everything downstream — your prompts, your streaming loops, your tool schemas, your business logic — stays blissfully provider-agnostic. This is the "one client" discipline from DF4 pointed at model providers instead of HTTP endpoints.

The mistake here is over-engineering in the other direction — building a sprawling framework that tries to abstract every conceivable difference. Don't. The whole force of a good abstraction is that it hides only what varies (constructor, prefix) and leaves everything shared exposed and obvious. Wrap the two differences; leave messages.create alone. A lead who draws that line well saves the team a migration; a lead who abstracts too much just builds a second thing to maintain. Here's the principle:

A lead wraps the front door behind one internal client so the app code never hard-codes a provider. Switching API→Bedrock→Vertex (for cost, compliance, or a new region) becomes a config change — the DF4 "one client" lesson applied to model providers.

def front_door(provider):
    return {
        "anthropic": ("Anthropic()",              "bare id: claude-opus-4-8"),
        "vertex":    ("AnthropicVertex(...)",     "bare id: claude-opus-4-8 (no prefix)"),
        "bedrock":   ("AnthropicBedrockMantle(...)", "prefixed: anthropic.claude-opus-4-8"),
    }[provider]

for p in ("anthropic", "vertex", "bedrock"):
    print(p, "->", front_door(p))

# One-time local auth — populates Application Default Credentials:
#   gcloud auth application-default login

from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-gcp-project", region="us-east5")
# No ANTHROPIC_API_KEY — auth comes from ADC (the gcloud login above,
# or a service account / workload identity in production).

from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-gcp-project", region="us-east5")

resp = client.messages.create(
    model="claude-opus-4-8",          # bare id on Vertex — NO anthropic. prefix
    max_tokens=512,
    messages=[{"role": "user", "content": "Explain ADC in one sentence."}],
)
print(next(b.text for b in resp.content if b.type == "text"))

VERTEX = {                      # from the platform-availability table
    "messages/streaming/tools": True,
    "prompt_caching":           True,
    "automatic_prompt_caching": False,   # 1P only
    "web_search":               "basic only (web_search_20250305)",
    "web_fetch":                False,
    "code_execution":           False,
    "files_api":                False,
    "batches":                  False,
}
def on_vertex(feature):
    return VERTEX.get(feature, "verify in platform-availability docs")

print(on_vertex("prompt_caching"))            # True
print(on_vertex("web_fetch"))                 # False
print(on_vertex("web_search"))                # basic only (web_search_20250305)

def choose_door(existing_cloud, needs_1p_only_feature, wants_iam_billing):
    if needs_1p_only_feature:
        return "first-party API — Batches / Files / code exec are 1P-only"
    if existing_cloud == "gcp":
        return "Vertex — ADC auth, GCP billing, data stays in your GCP project"
    if existing_cloud == "aws" or wants_iam_billing:
        return "Bedrock — AWS IAM auth + Marketplace billing"
    return "first-party API — simplest, full feature surface"

print(choose_door("gcp", False, False))   # Vertex
print(choose_door("aws", False, True))    # Bedrock
print(choose_door("none", True, False))   # first-party (needs 1P-only feature)

import os

def make_client(provider):
    if provider == "vertex":
        from anthropic import AnthropicVertex
        return AnthropicVertex(project_id=os.environ["GCP_PROJECT"], region="us-east5"), ""
    if provider == "bedrock":
        from anthropic import AnthropicBedrockMantle
        return AnthropicBedrockMantle(aws_region=os.environ["AWS_REGION"]), "anthropic."
    from anthropic import Anthropic
    return Anthropic(), ""          # first-party

def model_id(base, prefix):         # normalize per provider
    return prefix + base            # bedrock -> "anthropic.claude-opus-4-8"

client, prefix = make_client(os.environ.get("LLM_PROVIDER", "anthropic"))
resp = client.messages.create(model=model_id("claude-opus-4-8", prefix),
                              max_tokens=256,
                              messages=[{"role":"user","content":"ping"}])

Knowledge check check yourself