Claude on Google Cloud's Vertex AI

A walkthrough of the Claude Academy course Claude on Google Cloud’s Vertex AI (Build with the API track). Each lesson is summarised with my own tables and examples; take the course for the full lessons. All the courses are listed in the Claude Academy course index.

Note: This page focuses on what differs on Vertex AI. Shared concepts are covered in my Building with the Claude API series: the request lifecycle, multi-turn, temperature, prompt evals and engineering, the tool loop, chunking, BM25, RRF, MCP and agent patterns. A few details were added from docs.claude.com, such as the IAM role, the endpoint names and the “Agent Platform” naming; verify those against the lessons.

Prerequisites:

• Python and JSON.
• A Google Cloud project with Vertex AI enabled. Google now brands this “Agent Platform”.
• The gcloud CLI.
• Jupyter.
• An Anthropic API key for the MCP project only.

Course Outline (and how it maps to the main course)

Module	Vertex-specific content	Shared with the main course
Accessing Claude (10 lessons)	Vertex AI setup, AnthropicVertex client, @-versioned model IDs	Lifecycle, multi-turn, system prompts, temperature, streaming, prefill and stop sequences, structured data
Prompt evaluation & engineering	—	Main notes §2–3
Tool use (14 lessons)	Batch tool, tools for structured data, text edit tool, web search tool	Main notes §4
RAG (10 lessons)	text-embedding-005 via google-genai, reranking, contextual retrieval	Main notes §5
Features	Extended thinking, images, citations, prompt caching	Main notes §6
MCP (12 lessons)	Adds an “MCP review” lesson; the project uses an Anthropic API key	Main notes §7
Agents & workflows (8 lessons)	—	Main notes §8–9

• Key point: on Vertex you use the same anthropic Python SDK and Messages API format as the main course. The main changes are the client class, authentication and model ID format.
• Compare Bedrock, where the course switches to boto3 Converse.

---

1. Vertex AI Setup

1. Open the Vertex AI dashboard, go to Model Garden, search for “Anthropic” and open the model you want.
2. Click Enable on the model page. If there is no Enable button, you already have access.
3. Install the gcloud CLI.
4. Authenticate:

gcloud init
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login   # ADC — the Anthropic SDK picks these up automatically

• IAM (from the docs): the calling identity needs aiplatform.endpoints.predict, for example through the Vertex AI / Agent Platform User role (roles/aiplatform.user).
• In production, use a service account through ADC instead of user credentials.
• No Anthropic API key is needed for the model calls. Billing goes through Google Cloud.
• A request needs Google Cloud credentials, the model, messages and max_tokens.

2. Client and Requests

%pip install "anthropic[vertex]"
from anthropic import AnthropicVertex

client = AnthropicVertex(region="global", project_id="your-project-id")
model = "claude-sonnet-4-5@20250929"

message = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=[{"role": "user", "content": "What is quantum computing? Answer in one sentence"}],
)
print(message.content[0].text)

Aspect	Claude API	Vertex AI
Client	Anthropic()	AnthropicVertex(region=…, project_id=…)
Install	anthropic	"anthropic[vertex]"
Auth	ANTHROPIC_API_KEY	Google ADC (gcloud auth application-default login)
Model ID	claude-sonnet-4-5 / claude-sonnet-4-5-20250929	claude-sonnet-4-5@20250929. Newer models have no @date suffix, e.g. claude-sonnet-4-6.
Region	n/a	global, multi-region or a specific region such as us-east5; model availability varies
Endpoint (raw REST)	/v1/messages	…/publishers/anthropic/models/<model>:rawPredict (:streamRawPredict for streaming). The model goes in the URL, and anthropic_version: "vertex-2023-10-16" goes in the body.
Other SDKs	—	TypeScript @anthropic-ai/vertex-sdk, Go, Java and others

• Streaming works exactly as in the main course:
  • Use stream=True for raw events (MessageStart … MessageStop).
  • Or use client.messages.stream(...) with text_stream and get_final_message().
• Prefill and stop sequences are unchanged. For example, stop_sequences=[", 5"] on “count 1–10” returns "1, 2, 3, 4".

3. Tool Use on Vertex

• The schemas, tool_use / tool_result blocks and the stop_reason loop are identical to the Claude API.
• Batch tool: batch_tool with invocations: [{name, arguments(object)}]. run_batch(invocations) loops over run_tool, and you route to it with run_batch(**tool_input).
  • In the course example, Claude sets two reminders in one turn.
• Tools for structured data: force the tool with tool_choice={"type": "tool", "name": "article_summary"} and read response.content[0].input. No follow-up request is needed.
  • The other options are {"type": "auto"}, the default, and {"type": "any"}.
