FinanceAgent (WhatsApp + Google ADK)

Agente financeiro para WhatsApp com Google ADK (Python) e Google Sheets.

Visao geral

• Recebe mensagens tipo "gastei 50 reais com um bolo" e registra na planilha.
• Consulta historico ("quanto gastei em janeiro?").
• Recebe nota fiscal (imagem) e extrai texto com Gemini multimodal.

Requisitos

• Python 3.10+
• Conta Google Cloud com Service Account habilitada para Google Sheets
• API key do Gemini

Configuracao rapida

1. Copie .env.example para .env e preencha:
   • GOOGLE_API_KEY
   • GOOGLE_SHEETS_ID
   • GOOGLE_SHEETS_CREDENTIALS_FILE (ou GOOGLE_SHEETS_CREDENTIALS_JSON)
   • ADK_REQUEST_STYLE (use camel ou snake dependendo do seu ADK)
2. Crie uma planilha no Google Sheets e compartilhe com o email da Service Account.

Instalar dependencias

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Rodar o ADK API Server

.\scripts\run_api_server.ps1

Rodar o webhook

.\scripts\run_webhook.ps1

Payload placeholder (ate integrar provedor do WhatsApp)

POST http://localhost:8080/webhook/whatsapp

{
  "user_id": "5511999999999",
  "text": "gastei 50 reais com um bolo",
  "image_url": null,
  "image_base64": null,
  "mime_type": null,
  "timestamp": "2026-01-28T11:25:00-03:00"
}

Header:

x-webhook-token: <WEBHOOK_TOKEN>

Observacoes

• O provedor do WhatsApp esta como placeholder. Basta trocar o parser em webhook/providers/.
• O ADK usa o agente definido em finance_agent/agent.py.
• O webhook envia o texto extraido da nota fiscal para o agente (via ADK).

O que falta

• Integrar um provedor real de WhatsApp (ex: Meta Cloud API, Twilio, Z-API) e implementar o envio da resposta.
• Criar a planilha no Google Sheets e compartilhar com a Service Account.
• Ajustar o modelo do ADK se a API tiver formato diferente de request/response.
• Deploy/infra (ngrok ou dominio com HTTPS) para expor o webhook.