# Google Vertex AI

> Run Pullfrog on models hosted in your own Google Cloud project through Vertex AI.

Route Pullfrog's model calls through [Vertex AI](https://cloud.google.com/vertex-ai) in your own Google Cloud project. Use it when your team already buys through Google Cloud, holds Vertex model-access approvals, or wants Google Cloud's audit and billing controls around inference.

## Setup

### Store a service-account key

Create a Google Cloud service account with the `roles/aiplatform.user` role and download a JSON key. In the Pullfrog console, click **Set up** on the **Google Vertex AI** tile of the **Providers** card and paste the whole JSON object as `VERTEX_SERVICE_ACCOUNT_JSON`.

You can store it as a GitHub Actions secret instead and map it in the workflow's `env:` block.

### Set the project, location and model in your workflow

Add these to the workflow's `env:` block. None of them is secret.

`.github/workflows/pullfrog.yml`:

```yaml
- name: Run agent
  uses: pullfrog/pullfrog@v0
  with:
    prompt: ${{ inputs.prompt }}
  env:
    GOOGLE_CLOUD_PROJECT: my-project
    VERTEX_LOCATION: global
    VERTEX_MODEL_ID: <vertex-model-id>
    # only when the key is a GitHub Actions secret
    VERTEX_SERVICE_ACCOUNT_JSON: ${{ secrets.VERTEX_SERVICE_ACCOUNT_JSON }}
```

### Enable the API and the model

Enable the Vertex AI API (`aiplatform.googleapis.com`) for the project, then enable any gated model in [Model Garden](https://console.cloud.google.com/agent-platform/model-garden).

### Pick the model

Open the **Model** card's editor, choose **Manual** and pick **Google Vertex AI** from the model menu.

## Variables

| Name | Secret | Purpose |
| --- | --- | --- |
| `VERTEX_SERVICE_ACCOUNT_JSON` | Yes | The full service-account JSON key, not a file path. |
| `GOOGLE_CLOUD_PROJECT` | No | Project ID. Optional when the JSON key has a `project_id`. |
| `VERTEX_LOCATION` | No | Vertex location. Use `global` unless data residency needs a regional endpoint. |
| `VERTEX_MODEL_ID` | No | Exact Vertex model ID. Pullfrog runs it as written and never upgrades it. |

A value stored in the console needs no `env:` line, because Pullfrog injects it into every run. A value set in the workflow wins over a stored one.

> On an account that pays through [Pullfrog Router](https://pullfrog.com/docs/router), store the service-account key in the Pullfrog console. Pullfrog decides how to fund a run before the runner starts, when GitHub Actions secrets are not visible to it, so a run whose key exists only there falls back to the Router's default model.

## Model IDs

The model menu has a single **Google Vertex AI** entry; `VERTEX_MODEL_ID` names the actual model. Use the ID that Model Garden shows for a Claude, Gemini or partner model your project has enabled, and edit the variable to change models.

## Routing

Pullfrog reads the model ID to choose the agent:

- **Claude models**, whose ID starts with `claude-`, run on [Claude Code](https://code.claude.com/docs/en/google-vertex-ai). Pullfrog sets `CLAUDE_CODE_USE_VERTEX=1` and passes the project and location in Claude Code's own variable names.
- **Every other model** runs on OpenCode's `google-vertex` provider.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| "`VERTEX_MODEL_ID` must be set when the model is `vertex/byok`" | The repository uses Google Vertex AI, but the workflow does not set `VERTEX_MODEL_ID`. Add it to `env:`. |
| "Google Vertex AI is missing required settings" | The message lists each missing value: `VERTEX_SERVICE_ACCOUNT_JSON`, `GOOGLE_CLOUD_PROJECT` (when the key has no `project_id`), `VERTEX_LOCATION`, or `VERTEX_MODEL_ID`. |
| Google authentication error | `VERTEX_SERVICE_ACCOUNT_JSON` must hold the JSON object itself, not a file path. Pullfrog writes it to a credentials file on the runner and sets `GOOGLE_APPLICATION_CREDENTIALS` for the agent. |
| Permission or model-access error | Check that the service account has `roles/aiplatform.user`, the Vertex AI API is on, and the model is enabled in Model Garden for `VERTEX_LOCATION`. |
