How simaraconceicao/ai-agent-finance works
Project Type and Purpose
• This is a serverless, micro-service based AI assistant for personal finance management.
• Two main codebases:
a. AI Agent (agente-financeiro/finance_agent/): built with Google ADK + Gemini for conversational interactions and intent parsing.
b. MCP Server (my-mcp/): a FastMCP service that exposes tool calls (list_expenses_by_user, create_expense) via HTTP to the Agent.
• The system orchestrates user queries, LLM processing, tool invocation, and interactions with an external Finance REST API (hosted on Render with MongoDB).
File Structure Analysis
• Top level
• .gitignore, README.md
• agente-financeiro/ → finance_agent/: contains agent.py, .env.example, ADK configuration.
• my-mcp/: contains my_server.py, Dockerfile, requirements.txt — this is the MCP Server service.
• Patterns
• Each component is a standalone service (microservice).
• Deployment configuration present (Dockerfile in my-mcp/; ADK CLI for finance_agent/).
• Environment files (.env example) and Cloud Run deployment instructions.
Key Architectural Insights from README
• The Agent uses prompt engineering + Gemini “gemini-2.0-flash” to interpret user intent.
• Tooling layer is implemented via the Model Context Protocol (FastMCP).
• Both services are deployed serverlessly on Google Cloud Run, requiring containerization (MCP) or ADK deployment (Agent).
• External dependency: a RESTful Finance API (separate service) backed by MongoDB.
a. AI Agent Service
• Tech: Python, Google ADK, Google Gemini (LLM via Vertex AI or builtin).
• Deployed on Cloud Run (with ADK CLI).
• Exposes a Dev UI (frontend to the user).
b. Gemini LLM
• A managed model; invoked by the Agent for natural language understanding/generation.
c. MCP Server
• Tech: Python, FastMCP, httpx.
• Exposes REST endpoints under /mcp/.
• Containerized via Dockerfile, deployed on Cloud Run.
d. External Finance Backend
• A third-party RESTful API (hosted on Render).
• Manages user finances and stores data in MongoDB.
Data Flow & Relationships
1. User → ADK Dev UI → Agent Service
2. Agent → Gemini LLM (prompt + user query) → Intent & action decision
3. Agent → MCP Server (/mcp/ endpoint) → Tool invocation
4. MCP Server → External Finance API (httpx calls) → Retrieves or writes finance data
5. External API → MongoDB (persistence)
6. MCP Server returns response → Agent → Formats NL response → User
Architectural Patterns & Principles
• Microservices: each service has a single responsibility (Agent vs. Toolset).
• Serverless: Cloud Run hosting, auto-scaling, containerized deployment.
• LLM Tooling Pattern: LLM-driven agent with a well-defined tool interface (MCP).
• Environment-driven configuration: .env, Cloud Run env vars, fixed URLs in code.