Google Vertex AI

O Hermes Agent suporta modelos Gemini no Google Cloud Vertex AI através do endpoint compatível com OpenAI do Vertex. Diferente do provedor Google AI Studio (que usa uma chave de API estática contra generativelanguage.googleapis.com), o Vertex oferece limites de taxa de nível corporativo e faturamento/créditos do GCP, e é a escolha certa quando você quer que o uso do Gemini saia da sua conta do Google Cloud em vez de uma chave do AI Studio.

O Vertex autentica com OAuth2, não com chave de API

O Vertex não tem chave de API estática para o endpoint padrão. Toda requisição precisa de um token de acesso OAuth2 de vida curta (TTL de aproximadamente 1 hora) gerado a partir de um JSON de conta de serviço ou das Application Default Credentials (ADC). O Hermes gera e renova automaticamente esses tokens para você — você nunca cola um token na mão. É por isso que colar um token temporário no campo api_key de um provedor personalizado não funciona: ele expira no meio da sessão.

Pré-requisitos

• Um projeto do Google Cloud com a API do Vertex AI ativada e faturamento ativo.
• Credenciais, uma destas:
  • um arquivo de chave JSON de conta de serviço com o papel roles/aiplatform.user, ou
  • Application Default Credentials via gcloud auth application-default login (ou o servidor de metadados quando você roda em uma VM do GCP).
• google-auth — instalado automaticamente na primeira vez que você seleciona o Vertex (instalação preguiçosa). Rode hermes setup para reparar uma instalação gerenciada se isso falhar.

Início rápido

# Opção A — JSON de conta de serviço (recomendado para servidores / gateways)
echo "VERTEX_CREDENTIALS_PATH=/caminho/da/conta-de-servico.json" >> ~/.hermes/.env

# Opção B — Application Default Credentials (bom para desenvolvimento local)
gcloud auth application-default login

# Selecione o Vertex como seu provedor
hermes model
# → Escolha "More providers..." → "Google Vertex AI"
# → Informe o ID do seu projeto GCP (ou deixe em branco para usar o das credenciais)
# → Escolha uma região (padrão: global)
# → Selecione um modelo Gemini

# Comece a conversar
hermes chat

Configuração

O Vertex separa suas opções por sensibilidade:

• O caminho da credencial é um ponteiro para um segredo e fica em ~/.hermes/.env.
• ID do projeto e região são opções de roteamento não secretas e ficam em ~/.hermes/config.yaml.

~/.hermes/.env:

# Uma destas (verificadas nesta ordem); omita as duas para usar ADC:
VERTEX_CREDENTIALS_PATH=/caminho/da/conta-de-servico.json
GOOGLE_APPLICATION_CREDENTIALS=/caminho/da/conta-de-servico.json

~/.hermes/config.yaml:

model:
  default: google/gemini-3-flash-preview
  provider: vertex

vertex:
  project_id: meu-projeto-gcp   # em branco → usa o projeto embutido nas credenciais
  region: global                # "global" é obrigatório para os previews do Gemini 3.x

Variáveis de ambiente vencem o config.yaml

VERTEX_PROJECT_ID e VERTEX_REGION sobrescrevem os valores vertex.project_id / vertex.region do config.yaml. Use as variáveis para sobrescritas por shell; mantenha as opções duradouras no config.yaml.

Como a autenticação funciona

1. O Hermes resolve as credenciais nesta ordem: VERTEX_CREDENTIALS_PATH → GOOGLE_APPLICATION_CREDENTIALS → ADC.
2. Ele gera um token de acesso OAuth2 (escopo cloud-platform) e guarda em cache, renovando quando faltam menos de 5 minutos para expirar.
3. O token é entregue a um cliente OpenAI padrão apontado para o endpoint do Vertex:

   https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi

   Localizações regionais usam um host {region}-aiplatform.googleapis.com no lugar.
4. Se uma sessão durar mais que a vida do token e uma requisição retornar 401, o Hermes gera o token de novo e repete a chamada automaticamente. Em um gateway de longa duração, se o refresh token do ADC também tiver expirado, o Hermes recorre ao JSON de conta de serviço quando há um configurado.

Modelos disponíveis

O Vertex exige o prefixo de fornecedor google/ nos IDs de modelo. O seletor hermes model oferece:

Modelo	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

Região global para o Gemini 3.x

Os modelos de preview do Gemini 3.x são servidos pelo endpoint global. Endpoints regionais (us-central1 e afins) podem devolver 404 para eles. Deixe region: global a menos que você tenha um motivo específico para fixar uma região.

Trocar de modelo no meio da sessão

/model google/gemini-3-pro-preview
/model google/gemini-3-flash-preview

O /model troca entre provedores e modelos já configurados; ele não coleta credenciais novas. Configure o Vertex com hermes model antes.

Raciocínio / pensamento

O Vertex expõe o orçamento de pensamento do Gemini pela superfície compatível com OpenAI. O Hermes mapeia sua configuração de esforço de raciocínio para extra_body.google.thinking_config automaticamente, então reasoning_effort funciona do mesmo jeito que nas outras superfícies do Gemini.

Diagnóstico

hermes doctor

O doctor informa se as credenciais do Vertex podem ser resolvidas (caminho da conta de serviço ou ADC) e se o provedor está configurado.

Solução de problemas

"Vertex AI credentials could not be resolved"

O Hermes não encontrou nem um JSON de conta de serviço nem ADC funcionando. Defina VERTEX_CREDENTIALS_PATH em ~/.hermes/.env ou rode gcloud auth application-default login. Se o seu projeto não estiver embutido nas credenciais, defina vertex.project_id no config.yaml.

google-auth não instalado

O Hermes instala essa biblioteca de forma preguiçosa na primeira vez que você seleciona o provedor Vertex. Se isso falhar, rode hermes setup para reparar a instalação gerenciada.

404 em modelos Gemini 3.x

Você provavelmente está em um endpoint regional. Defina region: global na seção vertex: do config.yaml (ou remova VERTEX_REGION).

403 / permissão negada

A conta de serviço (ou a sua identidade do ADC) precisa do papel roles/aiplatform.user no projeto, e a API do Vertex AI precisa estar ativada nesse projeto.

Relacionados

• Google Gemini (AI Studio) — Gemini com chave de API estática, sem GCP
• AWS Bedrock — outra integração nativa com provedor de nuvem
• Provedores de IA
• Configuração

---