docs: document Vertex AI dependencies for the agent-server image

[rajshah4]

Summary

Vertex AI support (google-cloud-aiplatform) is not included by default in the published agent-server image — it requires the ENABLE_VERTEX build flag (Docker) or the vertex extra (local/uv). This was previously undocumented, leading to cryptic ModuleNotFoundError: No module named 'vertexai' errors for any Vertex AI customer.

This came up while addressing a Red Hat POC objection: Red Hat routes Claude through Google Vertex AI / Model Garden (not direct Anthropic), and there was no documented path for enabling Vertex support across deployment types.

Changes

Adds the following sections to the existing Google Gemini/Vertex provider page (openhands/usage/llms/google-llms.mdx):

• Vertex AI Dependencies — covers all three deployment contexts:
  • Local / non-Docker install (pip install "openhands-sdk[vertex]" / uv sync --extra vertex)
  • Custom agent-server image (--build-arg ENABLE_VERTEX=1), with a cross-link to the Custom Sandbox Guide
  • OpenHands Enterprise (replicated/K8s) — notes the built-in Vertex config path but flags that the default image still needs Vertex enabled
• Claude via Vertex AI — the vertex_ai/claude-*@<date> provider string, plus a note about the additional anthropic[vertex] dependency
• Troubleshooting — the No module named 'vertexai' error and how to resolve it

A <Note> also calls out the asymmetry with AWS Bedrock, whose boto3 dependency is bundled by default — Vertex is the outlier opt-in provider.

Style

Follows the structure of the existing AWS Bedrock provider page (Prerequisites → Configuration → Troubleshooting), uses Mintlify <Note> components, and follows the repo's DOC_STYLE_GUIDE.md (Title Case headers, code blocks for commands, absolute internal link paths).

Notes for reviewers

• The anthropic[vertex] caveat is hedged with "may also require" because it surfaces from historical issue reports ([Bug]: VertexAI integration with Anthropic fails due to missing dependencies OpenHands#3505) rather than a validated end-to-end test of Claude-via-Vertex in our own deployments. We've validated Gemini-via-Vertex but not Claude-via-Vertex.
• This is a documentation-only change — no code or config changes.

---

This PR was created by an AI agent (OpenHands) on behalf of Rajiv Shah.

@rajshah4 can click here to continue refining the PR

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Jun 26, 2026, 6:19 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

🟡 Acceptable — addresses a real and common failure mode (ModuleNotFoundError: vertexai), and the new structure is reasonable. Requesting changes because several concrete technical claims in the new sections should be verified against the actual openhands-agent-server Dockerfile and SDK packaging before this lands; if any are wrong, users following the guide will hit new errors instead of getting unstuck.

The three blocking items are:

1. ENABLE_VERTEX build-arg is not referenced anywhere else in this docs repo, and the path openhands-agent-server/openhands/agent_server/docker/Dockerfile cannot be verified from here — both need to match what the Dockerfile actually accepts.
2. anthropic[vertex] does not appear to be a real pip extra on the anthropic package; suggesting it will likely yield Could not find a version that satisfies the requirement anthropic[vertex] for users who follow the troubleshooting note.
3. openhands-sdk[vertex] package + extra name needs to be confirmed against the published SDK.

Two smaller suggestions (non-blocking): the uv sync --extra vertex command will not work for end users outside the openhands source tree, and the Claude example uses a 2-year-old model version.

Detailed inline comments follow.

---

[RISK ASSESSMENT]

• Overall PR ⚠️ Risk Assessment: 🟢 LOW
  Docs-only change. No code, no dependency manifest, no runtime behavior change. Worst case if any technical claim is wrong: users waste time debugging before finding the right docs. No security, compliance, or production-risk surface.

VERDICT:
❌ Needs rework: Verify the three concrete technical claims above against the actual source files, then this is a valuable addition.

KEY INSIGHT:
A docs PR that tells users to run a command they cannot reproduce is worse than no doc at all — every command in this section needs to match what the code actually accepts.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

Was this review helpful? React with 👍 or 👎 to give feedback.

---

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

🟡 Suggestion: uv sync only works from inside a project directory whose pyproject.toml declares the vertex extra. End users running OpenHands (rather than hacking on it) will not be in such a directory, so this command will fail with Project directory not found or similar. Either drop the uv variant, or replace it with uv pip install "openhands-sdk[vertex]" which works in any Python environment the same way the pip install line above does.

[rajshah4]

Fixed — replaced uv sync --extra vertex with uv pip install "openhands-sdk[vertex]" (commit 93966ca), which works in any Python environment.

[all-hands-bot]

🔴 Critical: The Anthropic Python SDK does not expose a vertex extras spec — there is no anthropic[vertex] distribution on PyPI. LiteLLM routes Claude-via-Vertex calls through google-cloud-aiplatform (already covered by the vertex extra), not through any anthropic[vertex] package. A user following this note will hit ERROR: Could not find a version that satisfies the requirement anthropic[vertex] and conclude the Vertex setup is broken. Either remove this paragraph entirely, or replace it with the actual LiteLLM-recommended install command (typically just google-cloud-aiplatform, possibly with the anthropic SDK itself for some LiteLLM code paths).

[rajshah4]

Pushing back on this one — anthropic[vertex] is a real PyPI extra. Verified directly against the published wheel METADATA:

Provides-Extra: vertex
Requires-Dist: google-auth[requests]<3,>=2; extra == 'vertex'

pip install "anthropic[vertex]" resolves successfully (tested against anthropic 0.112.0). The note stands, since Claude-via-Vertex historically surfaced ModuleNotFoundError: No module named 'anthropic' (OpenHands/OpenHands#3505) when only google-cloud-aiplatform was present.