mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-26 17:38:36 +00:00
d84e11af4d
Removes Homebrew and PyPI wheel/sdist as Hermes distribution paths while
preserving the supported source, Docker, and Nix workflows.
Changes:
- Removes the Homebrew formula, PyPI publish workflow, sdist manifest
(MANIFEST.in), and wheel/sdist release-attachment logic from scripts/release.py.
- Keeps setuptools metadata and entry points required by editable installs
and Docker/Nix builds, but adds a setup.py guard that rejects wheel/sdist
builds outside a sealed Nix derivation (HERMES_NIX_BUILD=1).
- Removes pip/Homebrew install detection, PyPI update checks, the pip
self-update path, the deprecation-banner state, the postinstall subcommand,
wheel data-directory fallbacks in agent/i18n.py and hermes_constants.py,
and the ACP Registry manifest/version-lockstep release logic.
- Adds /nix/store/ path detection so `nix run` / `nix profile install`
installs (which don't set HERMES_MANAGED) are correctly identified as
"nix" rather than falling through to "git"/"unknown".
- Retired install-method values ("pip", "homebrew") in existing
.install_method stamps (both code-scoped and home-scoped) are ignored by
the allowlist reader and fall through to "unknown" instead of resurrecting
a retired enum value.
- Updates Nix packaging to ship bare runtime data (locales, optional-mcps)
through store symlinks and wrapper env vars instead of wheel data-files.
- Removes the ACP Registry manifest/icon and their version-lockstep tests.
- Deletes or rewrites packaging, pip-update, Homebrew, and ACP Registry
tests; adds parametrized coverage for the packaging build guard covering
BOTH sdist and wheel paths (the guards live in separate cmdclass entries
— a passing sdist test proves nothing about the wheel path).
- Updates installation/platform documentation and related user-facing copy.
- Adjusts the supply-chain scan so deleted install-hook files do not trigger
a finding, while additions or modifications still require the existing
ci-reviewed label gate.
Supported installation paths (unchanged):
- git installer (install.sh)
- Docker
- Nix/NixOS
- editable development installs (uv sync, uv pip install -e ., pip install -e .)
146 lines
6.5 KiB
Markdown
146 lines
6.5 KiB
Markdown
---
|
|
sidebar_position: 15
|
|
title: "Google Vertex AI"
|
|
description: "Use Hermes Agent with Gemini on Google Cloud Vertex AI — OAuth2 service account or ADC, GCP billing and quotas, no static API key"
|
|
---
|
|
|
|
# Google Vertex AI
|
|
|
|
Hermes Agent supports **Gemini models on Google Cloud Vertex AI** through Vertex's OpenAI-compatible endpoint. Unlike the [Google AI Studio provider](/guides/google-gemini) (which uses a static API key against `generativelanguage.googleapis.com`), Vertex gives you **enterprise-grade rate limits and GCP billing/credits**, and is the right choice when you want Gemini usage to draw on your Google Cloud account rather than an AI Studio key.
|
|
|
|
:::info Vertex authenticates with OAuth2, not an API key
|
|
Vertex has **no static API key** for the standard endpoint. Every request needs a short-lived **OAuth2 access token** (≈1 hour TTL) minted from either a service-account JSON or Application Default Credentials (ADC). Hermes mints and **auto-refreshes** these tokens for you — you never paste a token by hand. This is why pasting a temporary token into a custom provider's `api_key` field does not work: it expires mid-session.
|
|
:::
|
|
|
|
## Prerequisites
|
|
|
|
- **A Google Cloud project** with the **Vertex AI API enabled** and billing active.
|
|
- **Credentials**, one of:
|
|
- a **service-account JSON** key file with the `roles/aiplatform.user` role, or
|
|
- **Application Default Credentials** via `gcloud auth application-default login` (or the metadata server when running on a GCP VM).
|
|
- **`google-auth`** — installed automatically the first time you select Vertex (lazy install). Run `hermes setup` to repair a managed install if that fails.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Option A — service account JSON (recommended for servers / gateways)
|
|
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env
|
|
|
|
# Option B — Application Default Credentials (good for local dev)
|
|
gcloud auth application-default login
|
|
|
|
# Select Vertex as your provider
|
|
hermes model
|
|
# → Choose "More providers..." → "Google Vertex AI"
|
|
# → Enter your GCP project ID (or leave blank to use the one in your credentials)
|
|
# → Choose a region (default: global)
|
|
# → Select a Gemini model
|
|
|
|
# Start chatting
|
|
hermes chat
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Vertex splits its settings by sensitivity:
|
|
|
|
- The **credential path** is a pointer to a secret and lives in `~/.hermes/.env`.
|
|
- **Project ID and region** are non-secret routing settings and live in `~/.hermes/config.yaml`.
|
|
|
|
`~/.hermes/.env`:
|
|
|
|
```bash
|
|
# One of these (checked in this order); omit both to use ADC:
|
|
VERTEX_CREDENTIALS_PATH=/path/to/service-account.json
|
|
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
|
```
|
|
|
|
`~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
model:
|
|
default: google/gemini-3-flash-preview
|
|
provider: vertex
|
|
|
|
vertex:
|
|
project_id: my-gcp-project # blank → use the project embedded in the credentials
|
|
region: global # "global" is required for the Gemini 3.x previews
|
|
```
|
|
|
|
:::tip Environment variables win over config.yaml
|
|
`VERTEX_PROJECT_ID` and `VERTEX_REGION` override the `vertex.project_id` / `vertex.region` values in `config.yaml`. Use them for per-shell overrides; keep the durable settings in `config.yaml`.
|
|
:::
|
|
|
|
### How authentication works
|
|
|
|
1. Hermes resolves credentials in this order: `VERTEX_CREDENTIALS_PATH` → `GOOGLE_APPLICATION_CREDENTIALS` → ADC.
|
|
2. It mints an OAuth2 access token (`cloud-platform` scope) and caches it, refreshing when the token is within 5 minutes of expiry.
|
|
3. The token is handed to a standard OpenAI client pointed at the Vertex endpoint:
|
|
```text
|
|
https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi
|
|
```
|
|
Regional locations use a `{region}-aiplatform.googleapis.com` host instead.
|
|
4. If a session runs longer than the token lifetime and a request returns `401`, Hermes re-mints the token and retries automatically. On a long-running gateway, if ADC's refresh token has itself expired, Hermes falls back to the service-account JSON when one is configured.
|
|
|
|
## Available Models
|
|
|
|
Vertex requires the `google/` vendor prefix on model IDs. The `hermes model` picker offers:
|
|
|
|
| Model | ID |
|
|
|-------|----|
|
|
| Gemini 3.1 Pro Preview | `google/gemini-3.1-pro-preview` |
|
|
| Gemini 3 Pro Preview | `google/gemini-3-pro-preview` |
|
|
| Gemini 3 Flash Preview | `google/gemini-3-flash-preview` |
|
|
| Gemini 3.1 Flash Lite Preview | `google/gemini-3.1-flash-lite-preview` |
|
|
| Gemini 2.5 Pro | `google/gemini-2.5-pro` |
|
|
| Gemini 2.5 Flash | `google/gemini-2.5-flash` |
|
|
|
|
:::note `global` region for Gemini 3.x
|
|
The Gemini 3.x preview models are served through the `global` endpoint. Regional endpoints (`us-central1`, etc.) may 404 them. Leave `region: global` unless you have a specific reason to pin a region.
|
|
:::
|
|
|
|
## Switching Models Mid-Session
|
|
|
|
```text
|
|
/model google/gemini-3-pro-preview
|
|
/model google/gemini-3-flash-preview
|
|
```
|
|
|
|
`/model` switches among already-configured providers and models; it does not collect new credentials. Configure Vertex with `hermes model` first.
|
|
|
|
## Reasoning / Thinking
|
|
|
|
Vertex exposes Gemini's thinking budget through the OpenAI-compatible surface. Hermes maps its reasoning-effort setting onto `extra_body.google.thinking_config` automatically, so `reasoning_effort` works the same way it does on other Gemini surfaces.
|
|
|
|
## Diagnostics
|
|
|
|
```bash
|
|
hermes doctor
|
|
```
|
|
|
|
The doctor reports whether Vertex credentials can be resolved (service-account path or ADC) and whether the provider is configured.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Vertex AI credentials could not be resolved"
|
|
|
|
Hermes found neither a service-account JSON nor working ADC. Either set `VERTEX_CREDENTIALS_PATH` in `~/.hermes/.env`, or run `gcloud auth application-default login`. If your project isn't embedded in the credentials, set `vertex.project_id` in `config.yaml`.
|
|
|
|
### `google-auth` not installed
|
|
|
|
Hermes lazy-installs it the first time you select the Vertex provider. If that fails, run `hermes setup` to repair the managed install.
|
|
|
|
### 404 on Gemini 3.x models
|
|
|
|
You are probably on a regional endpoint. Set `region: global` in the `vertex:` section of `config.yaml` (or unset `VERTEX_REGION`).
|
|
|
|
### 403 / permission denied
|
|
|
|
The service account (or your ADC identity) needs the `roles/aiplatform.user` role on the project, and the Vertex AI API must be enabled for that project.
|
|
|
|
## Related
|
|
|
|
- [Google Gemini (AI Studio)](/guides/google-gemini) — static-API-key Gemini without GCP
|
|
- [AWS Bedrock](/guides/aws-bedrock) — another native cloud-provider integration
|
|
- [AI Providers](/integrations/providers)
|
|
- [Configuration](/user-guide/configuration)
|