Google Gemini

O Hermes Agent suporta o Google Gemini como provedor nativo usando a API Gemini / Google AI Studio — e não o endpoint compatível com OpenAI. Assim o Hermes traduz seu laço interno de mensagens e ferramentas (no formato OpenAI) para a API nativa generateContent do Gemini, preservando chamadas de ferramenta, streaming, entradas multimodais e os metadados de resposta específicos do Gemini.

Pré-requisitos

• Chave de API do Google AI Studio — crie uma em aistudio.google.com/apikey
• Projeto do Google Cloud com faturamento ativo — recomendado para uso com agente. O nível gratuito do Gemini é pequeno demais para sessões longas de agente, porque o Hermes pode fazer várias chamadas ao modelo a cada turno do usuário.
• Hermes instalado — nenhum pacote Python adicional é necessário para o provedor nativo do Gemini.

Caminho da chave de API

Defina GOOGLE_API_KEY ou GEMINI_API_KEY. O Hermes verifica os dois nomes para o provedor gemini.

Início rápido

# Adicione sua chave de API do Gemini
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# Selecione o Gemini como provedor
hermes model
# → Escolha "More providers..." → "Google AI Studio"
# → O Hermes verifica o nível da sua chave e mostra os modelos Gemini
# → Selecione um modelo

# Comece a conversar
hermes chat

Se você preferir editar a configuração direto, use a URL base da API nativa do Gemini:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Configuração

Depois de rodar hermes model, seu ~/.hermes/config.yaml vai conter:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

E, em ~/.hermes/.env:

GOOGLE_API_KEY=...

API nativa do Gemini

O endpoint recomendado é:

https://generativelanguage.googleapis.com/v1beta

O Hermes detecta esse endpoint e cria seu adaptador nativo do Gemini. Internamente, o Hermes continua mantendo o laço do agente em mensagens no formato OpenAI e depois traduz cada requisição para o esquema nativo do Gemini:

• messages[] → contents[] do Gemini
• prompts de sistema → systemInstruction do Gemini
• esquemas de ferramenta → functionDeclarations do Gemini
• resultados de ferramenta → partes functionResponse do Gemini
• respostas em streaming → trechos de stream no formato OpenAI para o laço do Hermes

Assinaturas de pensamento do Gemini 3

No uso de ferramentas com o Gemini 3, o Hermes preserva os valores thoughtSignature anexados às partes de chamada de função e os reenvia no turno de ferramenta seguinte. Isso cobre o caminho crítico de validação para fluxos de agente em várias etapas.

O Gemini 3 também pode anexar assinaturas de pensamento a outras partes da resposta. O adaptador nativo do Hermes está otimizado hoje para laços de ferramentas do agente, então ele ainda não reenvia todas as assinaturas fora de chamadas de função com fidelidade total por parte.

Prefira o endpoint nativo

O Google também expõe um endpoint compatível com OpenAI:

https://generativelanguage.googleapis.com/v1beta/openai/

Para sessões de agente do Hermes, prefira o endpoint nativo do Gemini acima. O Hermes inclui um adaptador nativo do Gemini, então consegue mapear uso de ferramentas em vários turnos, resultados de chamadas de ferramenta, streaming, entradas multimodais e metadados de resposta do Gemini diretamente para a API generateContent. O endpoint compatível com OpenAI continua útil quando você precisa especificamente de compatibilidade com a API da OpenAI.

Se você já tinha definido GEMINI_BASE_URL com a URL /openai, remova ou altere:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Modelos disponíveis

O seletor hermes model mostra os modelos Gemini mantidos no registro de provedores do Hermes. Escolhas comuns incluem:

Modelo	ID	Observações
Gemini 3.7 Flash	gemini-3.7-flash	Padrão recomendado; bom equilíbrio entre velocidade, capacidade e compreensão multimodal
Gemini 3.1 Pro Preview	gemini-3.1-pro-preview	Modelo mais capaz em raciocínio, matemática e programação
Gemini 3.5 Flash Lite	gemini-3.5-flash-lite	Opção mais rápida e de menor custo para tarefas leves
Gemini 2.5 Flash	gemini-2.5-flash	Modelo rápido da geração anterior, com capacidade de raciocínio
Gemini 2.5 Pro	gemini-2.5-pro	Modelo de raciocínio complexo da geração anterior

A disponibilidade de modelos muda com o tempo. Se um modelo sumir ou não estiver habilitado para sua chave, rode hermes model de novo e escolha um da lista atual.

IDs de modelo

Com provider: gemini, use os IDs nativos do Gemini, como gemini-3.7-flash, e não IDs no estilo OpenRouter, como google/gemini-3.7-flash.

Apelidos "latest"

