fin-agent

A LangGraph-powered financial analysis agent exposed as an MCP-compatible FastAPI server, containerized with Docker and deployable on Kubernetes.

Built as a home project to demonstrate end-to-end AI agent engineering: from LLM tool-calling and agent loops to production serving, containerization, and CI/CD.

Architecture

User Query
    │
    ▼
FastAPI /invoke  ←  MCP Server (Facade pattern)
    │
    ▼
LangGraph Graph  ←  ReAct loop (Reason → Act → Observe)
    │
    ├── LLM Node (claude-sonnet-4-6 via Anthropic API)
    └── Tool Node (Dispatcher pattern)
              ├── get_stock_price
              ├── get_company_summary
              └── get_recent_news

Design Patterns

Pattern	Where	Why
State Machine	agent/graph.py	Agent loop modeled as a graph over immutable state
ReAct	agent/graph.py → agent/nodes.py	Reason→Act→Observe loop (Yao et al. 2022)
Facade	mcp_server/app.py	Single /invoke endpoint hides all agent internals
Registry	tools/registry.py	Central tool lookup — adding a tool requires no changes elsewhere
Dispatcher	agent/nodes.py	Routes LLM tool_calls to the correct tool at runtime

Project Structure

fin-agent/
├── agent/
│   ├── graph.py        # LangGraph StateGraph (ReAct loop)
│   ├── nodes.py        # Pure node functions (LLM + tool executor)
│   └── state.py        # AgentState TypedDict
├── tools/
│   ├── registry.py     # Registry pattern — central tool lookup
│   ├── price.py        # get_stock_price tool
│   ├── summary.py      # get_company_summary tool
│   └── news.py         # get_recent_news tool
├── mcp_server/
│   └── app.py          # FastAPI server (Facade pattern)
├── tests/
│   ├── test_tools.py   # Unit tests (tools in isolation)
│   └── test_server.py  # Integration tests (mocked graph)
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── k8s/
│   ├── deployment.yaml
│   └── secret.yaml
└── .github/workflows/ci.yml

Tech Stack

• Agent framework: LangGraph + LangChain
• LLM: Claude Sonnet 4.6 (Anthropic API)
• Server: FastAPI + Uvicorn
• Financial data: yfinance (Yahoo Finance, no API key needed)
• Containerization: Docker + Docker Compose
• Orchestration: Kubernetes
• CI/CD: GitHub Actions

Quickstart

# 1. Clone and install
git clone https://github.com/BasselSharaf/finance-agent.git
cd finance-agent
pip install -r requirements.txt

# 2. Set your Anthropic API key
cp .env.example .env
# edit .env and add your key

# 3. Run the server
uvicorn mcp_server.app:app --reload

API

Health check

GET /health
→ {"status": "ok"}

Run the agent

POST /invoke
Content-Type: application/json

{"query": "What is the current price and recent news for NVDA?"}

Interactive docs available at http://localhost:8000/docs

Docker

docker compose -f docker/docker-compose.yml up --build

Kubernetes

# Add your real API key to k8s/secret.yaml first
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/deployment.yaml

Tests

pytest tests/ -v

• test_tools.py — unit tests for each tool in isolation (no LLM calls)
• test_server.py — integration tests for the FastAPI layer (graph mocked)

References

• LangGraph: https://langchain-ai.github.io/langgraph/
• ReAct paper (Yao et al. 2022): https://arxiv.org/abs/2210.03629
• MCP specification: https://modelcontextprotocol.io/
• Anthropic API: https://docs.anthropic.com