Financial Research Agent

An autonomous stock research agent built with LangGraph, LangChain, and the ReAct pattern. It researches any ticker — fundamentals, news sentiment, technical indicators, and analyst consensus — then produces a structured buy/sell investment brief.

Includes a Streamlit web UI, MCP server for tool exposure, and session tracking for the full ReAct loop.

Based on Building a Financial Research Agent with ReAct, LangGraph, and LangChain.

Features

• ReAct Agent Loop — Agent decides tool order dynamically (Reason → Act → Observe)
• 4 Research Tools — Fundamentals, news sentiment, technicals, analyst ratings
• Streamlit UI — Live ReAct step tracking + investment brief display
• Session Tracking — Persisted JSON logs of every research session
• MCP Server — Expose tools to Cursor, Claude Desktop, or any MCP client
• Ticker Normalization — Handles mixed case input (reliance.ns → RELIANCE.NS)

Project Structure

financial-research-agent/
├── app/
│   └── streamlit_app.py      # Streamlit web interface
├── financial_mcp/
│   ├── server.py             # MCP server (stdio transport)
│   └── config.json           # Sample MCP client config
├── src/financial_agent/
│   ├── state.py              # LangGraph agent state
│   ├── tools.py              # Research tools (yfinance, Tavily, pandas-ta)
│   ├── agent.py              # LLM + system prompt
│   ├── graph.py              # LangGraph ReAct graph
│   ├── runner.py             # Streaming runner with tracking
│   ├── utils.py              # Ticker normalization
│   └── tracking/
│       └── session_tracker.py  # ReAct step & session persistence
├── data/sessions/            # Tracked research sessions (JSON)
├── main.py                   # CLI entry point
├── requirements.txt
├── .env.example
└── README.md

Setup

1. Clone and install

cd financial-research-agent
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

2. Configure API keys

Copy .env.example to .env and add your keys:

OPENAI_API_KEY=your_openai_key
TAVILY_API_KEY=your_tavily_key
OPENAI_MODEL=gpt-4o

Get a free Tavily key at tavily.com.

3. Run

Streamlit UI (recommended):

streamlit run app/streamlit_app.py

CLI:

python main.py RELIANCE.NS
python main.py AAPL

MCP Server:

python -m financial_mcp.server

Add to your MCP client config (see financial_mcp/config.json):

{
  "mcpServers": {
    "financial-research-agent": {
      "command": "python",
      "args": ["-m", "financial_mcp.server"],
      "cwd": "/path/to/financial-research-agent",
      "env": { "PYTHONPATH": "/path/to/financial-research-agent/src" }
    }
  }
}

Architecture

User: "Research RELIANCE.NS"
        │
        ▼
  ┌─────────────┐     tool_call      ┌─────────────┐
  │  Agent Node │ ─────────────────► │  Tools Node │
  │   (LLM)     │ ◄───────────────── │  (ToolNode) │
  └─────────────┘    observation     └─────────────┘
        │
        ▼ (no more tool calls)
  Final Investment Brief

Session Tracking

Every research run is tracked step-by-step:

Step Type	Description
tool_call	Agent decides to call a tool
tool_result	Tool observation returned
final_brief	Structured investment brief

Sessions are saved to data/sessions/{session_id}_{ticker}.json.

Supported Tickers

Market	Format	Example
US	SYMBOL	AAPL, MSFT
NSE	SYMBOL.NS	RELIANCE.NS
BSE	SYMBOL.BO	RELIANCE.BO

License

MIT