Real Estate AI Agent

A robust, multi-tool AI assistant for real estate operations built using LangGraph, the Model Context Protocol (MCP) via langchain-mcp-adapters, and OpenRouter.

---

Architecture Overview

The agent orchestrates multiple tools across decoupled local MCP servers, external APIs, and local Python tools:

1. Property Data MCP Server (property_data_mcp_server.py):

   • Manages local SQLite property listings (property_data.db).
   • Tools:
     • search_properties(min_price, max_price, beds, baths): Flexible property queries with optional filters.
     • get_property_details(address): Case-insensitive and partial address matching.

2. CRM MCP Server (crm_mcp_server.py):

   • Manages clients and timestamped interaction notes (crm_db.db).
   • Enforces unique email constraints and foreign keys with cascade deletion.
   • Tools:
     • create_client_lead(name, email): Adds a client with duplicate detection.
     • add_note_to_client(email, note): Attaches notes to existing clients.
     • get_client_notes(email): Fetches timestamped notes for a client.

3. Web Search:

   • Uses Tavily if TAVILY_API_KEY is provided in .env.
   • Automatically and gracefully falls back to DuckDuckGo (DuckDuckGoSearchRun) if no API key is configured.

4. Custom Tools:

   • estimate_property_price_tool(bedrooms, bathrooms): Computes baseline price approximations.
   • end_conversation_tool(farewell_message): Allows the agent to conclude the session when the user indicates they are finished.

5. LangGraph State & Memory:

   • Built on LangGraph StateGraph with a cyclical ReAct tool loop.
   • Preserves multi-turn conversational memory via MemorySaver checkpointer.

---

Setup & Installation

1. Environment & Dependencies

Create and activate a virtual environment, then install dependencies:

python -m venv env
# On Windows PowerShell:
.\env\Scripts\Activate.ps1
# On macOS/Linux:
source env/bin/activate

pip install -r requirements.txt

2. Configure API Keys

Copy .env.example to .env:

cp .env.example .env

Edit .env and set your credentials:

# OpenRouter API Key (https://openrouter.ai/settings/keys)
OPENROUTER_API_KEY=your_openrouter_api_key_here

# OpenRouter Model (Default: google/gemma-4-26b-a4b-it)
OPENROUTER_MODEL=google/gemma-4-26b-a4b-it

# Optional Tavily API Key (Falls back to DuckDuckGo if omitted)
TAVILY_API_KEY=your_tavily_api_key_here

---

Usage

1. Interactive Mode (Recommended)

Run the agent without arguments to launch the multi-turn conversational REPL:

python real_estate_agent.py

• Context is preserved across conversational turns.
• To exit, type DONE, bye, exit, quit, or simply tell the agent you are finished!

2. Single-Shot Command Line Mode

Pass your query directly as arguments:

python real_estate_agent.py "Find me homes under 600000 with at least 3 bedrooms"

Sample Queries

• Property Search: "Find me homes between 300000 and 600000 with 3+ bedrooms."
• Property Details: "Give me details for 123 Oak St"
• CRM Client Management: "Create a new client named Alice Jay with email alice.j@example.com"
• Client Notes: "Add a note to alice.j@example.com saying she prefers houses with 3+ bedrooms" "Show me the notes we have for alice.j@example.com in our CRM"
• Property Valuation: "Estimate the price of a 4 bedroom 3 bathroom property"
• Web Search: "Search the web for current real estate mortgage rates and trends"
• Complex Multi-Step Inquiries: "Check if we have any notes on alice.j@example.com, then find available houses based on her preference, and estimate the price for a 4 bed 3 bath house."