Python para automação de email: ler, filtrar e responder com IA

A caixa de entrada do Gmail pode ser um autêntico sorvedouro de produtividade, consumindo metade do teu dia de trabalho em leitura, organização e respostas que poderiam ser geridas de forma automática. Felizmente, combinando o poder do Python com a inteligência artificial do Hermes Agent, podemos criar um sistema autónomo que lê a tua caixa de entrada, categoriza os emails importantes e rascunha respostas inteligentes de forma imediata.

Neste tutorial prático, vais aprender a criar um fluxo de trabalho completo para automatizar a tua gestão de correio eletrónico. Vamos configurar o acesso ao Gmail, utilizar o Python para extrair as mensagens não lidas e invocar o Hermes Agent para analisar e responder a cada mensagem de forma ultra-personalizada.

O que é o Hermes Agent?

O Hermes Agent é um assistente de inteligência artificial open-source extremamente poderoso, desenhado para correr tanto na cloud como localmente na tua máquina (preservando totalmente a privacidade dos teus dados). Através do conceito de skills (competências personalizadas), podemos ensinar o Hermes a executar tarefas complexas — como analisar o tom de um email e redigir uma resposta profissional — com apenas alguns comandos simples.

Passo 1: Instalar o Hermes Agent e as Dependências

Antes de começarmos a programar em Python, precisamos de garantir que temos o Hermes Agent instalado no nosso sistema operacional. Abre o teu terminal e executa o comando oficial de instalação:

# Instalação para macOS e Linux
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Se estiveres a utilizar o Windows, deves abrir a PowerShell como Administrador e executar o seguinte comando:

# Instalação para Windows
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Depois de concluída a instalação, precisamos de instalar as bibliotecas de Python necessárias para comunicar com a API do Gmail e gerir a autenticação de forma segura. Executa o comando abaixo no teu terminal:

pip install google-auth-oauthlib google-api-python-client

Passo 2: Configurar o Acesso à API do Gmail

Para que o Python consiga aceder à tua caixa de entrada, precisas de criar um projeto na Google Cloud Console, ativar a "Gmail API" e descarregar o ficheiro de credenciais OAuth 2.0. Guarda esse ficheiro na pasta do teu projeto com o nome credentials.json.

Na primeira execução do script, abrir-se-á uma janela no teu navegador web para autorizares o acesso à tua conta de email. Isto gerará um ficheiro local chamado token.json que garantirá que o teu script corre de forma automática no futuro, sem intervenção humana.

Passo 3: Criar a Skill do Hermes Agent

Em vez de escrevermos prompts gigantescos diretamente no código Python, vamos tirar partido do ecossistema do Hermes Agent criando uma Skill dedicada. No Hermes, as skills são definidas através de ficheiros Markdown estruturados, guardados no diretório ~/.hermes/skills/.

Cria um ficheiro chamado SKILL.md dentro da diretoria de skills do Hermes ou na pasta do teu projeto com a seguinte estrutura canónica:

---
name: email_responder
description: Analisa um email recebido, categoriza-o e gera uma sugestão de resposta profissional.
author: MarcTechJA
version: "1.0"
platforms:
  - macos
  - linux
  - windows
metadata:
  hermes:
    tags: [email, automacao, produtividade]
---

# Email Responder
Analisa o conteúdo de um email, determina o seu nível de prioridade, categoriza-o (Suporte, Comercial, Parcerias, Spam) e gera uma resposta adequada baseada no tom especificado.

## When to Use
Usa esta skill sempre que receberes um novo email na tua caixa de entrada que precise de ser analisado e respondido de forma rápida e profissional.

## Instruções
1. Lê atentamente o conteúdo do email fornecido pelo utilizador.
2. Determina a categoria do email (ex: Suporte, Comercial, Dúvida Geral).
3. Avalia o nível de urgência (Alta, Média, Baixa).
4. Escreve uma proposta de resposta profissional, amigável e adaptada ao contexto, em português de Portugal (pt-PT).
5. Apresenta o resultado estruturado em formato JSON com os campos: "categoria", "urgencia" e "resposta_sugerida".

## Critérios de conclusão
- O output deve conter a análise clara e o rascunho da resposta estruturado em formato JSON limpo, sem texto adicional antes ou depois.

