What is Ai Agent Finance

ai-agent-finance is a Personal Finance Manager powered by an AI Agent, utilizing Generative AI and Serverless technologies (ADK, MCP, Gemini, Cloud Run). It enables conversational interaction to list, record, analyze finances, and provide tips.

Use cases

Use cases include individuals seeking to manage their personal finances more effectively, families wanting to track household expenses, and anyone looking for financial advice through a conversational interface.

How to use

Users can interact with the AI Agent through a conversational interface, allowing them to manage their finances by listing expenses, recording transactions, analyzing financial data, and receiving personalized financial advice.

Key features

Key features include conversational finance management, integration with Google Gemini for natural language processing, serverless architecture using Google Cloud Run, and a backend API for managing financial data.

Where to use

ai-agent-finance can be used in personal finance management, budgeting, expense tracking, and financial analysis across various platforms that support AI interactions.

Gerenciador Financeiro Pessoal com Agente de IA

Um projeto que demonstra a construção de um Agente de Inteligência Artificial para Gestão Financeira Pessoal, utilizando IA Generativa e Serverless(ADK, MCP, Gemini, Cloud Run)
. Este sistema permite a interação conversacional para listar, registrar, analisar finanças e receber dicas.

Estrutura do Projeto

Este repositório principal, ai-agent-finance/, contém duas pastas-filhas que compõem a arquitetura do agente financeiro:

1. agente-financeiro -> finance_agent/: Contém o código do Agente de IA desenvolvido com o Google Agent Development Kit (ADK). Este agente usa Gemini pra processar as interações do usuário, interpretar intenções e orquestrar as chamadas para as ferramentas financeiras, além prover dicas.
2. mcp_server/: Contém o código do Model Context Protocol (MCP) Server implementado com FastMCP. Este servidor atua como uma ponte para expor funcionalidades da sua API de backend (list_expenses_by_user, create_expense) ao Agente de IA.

Tecnologias Utilizadas

• Google Agent Development Kit (ADK): Framework para o desenvolvimento de agentes de IA.
• FastMCP (Model Context Protocol): Biblioteca Python para construir MCP, facilitando a integração e criação de ferramentas, além do uso de transports inerentes ao protocolo.
• Google Gemini (API / Modelo gemini-2.0-flash): O modelo de linguagem grande (LLM) que impulsiona as capacidades generativas do agente.
• Google Cloud Run: Plataforma de computação serverless que hospeda o Agente de IA e o MCP Server.
• Python: Linguagem de programação principal para o desenvolvimento de ambos os componentes.
• httpx: Biblioteca HTTP assíncrona utilizada pelo FastMCP para interagir com a API de backend de finanças.
• API RESTful de Finanças (Backend): Um serviço externo (neste caso, hospedado no Render e com o Banco de Dados no MongoDB) que gerencia os dados de despesas e entradas.

Technical Workflow

O sistema opera através da seguinte sequência:

1. O Agente de IA (de finance_agent/) recebe a entrada do usuário, tipicamente via ADK Dev UI.
2. Utilizando Prompt Engineering em sua configuração, o modelo Google Gemini interpreta a intenção do usuário.
3. Se uma ação financeira é requerida (ex: listar ou criar uma despesa), o Agente de IA invoca a ferramenta apropriada exposta pelo MCP Server.
4. O MCP Server (de mcp_server/) processa esta requisição, realiza validações de entrada e faz a chamada correspondente à API RESTful de finanças.
5. A resposta da API é tratada pelo MCP Server e retransmitida ao Agente de IA(pelo transport neste caso do tipo streamable HTTPs).
6. O Agente de IA então formata esta informação em uma resposta de linguagem natural para o usuário ou, em caso de erro, comunica o problema com base em suas instruções de sistema.

Configuração e Deploy

Para colocar o projeto em funcionamento no Google Cloud Run, siga os passos abaixo.

Pré-requisitos

• Conta Google Cloud: Com faturamento ativado.
• Google Cloud SDK (gcloud CLI): Instalado e configurado.
• Docker: Instalado (necessário para construir a imagem do MCP Server).
• Sua API de Backend de Finanças: Deve estar deployada e acessível.

1. Autenticação e Configuração do Projeto Google Cloud

Primeiro, autentique o gcloud CLI e defina seu projeto padrão:

gcloud auth login
gcloud config set project your-gcp-project-id
gcloud config set run/region us-central1 # Ou sua região preferida, ex: southamerica-east1

Projeto MCP Server (mcp_server/)

1. Preparar o Dockerfile

Crie um arquivo chamado Dockerfile na pasta mcp_server/ com o seguinte conteúdo:

# Usa uma imagem base Python oficial leve
FROM python:3.10-slim-buster

# Define o diretório de trabalho no container
WORKDIR /app

# Copia o arquivo de requisitos e instala as dependências
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copia o código da sua aplicação
COPY . .

# Expõe a porta que o FastMCP usará (8080 por padrão, exigido pelo Cloud Run)
EXPOSE 8080

# Comando para iniciar o servidor FastMCP
# FORÇAR HOST '0.0.0.0' É CRUCIAL PARA O CLOUD RUN
# A variável de ambiente PORT será injetada automaticamente pelo Cloud Run 
# Isso será feito direto no run do server
CMD ["python", "my_server.py"]

Crie um arquivo requirements.txt na pasta mcp_server/ com as dependências:

fastmcp
httpx

2. Deploy do MCP Server

Na pasta mcp_server/, execute os seguintes comandos:

# Define o nome do serviço
export MCP_SERVICE_NAME="meu-mcp" # Nome do seu serviço Cloud Run
export GCP_PROJECT_ID="your-gcp-project-id" # Substitua pelo seu ID de projeto