• Text edit tool: use {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"} for Sonnet 4.5. Choose the version by model, for example get_text_edit_schema(model). You implement the file operations.
• Web search tool is available on Vertex in the course:
  • Schema: {"type": "web_search_20250305", "name": "web_search", "max_uses": 5, "allowed_domains": ["nih.gov"]}.
  • The response has these blocks: ServerToolUseBlock, WebSearchToolResultBlock, WebSearchResultBlock and CitationsWebSearchResultLocation.

4. RAG Differences

• Claude can’t create embeddings. On Vertex the course uses Google’s text-embedding-005 through the Google GenAI SDK:

# pip install google-genai
from google import genai
gclient = genai.Client(project="YOUR_PROJECT_ID", location="global", vertexai=True)

def generate_embedding(text):
    resp = gclient.models.embed_content(model="text-embedding-005", contents=text)
    return [e.values for e in resp.embeddings] if resp.embeddings else []

• Note that this returns a list of vectors, one per input.
• Everything else is the same as the main course: VectorIndex with cosine similarity, BM25, and a hybrid Retriever with RRF.
• Reranking: Claude returns the IDs of the most relevant chunks in order.
• Contextual retrieval: Claude writes a snippet that situates each chunk in the document, and the snippet is prepended before indexing.

5. Claude Features on Vertex

Feature	Notes on Vertex
Extended thinking	Same as the API: thinking={"type": "enabled", "budget_tokens": 1024} (minimum 1024), and max_tokens must be greater than the budget, e.g. 4000. The response has thinking blocks with a signature, or redacted thinking. Test redaction with the course’s TRIGGER_REDACTED_THINKING_… string. Newer models use adaptive thinking (see main notes §6).
Images	Messages-API image blocks. Course limits: 100 images, 5 MB each, 8000 px for a single image or 2000 px each when sending multiple, base64 only in the Vertex lesson. Tokens ≈ w×h/750. Use step-by-step or one-shot prompts (marbles, fire risk 1–4).
Citations	Document block with "title" and "citations": {"enabled": True}. PDFs return page locations; plain text returns CitationCharLocation.
Prompt caching	cache_control: {"type": "ephemeral"}, the same as the API. Clone the tools list and mark the last tool; put the system prompt in a text-block list. Cache order is tools → system → messages, the TTL is 5 min, and you check cache_creation_input_tokens / cache_read_input_tokens.

• The Vertex outline has no separate PDF, code execution or Files API lessons. Check the docs for which beta features are available on Vertex, as they can lag the Claude API.

6. MCP, Claude Code and Agents

• MCP project (cli_project.zip): put ANTHROPIC_API_KEY in .env. The starter project calls the Claude API directly, not Vertex.
  • Run with uv run main.py and test a simple question such as “what’s 1+1?”.
  • In real projects you usually build either the client or the server, not both.
• MCP review: tools are controlled by the model, resources by the app (autocomplete, “Add from Google Drive”), and prompts by the user (starter buttons, slash commands).
• Claude Code, computer use and workflows vs agents are covered in main notes §8–9 and are not platform-specific.
  • Claude Code can also be pointed at Vertex. Check the Claude Code docs for the environment variables.

---

Quick-Review Flashcards

1. Q: Which Python client and install extra are used for Claude on Vertex? → A: from anthropic import AnthropicVertex, installed with pip install "anthropic[vertex]".
2. Q: What arguments does AnthropicVertex take in the course? → A: region="global" and project_id="your-project-id".
3. Q: What format do Vertex model IDs have for Claude 4.5-era models? → A: Name @ date, e.g. claude-sonnet-4-5@20250929 or claude-haiku-4-5@20251001.
4. Q: How does the SDK authenticate to Vertex? → A: With Google Application Default Credentials, set up by gcloud auth application-default login. No Anthropic key is needed.
5. Q: Where do you enable Claude models in Google Cloud? → A: Vertex AI → Model Garden → search “Anthropic” → model page → Enable.
6. Q: Which IAM permission or role is needed to call Claude on Vertex? → A: aiplatform.endpoints.predict, e.g. through roles/aiplatform.user.
7. Q: Does the request and response format change on Vertex compared with the Claude API? → A: Not in the SDK; you still use messages.create and the same blocks. In raw REST, the model goes in the URL (:rawPredict) and the body includes anthropic_version: "vertex-2023-10-16".
8. Q: Which embedding model and SDK does the Vertex course use? → A: text-embedding-005 via google-genai (genai.Client(vertexai=True) and models.embed_content).
9. Q: How do you force structured output with a tool on Vertex? → A: tool_choice={"type": "tool", "name": "article_summary"}, then read response.content[0].input.
10. Q: Which built-in server tool does the Vertex course demo that the Bedrock course doesn’t? → A: The web search tool (web_search_20250305, with max_uses and allowed_domains).
11. Q: What image limits does the Vertex course state? → A: Up to 100 images, 5 MB each, 8000 px for one image or 2000 px for several, base64 encoded.
12. Q: How do you cache tools and the system prompt? → A: Add cache_control: {"type": "ephemeral"} to a copy of the last tool, and send the system prompt as a text-block list with cache_control.
13. Q: Why does the MCP project need an Anthropic API key? → A: Its starter chatbot calls the Claude API directly instead of going through Vertex.
14. Q: What does the batch tool do? → A: It wraps several tool invocations in a single call, so Claude runs independent operations in one turn.

Practice Ideas

• Set up a fresh GCP project:
  1. Enable a Claude model in Model Garden.
  2. Configure ADC.
  3. Grant a service account roles/aiplatform.user.
  4. Make one request with the SDK and one with raw curl to :rawPredict.
• Take a main-course notebook and switch Anthropic() to AnthropicVertex(...), changing the model ID. Confirm that streaming, tools and caching work unchanged.
• Try the global region and a specific regional endpoint for the same model, and note availability and errors.
• Build the RAG pipeline with text-embedding-005, BM25, RRF, Claude reranking and contextual retrieval.
• Use web search restricted with allowed_domains, and render the search results plus inline citations in a simple HTML page.
• Add prompt caching to a tool-heavy helper and log the cache read and write tokens over 3 consecutive calls.