O Google publica apelidos móveis para as famílias Pro e Flash do Gemini. gemini-pro-latest e gemini-flash-latest são úteis quando você quer que o Google avance o modelo automaticamente sem mexer na sua configuração do Hermes. Atenção: suas cobranças de uso podem mudar se os modelos novos tiverem tarifas diferentes.

Apelido	Aponta hoje para	Observações
gemini-pro-latest	Modelo Gemini Pro mais recente	Melhor quando você quer o Pro padrão atual do Google
gemini-flash-latest	Modelo Gemini Flash mais recente	Melhor quando você quer o Flash padrão atual do Google

model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Se você precisa de reprodutibilidade estrita, prefira IDs explícitos, como gemini-3.1-pro-preview ou gemini-3.7-flash.

Gemma pela API do Gemini

O Google também expõe modelos Gemma pela API do Gemini. O Hermes reconhece esses modelos como modelos do Google, mas esconde do seletor padrão as entradas Gemma de vazão muito baixa, para que usuários novos não escolham sem querer um modelo de nível de avaliação para uma sessão longa de agente.

IDs úteis para avaliação:

Modelo	ID	Observações
Gemma 4 31B IT	gemma-4-31b-it	Modelo Gemma maior; útil para avaliar compatibilidade e qualidade
Gemma 4 26B A4B IT	gemma-4-26b-a4b-it	Variante menor, de parâmetros ativos, quando disponível

Trate esses modelos como opções de avaliação em chaves da API Gemini. A cobrança do Google para a API Gemma é só de nível gratuito, e os limites de uso são baixos em comparação com os modelos Gemini de produção; então, para uso sustentado do agente Hermes, migre para um modelo Gemini pago, uma implantação própria ou outro provedor com cota adequada.

Para usar um modelo Gemma escondido do seletor, defina-o diretamente:

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Trocar de modelo no meio da sessão

Use o comando /model durante uma conversa:

/model gemini-3.7-flash
/model gemini-flash-latest
/model gemini-3.1-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

Se você ainda não configurou o Gemini, saia da sessão e rode hermes model antes. O /model alterna entre provedores e modelos já configurados; ele não coleta chaves de API novas.

Diagnóstico

hermes doctor

O doctor verifica:

• Se GOOGLE_API_KEY ou GEMINI_API_KEY está disponível
• Se as credenciais dos provedores configurados podem ser resolvidas

Gateway (plataformas de mensagem)

O Gemini funciona com todas as plataformas de gateway do Hermes (Telegram, Discord, Slack, WhatsApp, LINE, Feishu etc.). Configure o Gemini como provedor e inicie o gateway normalmente:

hermes gateway setup
hermes gateway start

O gateway lê o config.yaml e usa a mesma configuração do provedor Gemini.

Solução de problemas

"Gemini native client requires an API key"

O Hermes não encontrou uma chave de API utilizável. Adicione uma destas ao ~/.hermes/.env:

GOOGLE_API_KEY=...
# ou
GEMINI_API_KEY=...

Depois rode hermes model de novo.

"This Google API key is on the free tier"

O Hermes sonda as chaves da API Gemini durante a configuração. As cotas do nível gratuito podem se esgotar depois de poucos turnos do agente, porque uso de ferramentas, novas tentativas, compressão e tarefas auxiliares podem exigir várias chamadas ao modelo.

Ative o faturamento no projeto do Google Cloud associado à sua chave, gere a chave de novo se precisar e então rode:

hermes model

"404 model not found"

O modelo selecionado não está disponível para a sua conta, região ou chave. Rode hermes model de novo e escolha outro modelo Gemini da lista atual.

O modelo Gemma não aparece em hermes model

O Hermes pode esconder do seletor, por padrão, modelos Gemma de vazão baixa. Se você quer mesmo avaliar um deles, defina o ID do modelo diretamente no ~/.hermes/config.yaml.

"429 quota exceeded" no Gemma

Os modelos Gemma expostos pela API do Gemini são úteis para avaliação, mas seus limites de nível gratuito na API Gemini são baixos. Use-os para testar compatibilidade e depois troque por um modelo Gemini pago ou outro provedor para sessões de agente contínuas.

O endpoint compatível com OpenAI está configurado

Verifique no ~/.hermes/.env se há:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

Troque pelo endpoint nativo ou remova a sobrescrita:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

As chamadas de ferramenta falham com erros de esquema

Atualize o Hermes e rode hermes model de novo. O adaptador nativo do Gemini higieniza os esquemas de ferramenta para o formato mais estrito de declaração de funções do Gemini; builds antigos ou endpoints personalizados podem não fazer isso.

Relacionados

• Provedores de IA
• Configuração
• Provedores de reserva
• AWS Bedrock — integração nativa com provedor de nuvem usando credenciais da AWS

---