> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-vertex-agent-server-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Gemini/Vertex

> OpenHands uses LiteLLM to make calls to Google's chat models. You can find their documentation on using Google as a provider -> [Gemini - Google AI Studio](https://docs.litellm.ai/docs/providers/gemini), [VertexAI - Google Cloud Platform](https://docs.litellm.ai/docs/providers/vertex)

## Gemini - Google AI Studio Configs

When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:

* `LLM Provider` to `Gemini`
* `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. gemini/\<model-name> like `gemini/gemini-2.0-flash`).
* `API Key` to your Gemini API key

## VertexAI - Google Cloud Platform Configs

To use Vertex AI through Google Cloud Platform when running OpenHands, you'll need to set the following environment
variables using `-e` in the docker run command:

```
GOOGLE_APPLICATION_CREDENTIALS="<json-dump-of-gcp-service-account-json>"
VERTEXAI_PROJECT="<your-gcp-project-id>"
VERTEXAI_LOCATION="<your-gcp-location>"
```

Then set the following in the OpenHands UI through the Settings under the `LLM` tab:

* `LLM Provider` to `VertexAI`
* `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:

<Note>
  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 <code>ModuleNotFoundError: No module named
  'vertexai'</code> error when the agent tries to call a Vertex AI model.
</Note>

#### Local / Non-Docker Install

Install the `vertex` extra in your Python environment:

```bash theme={null}
pip install "openhands-sdk[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 (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 theme={null}
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 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
Anthropic endpoints), use the `vertex_ai/` prefix with the Vertex-published model name,
which is date-stamped:

* `Custom Model`: `vertex_ai/claude-sonnet-4-5@20250929`

Use the exact model name shown in your Vertex AI Model Garden console.

<Note>
  Claude via Vertex AI may also require the <code>anthropic\[vertex]</code> package in
  addition to <code>google-cloud-aiplatform</code>. If you encounter
  <code>ModuleNotFoundError: No module named 'anthropic'</code>, ensure the image includes
  both dependencies.
</Note>

### 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.