> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Vertex

> Set up Ona Agent to use Google Vertex

<Note>Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.</Note>

Ona Agent supports direct integration with Google Vertex AI. Supported models: Anthropic Claude Opus 4.8 and Sonnet 4.6.

## Prerequisites

* You must have a Google Cloud Platform (GCP) account with [Vertex AI enabled](https://cloud.google.com/vertex-ai/docs/start/introduction).
* You must enable the Anthropic Claude models you want to use in [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden). Each model is enabled per project and may require a quota request. Enabling the Vertex AI API alone is not sufficient.
* You must have an Ona enterprise license.
* Your runner must be able to reach `aiplatform.googleapis.com` over HTTPS. For runners that egress through a private VPC, this means either Private Google Access on the runner's subnet or a NAT gateway with outbound internet access. Without this, agent calls fail with connection errors.

## Set up Google Cloud authentication

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Navigate to **IAM & Admin** > **Service Accounts**
3. Click **Create Service Account**
4. Enter a name and description for your service account
5. Click **Create and Continue**
6. Grant the following roles:
   * `Vertex AI User`
7. Click **Continue** and then **Done**
8. Click on the created service account
9. Go to the **Keys** tab
10. Click **Add Key** > **Create new key**
11. Select **JSON** format and click **Create**
12. Save the downloaded JSON key file securely

<img src="https://mintcdn.com/gitpod-13c83c2b/Qe884b1ciQ7Jkdxb/images/vertex-service-account.png?fit=max&auto=format&n=Qe884b1ciQ7Jkdxb&q=85&s=69b3cd332f4af1c2d05973ac7df66871" alt="GCP IAM Service Accounts page showing the process of creating a new service account with Vertex AI User role" width="4082" height="2254" data-path="images/vertex-service-account.png" />

## Configure the Vertex AI endpoint

### Endpoint format

```bash theme={null}
vertex://${region}/${model-version}
```

Use the [global](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai) region for dynamic routing across available infrastructure.

## Add the configuration to Ona

You can configure a Vertex integration in two ways:

* [Ona CLI](/ona/integrations/cli)
* Through the UI

### Option 1: Ona CLI

```bash theme={null}
export VERTEX_SERVICE_ACCOUNT_JSON=$(cat /path/to/service-account.json)

ona runner config llm-integration create <runner-id> SUPPORTED_MODEL_SONNET_4 vertex://global/claude-sonnet-4@20250514 "$VERTEX_SERVICE_ACCOUNT_JSON"

ona runner config llm-integration list
```

Refer to the Endpoint format section above for model and region values.

### Option 2: Through the UI

1. Go to the [Runners settings page](https://app.ona.com/settings/runners)

2. Select an enterprise runner where you want to enable LLM integration

3. Scroll down to the "LLM Providers" section

4. Click the **Configure** button

5. Fill in the configuration:
   * **Region**: Enter the region of your Vertex AI endpoint, we recommend using the global region for dynamic routing across available infrastructure.
   * **Model Version**: Enter the model version you want to use, for example `claude-sonnet-4@20250514`. See [Anthropic's model availability](https://docs.anthropic.com/en/api/claude-on-vertex-ai#model-availability).
   * **Service Account JSON**: Drag a service account file here.

6. Click **Create Integration**

<img src="https://mintcdn.com/gitpod-13c83c2b/Esg9fHi7gt5_JkZs/images/configure-llm-integration.png?fit=max&auto=format&n=Esg9fHi7gt5_JkZs&q=85&s=89ecd9c3a2482a6a523529913e72be9a" alt="LLM integration form with fields for region, model version, and service account JSON upload" width="4076" height="2226" data-path="images/configure-llm-integration.png" />

## Verify the integration

1. Create a new environment with the configured runner
2. Open Ona Agent and start a session - if you see Ona Agent responding, the integration is working.
3. Test with a simple code generation request

## Supported models

Ona Agent supports Anthropic Claude Opus 4.8 and Sonnet 4.6 on Google Vertex AI.

## Next steps

* Explore [Google Vertex AI model documentation](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/overview) for model-specific capabilities
* Learn about [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing) to optimize costs
* Set up monitoring and logging for your AI usage

## Troubleshooting

<Accordion title="Common issues">
  **Authentication errors**

  * Verify your service account has the correct IAM roles
  * Ensure the JSON key file is valid and properly formatted
  * Check that the Vertex AI API is enabled for your project

  **Endpoint not found**

  * Verify your project ID, region, and model name in the endpoint URL
  * Ensure the model is available in your selected region

  **Permission denied**

  * Check that your service account has `Vertex AI User` role
  * Verify your project has billing enabled
  * Ensure Vertex AI API is enabled
</Accordion>

<Accordion title="Getting help">
  If you encounter issues:

  1. Check the Ona Agent logs for detailed error messages
  2. Verify your Google Cloud quotas and limits
  3. Contact your account manager for additional support
</Accordion>