# Deployar para o Cloud Run usando a flag --source
# O Cloud Run construirá a imagem Docker automaticamente a partir do Dockerfile na pasta atual.
# A opção --allow-unauthenticated é necessária para que o ADK consiga acessá-lo.
# A variável de ambiente PORT será injetada automaticamente pelo Cloud Run e usada pelo seu código.
gcloud run deploy ${MCP_SERVICE_NAME} \
  --source=. \
  --platform managed \
  --allow-unauthenticated \
  --port 8080 \
  --project=${GCP_PROJECT_ID} \
  --region=${GOOGLE_CLOUD_LOCATION}

Após o deploy, o Cloud Run fornecerá uma URL do serviço. Anote-a, pois ela será usada na configuração do seu agente ADK. A URL terá um formato similar a https://meu-mcp-XXXX.REGION.run.app. Você deverá obrigatoriamente incluir o path /mcp/ quando for integrar.

Projeto Agente de IA (finance_agent/)

1. Preparar Variáveis de Ambiente e Configuração do Agente

Na pasta (finance_agent/), configure os 3 principais arquivos.

# Navegue para a pasta raiz do projeto se ainda não estiver nela
cd /path/to/your/agente-financeiro

# Seu ID de projeto do Google Cloud
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# Região onde seus serviços serão deployados (deve ser a mesma do MCP Server)
export GOOGLE_CLOUD_LOCATION="us-central1" # Ou sua região preferida

# Informa ao ADK para usar a Gemini API via Vertex AI
export GOOGLE_GENAI_USE_VERTEXAI=False

# O caminho para o diretório do seu agente ADK
export AGENT_PATH="./finance_agent"

# Nome do serviço Cloud Run para o seu agente
export AGENT_SERVICE_NAME="finance-assistant-agent"

# O ID do usuário fixo para o agente
export FINANCE_AGENT_USER_ID="seu-id" # Substitua pelo seu ID de usuário

# Não precisar exportar a key do Gemini pois dentro do cloud run você usa Gemini builtin

Importante: No seu arquivo finance_agent/agent.py, o USER_ID deve ser carregado via ambiente. A URL do MCP Toolset está fixada no código conforme sua instrução.

# finance_agent/agent.py (trecho relevante)
import os
from dotenv import load_dotenv # Importar para uso local

# Carrega as variáveis do arquivo .env (apenas para desenvolvimento local)
# Comenta ou remove esta linha se não estiver usando .env localmente
load_dotenv()

# Carrega o USER_ID de uma variável de ambiente
USER_ID = os.environ.get("FINANCE_AGENT_USER_ID")

# ... (restante do código do agente)

    tools=[
        MCPToolset(
            connection_params=StreamableHTTPServerParams(
                url="https://seulinkdocloudrun/mcp/" # URL do MCP fixada
            ),
        )
    ],
# ...

2. Deploy do Agente ADK

Use o comando adk deploy cloud_run. O ADK CLI irá conteinerizar e deployar seu agente.

# Deploy com a UI de desenvolvimento (recomendado para testes)
# A variável de ambiente FINANCE_AGENT_USER_ID será injetada para a instância do agente no Cloud Run.
adk deploy cloud_run \
  --project=${GOOGLE_CLOUD_PROJECT} \
  --region=${GOOGLE_CLOUD_LOCATION} \
  --service_name=${AGENT_SERVICE_NAME} \
  --with_ui \
  --set-env-vars="FINANCE_AGENT_USER_ID=${FINANCE_AGENT_USER_ID}" \
  ${AGENT_PATH}

Após o deploy, o Cloud Run fornecerá uma URL para a interface de desenvolvimento do seu agente. Acesse essa URL no seu navegador para interagir com o agente.

Desenvolvimento Local

Para executar o agente localmente, você pode usar um arquivo .env para gerenciar as variáveis de ambiente sem a necessidade de exportá-las manualmente no terminal a cada sessão.

1. Instale python-dotenv:

   pip install python-dotenv
   

2. Crie um arquivo .env na pasta finance_agent/:

   # finance_agent/.env
   FINANCE_AGENT_USER_ID="seu-user"
   # Note: MCP_SERVER_URL não precisa estar aqui se estiver fixado no agent.py para uso local.
   # Adicione outras variáveis de ambiente necessárias para o desenvolvimento local,
   # API Key e VertexAI.
   

   Importante: Adicione .env ao seu .gitignore para evitar o commit de informações sensíveis.

3. No seu finance_agent/agent.py, certifique-se de que from dotenv import load_dotenv e load_dotenv() estejam no início do arquivo, como mostrado na seção “Preparar Variáveis de Ambiente e Configuração do Agente” acima.

4. Para executar localmente:

   cd finance_agent/
   adk web
   

   Acesse http://localhost:8000 no seu navegador.

Uso

Uma vez que o Agente de IA e o MCP Server estejam deployados e funcionando, você pode interagir com o agente através da ADK Dev UI.

Exemplos de Interação:

• “Hi”
• “Can you list my finances?”
• “I received an extra 500 dollars today.”
• “I spent 45 dollars on internet this month.”
• “What tips do you have for saving money?”

Documentações oficiais

Esse repo tem algumas dicas legais que ainda não estão documentadas, tanto no fastMCP(config de deploy no Cloud Run) quanto no ADK(uso de transport streamable):

• Model Context Protocol (MCP): https://modelcontextprotocol.io/introduction
• Google Cloud Run: https://cloud.google.com/run/docs
• Google Agent Development Kit (ADK): https://google.github.io/adk-docs/
• FastMCP: https://gofastmcp.com/getting-started/welcome