Esta estrutura indica ao Hermes exatamente como processar a informação que o Python lhe vai enviar. Podes verificar se a skill foi reconhecida pelo agente executando o comando:

hermes skills list

Passo 4: Desenvolver o Script Python de Integração

Agora que temos a skill criada e a API do Gmail pronta, vamos escrever o script Python que une estas duas pontas. Este script vai ligar-se ao Gmail, procurar o email não lido mais recente, extrair o remetente e o corpo do texto, e enviá-lo para o Hermes Agent utilizando o comando de execução de skills.

Cria um ficheiro chamado auto_email.py com o seguinte código completo:

import os
import subprocess
import json
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
from googleapiclient.discovery import build

# Definir os acessos de leitura e escrita do Gmail
SCOPES = ['https://www.googleapis.com/auth/gmail.modify']

def obter_servico_gmail():
    creds = None
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return build('gmail', 'v1', credentials=creds)

def obter_ultimo_email_nao_lido(servico):
    resultados = servico.users().messages().list(userId='me', q='is:unread', maxResults=1).execute()
    mensagens = resultados.get('messages', [])
    
    if not mensagens:
        print("Nenhum email não lido encontrado.")
        return None
        
    msg_id = mensagens[0]['id']
    mensagem = servico.users().messages().get(userId='me', id=msg_id, format='full').execute()
    
    headers = mensagem['payload']['headers']
    assunto = next(h['value'] for h in headers if h['name'] == 'Subject')
    remetente = next(h['value'] for h in headers if h['name'] == 'From')
    corpo = mensagem.get('snippet', '')
    
    return {"id": msg_id, "remetente": remetente, "assunto": assunto, "corpo": corpo}

def processar_com_hermes(conteudo_email):
    prompt_entrada = f"Remetente: {conteudo_email['remetente']}\nAssunto: {conteudo_email['assunto']}\nCorpo: {conteudo_email['corpo']}"
    
    # Executa o Hermes Agent chamando a skill que criámos
    resultado = subprocess.run(
        ["hermes", "chat", "-s", "email_responder", prompt_entrada],
        capture_output=True,
        text=True,
        encoding="utf-8"
    )
    
    return resultado.stdout

if __name__ == "__main__":
    print("A ligar ao Gmail...")
    servico = obter_servico_gmail()
    
    email_dados = obter_ultimo_email_nao_lido(servico)
    if email_dados:
        print(f"\nNovo email de: {email_dados['remetente']}")
        print(f"Assunto: {email_dados['assunto']}")
        
        print("\nA enviar dados para o Hermes Agent analisar...")
        analise_ia = processar_com_hermes(email_dados)
        
        print("\n=== Resposta e Análise Sugerida pelo Hermes ===")
        print(analise_ia)

O que faz este código? O script autentica o utilizador no Gmail, recolhe o cabeçalho e o resumo do email não lido mais recente e envia essa string formatada para o Hermes Agent através de um subprocesso do sistema operacional. O Hermes executa a skill email_responder e devolve o output estruturado diretamente no ecrã do teu terminal.

Passo 5: Executar a Automação

Para colocar o teu novo assistente de email em funcionamento, garante que tens um email não lido na tua caixa de entrada e executa o script no terminal:

python auto_email.py

Em poucos segundos, verás o Hermes Agent a analisar a mensagem, a categorizar o seu nível de urgência e a escrever um rascunho de resposta perfeito e polido, pronto a ser enviado de volta ao remetente.

Conclusão: O Teu Novo Assistente de Email Inteligente

Parabéns! Acabas de dar os primeiros passos no mundo dos agentes autónomos de IA. Ao combinar o Python com a flexibilidade das skills do Hermes Agent, conseguiste criar um fluxo que lê e analisa dados do mundo real em tempo recorde, libertando tempo precioso do teu dia a dia para tarefas de maior valor acrescentado.

Podes expandir este projeto adicionando regras para enviar as respostas de volta de forma 100% automática, integrar filtros de spam personalizados ou até mesmo criar equipas de agentes que colaboram entre si para resolver problemas técnicos descritos nos emails de suporte.