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

# Google Vertex AI

> Configure Google Cloud Vertex AI in Braintrust to access Google and partner models

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

Braintrust integrates with [Google Cloud Vertex AI](https://cloud.google.com/vertex-ai), so you can use models from Google and Vertex Model Garden partners through the Braintrust playground, API, and SDKs.

## Confirm model access in Google Cloud

Before configuring Braintrust, make sure your Google Cloud project can call the Vertex AI models you want to use.

1. Enable the [Vertex AI API](https://cloud.google.com/vertex-ai/docs/start/cloud-environment) in your Google Cloud project.
2. Confirm the model is available in the Vertex location you want to use. See [Generative AI locations](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/locations).
3. If you use a service account, grant it permissions to invoke Vertex AI models, such as the `AI Platform Developer` role.
4. Check your project's Vertex AI quotas for the model and location you plan to use.

## Configure the integration

1. Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="sparkle" /> AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets).

2. Add a new [organization or project provider](/admin/ai-providers) and choose **Google Vertex AI**.

3. Choose your authentication method:

   * **Access token**: Paste a Vertex AI OAuth access token.
   * **Service account key**: Paste the full service account key JSON. Braintrust exchanges it for an OAuth bearer token when sending requests to Vertex AI.
   * **Workload identity federation**: Exchange a Braintrust-signed OIDC token for a Vertex AI access token, instead of storing a long-lived Google credential in Braintrust.

   <Note>
     API keys are stored as one-way cryptographic hashes, never in plaintext.
   </Note>

   <Note>
     Workload identity federation is available only for organization-level providers on Braintrust-hosted organizations with the Braintrust gateway enabled. Project-level providers and self-hosted deployments must use **Access token** or **Service account key** authentication.
   </Note>

4. If you chose **Workload identity federation**, configure Google Cloud and Braintrust with the matching setup values:

   1. In Google Cloud, [create a workload identity pool and OIDC provider](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers). When you configure the OIDC provider:
      * Set the issuer to the **Issuer URL** shown in Braintrust.
      * Leave the **JWK file** blank. Braintrust serves its public keys at the issuer's OIDC discovery endpoint.
      * Keep the default allowed audience.
      * Add the **Attribute mapping** entries shown in Braintrust. Use each left-side value as the Google attribute name and paste the copied value as the CEL expression.
      * Add the **Attribute condition** shown in Braintrust.
   2. Back in Braintrust, enter the values that identify your Google Cloud setup:
      * **Google project number**: The numeric project number of the Google Cloud project that contains the workload identity pool.
      * **Workload identity pool ID**: The pool ID from Google IAM.
      * **Workload identity provider ID**: The OIDC provider ID inside the pool.
   3. In Google Cloud, grant the **IAM principal** now shown in Braintrust the `roles/aiplatform.user` role on the Google Cloud project that contains your Vertex AI resources.

   <Tip>
     The workload identity pool can live in a different Google Cloud project from the Vertex AI resources. **Google project number** is the numeric project number for the project that holds the workload identity pool, while the **Project** field below is the Vertex AI project ID.
   </Tip>

5. Set **Project** to the Google Cloud project ID where Vertex AI is enabled.

6. Optional: Set **Location** to the Vertex location where Braintrust should send requests.

   If you leave this blank, Braintrust uses `global`. Some built-in model definitions include their own supported locations, and Braintrust may use those model-specific locations before the provider-level location.

   <Warning>
     The `global` endpoint can improve availability and reduce 429 errors, but Google may route requests to any supported region. If you need to route LLM requests to a specific region, choose a Vertex location.
   </Warning>

7. Optional: Set **API base URL** only if you need a custom Vertex endpoint.

   By default, Braintrust uses `https://aiplatform.googleapis.com/` for `global` and `https://{location}-aiplatform.googleapis.com/` for regional locations.

8. Many [Vertex AI models](/deploy/supported-models) are available in Braintrust by default. To access these, leave **Include the default registry of Vertex AI models** enabled.

   If the model you want is not supported by default, you can [add the model manually](#add-models-manually).

9. Click **Save**.

## Add models manually

You only need to add a Vertex AI model manually if it does not appear in Braintrust's [supported models](/deploy/supported-models) list. This is common for newly released models, preview models, partner models, or models your Google Cloud project has special access to.

When you add a model manually:

1. Copy the exact Vertex model ID from Google Cloud.
2. Add it under **Models** in the Vertex AI provider settings.
3. Choose the matching Braintrust format.
4. If the model is only available in specific regions, add those regions under **Locations**.

Common model ID patterns:

* `publishers/google/models/gemini-2.5-flash` - Google Gemini model through Vertex AI.
* `publishers/anthropic/models/claude-haiku-4-5` - Anthropic Claude model through Vertex AI.
* `publishers/meta/models/llama-3.3-70b-instruct-maas` - Meta model served through Vertex AI Model Garden.

<Note>
  Prefer the full publisher model ID from Vertex AI when adding models manually. Short Google model IDs can work for Gemini models, but full IDs are clearer and avoid ambiguity across model families.
</Note>

## Next steps

* [Use models in the Braintrust playground](/evaluate/playgrounds)
* [Supported models in Braintrust](/deploy/supported-models)
* [Call models via the Braintrust API](/api-reference)

## Additional resources

* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)
* [Vertex AI Model Garden](https://cloud.google.com/vertex-ai/docs/model-garden/explore-models)
* [Generative AI locations](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)
* [Vertex AI REST endpoints reference](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.endpoints)
* [Vertex AI authentication](https://cloud.google.com/vertex-ai/docs/authentication)
* [Workload identity federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation)
* [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)