Skill do Google Workspace

Integração com Gmail, Agenda, Drive, Contatos, Planilhas e Documentos para o Hermes. Usa OAuth2 com renovação automática de token. Prefere a CLI do Google Workspace (gws) quando ela está disponível, por cobrir mais coisas, e recorre às bibliotecas Python do Google quando não está.

Caminho da skill: skills/productivity/google-workspace/

Configuração

A configuração é toda conduzida pelo agente — peça ao Hermes para configurar o Google Workspace e ele guia você passo a passo. O fluxo:

1. Crie um projeto no Google Cloud e habilite as APIs necessárias (Gmail, Calendar, Drive, Sheets, Docs, People)
2. Crie credenciais OAuth 2.0 (do tipo Desktop app) e baixe o JSON com o segredo do cliente
3. Autorize — o Hermes gera uma URL de autorização, você aprova no navegador e cola de volta a URL de redirecionamento
4. Pronto — daí em diante o token se renova sozinho

Só precisa de e-mail?

Se você só precisa de e-mail (sem Agenda/Drive/Planilhas), use a skill himalaya — ela funciona com uma senha de aplicativo do Gmail e leva 2 minutos. Não precisa de projeto no Google Cloud.

Gmail

Buscar

$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:chefe@empresa.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"

Devolve um JSON com id, from, subject, date, snippet e labels de cada mensagem.

Ler

$GAPI gmail get MESSAGE_ID

Devolve o corpo completo da mensagem em texto (prefere texto puro, cai para HTML se não houver).

Enviar

# Envio simples
$GAPI gmail send --to usuario@exemplo.com --subject "Olá" --body "Texto da mensagem"

# E-mail em HTML
$GAPI gmail send --to usuario@exemplo.com --subject "Relatório" \
  --body "<h1>Resultados do 4º trimestre</h1><p>Detalhes aqui</p>" --html

# Cabeçalho From personalizado (nome exibido + e-mail)
$GAPI gmail send --to usuario@exemplo.com --subject "Olá" \
  --from '"Agente de Pesquisa" <usuario@exemplo.com>' --body "Texto da mensagem"

# Com cópia
$GAPI gmail send --to usuario@exemplo.com --cc "time@exemplo.com" \
  --subject "Atualização" --body "Para conhecimento"

Cabeçalho From personalizado

A opção --from permite personalizar o nome de exibição do remetente nos e-mails enviados. Isso é útil quando vários agentes compartilham a mesma conta do Gmail, mas você quer que os destinatários vejam nomes diferentes:

# Agente 1
$GAPI gmail send --to cliente@co.com --subject "Resumo da pesquisa" \
  --from '"Agente de Pesquisa" <compartilhado@empresa.com>' --body "..."

# Agente 2  
$GAPI gmail send --to cliente@co.com --subject "Revisão de código" \
  --from '"Assistente de Código" <compartilhado@empresa.com>' --body "..."

Como funciona: o valor de --from vira o cabeçalho From (RFC 5322) da mensagem MIME. O Gmail permite personalizar o nome de exibição no seu próprio endereço autenticado, sem configuração extra. Os destinatários veem o nome personalizado (por exemplo, "Agente de Pesquisa") e o endereço de e-mail continua o mesmo.

Importante: se você usar um endereço de e-mail diferente em --from (que não o da conta autenticada), o Gmail exige que esse endereço esteja configurado como alias de envio em Configurações do Gmail → Contas → Enviar e-mail como.

A opção --from funciona tanto no send quanto no reply:

$GAPI gmail reply MESSAGE_ID \
  --from '"Bot de Suporte" <compartilhado@empresa.com>' --body "Estamos cuidando disso"

Responder

$GAPI gmail reply MESSAGE_ID --body "Obrigado, por mim está ótimo."

Encadeia a resposta automaticamente (define os cabeçalhos In-Reply-To e References) e usa o ID da thread da mensagem original.

Marcadores

# Lista todos os marcadores
$GAPI gmail labels

# Adiciona/remove marcadores
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD

Agenda

# Lista eventos (por padrão, os próximos 7 dias)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z

# Cria evento (fuso horário obrigatório)
$GAPI calendar create --summary "Daily do time" \
  --start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00

# Com local e convidados
$GAPI calendar create --summary "Almoço" \
  --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z \
  --location "Café" --attendees "alice@co.com,bob@co.com"

# Apaga evento
$GAPI calendar delete EVENT_ID

aviso

Os horários da agenda precisam incluir o deslocamento de fuso (por exemplo, -07:00) ou usar UTC (Z). Datas cruas como 2026-03-01T10:00:00 são ambíguas e serão tratadas como UTC.

Drive

$GAPI drive search "relatório trimestral" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5

Planilhas

# Lê um intervalo
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"

# Escreve num intervalo
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Nome","Nota"],["Alice","95"]]'

# Acrescenta linhas
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["novos","dados","da linha"]]'

Documentos

$GAPI docs get DOC_ID

Devolve o título do documento e o texto completo.

Contatos

$GAPI contacts list --max 20

Formato da saída

Todos os comandos devolvem JSON. Campos principais por serviço:

Comando	Campos
gmail search	id, threadId, from, to, subject, date, snippet, labels
gmail get	id, threadId, from, to, subject, date, labels, body
gmail send/reply	status, id, threadId
calendar list	id, summary, start, end, location, description, htmlLink
calendar create	status, id, summary, htmlLink
drive search	id, name, mimeType, modifiedTime, webViewLink
contacts list	name, emails, phones
sheets get	matriz 2D com os valores das células

Resolução de problemas

Problema	Solução
NOT_AUTHENTICATED	Faça a configuração (peça ao Hermes para configurar o Google Workspace)
REFRESH_FAILED	Token revogado — refaça os passos de autorização
HttpError 403: Insufficient Permission	Escopo faltando — revogue e autorize de novo com os serviços certos
HttpError 403: Access Not Configured	API não habilitada no Google Cloud Console
ModuleNotFoundError	Rode o script de configuração com --install-deps