From 9181693896d68b056c2bb8857fcc2d0a7b8fa940 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 26 Jun 2026 18:07:15 +0000 Subject: [PATCH 1/4] docs: document Vertex AI dependencies for agent-server image MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 undocumented, leading to ModuleNotFoundError errors for Vertex customers. Adds: - Vertex AI Dependencies section covering local, custom-Docker, and OHE deployments - Claude via Vertex AI guidance (vertex_ai/claude-*@ provider string and anthropic[vertex] caveat) - Troubleshooting for the 'No module named vertexai' error Follows the structure/style of the existing AWS Bedrock provider page. Co-authored-by: openhands --- openhands/usage/llms/google-llms.mdx | 79 ++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx index 6b7898888..1742c9fd7 100644 --- a/openhands/usage/llms/google-llms.mdx +++ b/openhands/usage/llms/google-llms.mdx @@ -28,3 +28,82 @@ Then set the following in the OpenHands UI through the Settings under the `LLM` - `LLM Model` to the model you will be using. If the model is not in the list, enable `Advanced` options, and enter it in `Custom Model` (e.g. vertex_ai/<model-name>). + +### Vertex AI Dependencies + +The `vertex_ai/*` models (including Gemini and Claude via Vertex AI) require the +`google-cloud-aiplatform` package, which is **not included by default** in the published +agent-server image. How you enable it depends on your deployment: + + +Unlike AWS Bedrock (whose `boto3` dependency is bundled by default), Vertex AI support is +opt-in. If you skip this step, you will see a ModuleNotFoundError: No module named +'vertexai' error when the agent tries to call a Vertex AI model. + + +#### Local / Non-Docker Install + +Install the `vertex` extra in your Python environment: + +```bash +pip install "openhands-sdk[vertex]" +# or, with uv: +uv sync --extra vertex +``` + +#### Custom Agent-Server Image + +Build the image with the `ENABLE_VERTEX` build flag: + +```bash +docker build \ + --build-arg ENABLE_VERTEX=1 \ + -t my-agent-server:vertex \ + -f openhands-agent-server/openhands/agent_server/docker/Dockerfile \ + . +``` + +Then point OpenHands at your custom image via the `AGENT_SERVER_IMAGE_REPOSITORY` and +`AGENT_SERVER_IMAGE_TAG` environment variables (see the +[Custom Sandbox Guide](/openhands/usage/advanced/custom-sandbox-guide) for details). + +#### OpenHands Enterprise (Replicated / Kubernetes) + +The OHE installer has a built-in Vertex AI configuration path — select +`google_api_type = vertex` and enter your project, location, and service-account +credentials. However, the default published agent-server image does not include Vertex +support. You must either: + +- Provide a custom agent-server image built with `ENABLE_VERTEX=1`, or +- Use an image published by OpenHands that has Vertex enabled. + +### Claude via Vertex AI + +If you route Anthropic Claude through Google Vertex AI / Model Garden (rather than direct +Anthropic endpoints), use the `vertex_ai/` prefix with the Vertex-published model name, +which is date-stamped: + +- `Custom Model`: `vertex_ai/claude-3-5-sonnet@20240620` + +Use the exact model name shown in your Vertex AI Model Garden console. + + +Claude via Vertex AI may also require the anthropic[vertex] package in +addition to google-cloud-aiplatform. If you encounter +ModuleNotFoundError: No module named 'anthropic', ensure the image includes +both dependencies. + + +### Troubleshooting + +#### "No module named 'vertexai'" Error + +If you encounter this error: +``` +litellm.BadRequestError: Vertex_aiException BadRequestError - vertexai import failed +please run `pip install -U "google-cloud-aiplatform>=1.38"`. +Got error: No module named 'vertexai' +``` + +This means the agent-server image does not include the Vertex AI SDK. Enable the `vertex` +extra as described in [Vertex AI Dependencies](#vertex-ai-dependencies) above. From 793b1088e8c14474e51dbba38cc0c0ff5e06fbb7 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 26 Jun 2026 18:11:58 +0000 Subject: [PATCH 2/4] docs: remove unverified OHE Vertex claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The OHE LLM call path (direct vs. proxied through LiteLLM proxy) was not verified, so the claim that 'the default agent-server image does not include Vertex support' may not apply to OHE — the proxy may carry the Vertex deps. Removing until the OHE architecture is confirmed. Co-authored-by: openhands --- openhands/usage/llms/google-llms.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx index 1742c9fd7..084dc9dea 100644 --- a/openhands/usage/llms/google-llms.mdx +++ b/openhands/usage/llms/google-llms.mdx @@ -67,16 +67,6 @@ Then point OpenHands at your custom image via the `AGENT_SERVER_IMAGE_REPOSITORY `AGENT_SERVER_IMAGE_TAG` environment variables (see the [Custom Sandbox Guide](/openhands/usage/advanced/custom-sandbox-guide) for details). -#### OpenHands Enterprise (Replicated / Kubernetes) - -The OHE installer has a built-in Vertex AI configuration path — select -`google_api_type = vertex` and enter your project, location, and service-account -credentials. However, the default published agent-server image does not include Vertex -support. You must either: - -- Provide a custom agent-server image built with `ENABLE_VERTEX=1`, or -- Use an image published by OpenHands that has Vertex enabled. - ### Claude via Vertex AI If you route Anthropic Claude through Google Vertex AI / Model Garden (rather than direct From cf39b7c0e63c8798b5b5423874e69b719a4f1988 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 26 Jun 2026 18:16:54 +0000 Subject: [PATCH 3/4] docs: add accurate OHE Vertex path (LiteLLM proxy) OHE's default Vertex path routes through a LiteLLM proxy (agent-server uses litellm_proxy/... model), so the agent-server image does not need Vertex enabled. ENABLE_VERTEX=1 only matters for direct vertex_ai/* calls bypassing the proxy. Co-authored-by: openhands --- openhands/usage/llms/google-llms.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx index 084dc9dea..a44530d3a 100644 --- a/openhands/usage/llms/google-llms.mdx +++ b/openhands/usage/llms/google-llms.mdx @@ -67,6 +67,14 @@ Then point OpenHands at your custom image via the `AGENT_SERVER_IMAGE_REPOSITORY `AGENT_SERVER_IMAGE_TAG` environment variables (see the [Custom Sandbox Guide](/openhands/usage/advanced/custom-sandbox-guide) for details). +#### OpenHands Enterprise (Replicated / Kubernetes) + +The default OHE installer Vertex path routes LLM calls through a LiteLLM proxy — the +agent-server uses a `litellm_proxy/...` model, and the proxy makes the actual Vertex call. +So the agent-server image does **not** need Vertex enabled for the default path; `ENABLE_VERTEX=1` +is only relevant if you customize OHE to bypass the proxy and call `vertex_ai/*` directly from +the agent-server. + ### Claude via Vertex AI If you route Anthropic Claude through Google Vertex AI / Model Garden (rather than direct From 93966cad1dded11da945189ac54c8e55e41ac8d6 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 26 Jun 2026 18:23:58 +0000 Subject: [PATCH 4/4] docs: address review feedback on Vertex docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace uv sync --extra vertex with uv pip install (works outside source tree) - Add link to the agent-server Dockerfile and clarify repo-root working dir - Update Claude example to claude-sonnet-4-5@20250929 (current model) Kept anthropic[vertex] note — verified it IS a real PyPI extra (Provides-Extra: vertex -> google-auth[requests] in anthropic wheel METADATA). Co-authored-by: openhands --- openhands/usage/llms/google-llms.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx index a44530d3a..6b6d3a48d 100644 --- a/openhands/usage/llms/google-llms.mdx +++ b/openhands/usage/llms/google-llms.mdx @@ -47,13 +47,15 @@ Install the `vertex` extra in your Python environment: ```bash pip install "openhands-sdk[vertex]" -# or, with uv: -uv sync --extra vertex +# or, with uv (works in any Python environment): +uv pip install "openhands-sdk[vertex]" ``` #### Custom Agent-Server Image -Build the image with the `ENABLE_VERTEX` build flag: +Build the image with the `ENABLE_VERTEX` build flag (the Dockerfile is in the +[`software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/docker/Dockerfile) +repo; run from the repo root): ```bash docker build \ @@ -81,7 +83,7 @@ If you route Anthropic Claude through Google Vertex AI / Model Garden (rather th Anthropic endpoints), use the `vertex_ai/` prefix with the Vertex-published model name, which is date-stamped: -- `Custom Model`: `vertex_ai/claude-3-5-sonnet@20240620` +- `Custom Model`: `vertex_ai/claude-sonnet-4-5@20250929` Use the exact model name shown in your Vertex AI Model Garden console.