Leads Generation Agent

An intelligent automation tool designed to discover, extract, and compile business leads from online directories and map services using natural language prompts.

The current project uses a Streamlit UI frontend in backend/app/ui/streamlit_app.py and an agent architecture built around backend/app/agent/runner.py, tool_registry.py, and browser scraping services.

Agent Architecture & ReAct Loop

The agent uses a ReAct-style loop to alternate between reasoning and tool execution. It asks the LLM to return only structured JSON actions, either calling a tool or returning a final answer. The loop continues until the task is complete.

Implemented in:

• backend/app/agent/runner.py — core agent loop and tool orchestration
• backend/app/agent/prompt.py — system prompt and agent instruction templates
• backend/app/agent/tool_registry.py — tool registration, tool schemas, and handler lookup
• backend/app/agent/llm.py — wrapper for the LLM interface
• backend/app/agent/real_llm.py — actual langchain_groq LLM implementation

Tool implementations currently include:

• backend/app/services/parser.py — prompt parsing
• backend/app/services/browser.py — Google Maps scraping logic
• backend/app/services/exporter.py — Excel export logic
• backend/app/services/email_scraper.py — email scraping helper

How It Works

The Leads Generation Agent automates the entire process of discovering and compiling business leads from a simple natural-language prompt.

1. Prompt Processing & Intent Extraction

• The user enters a conversational request like "coffee shops in America".
• The prompt parser extracts the business category and location.

2. Browser Automation & Lead Scraping

• The agent uses browser automation to search Google Maps.
• It scrapes listings and extracts business details:
  • Business Name
  • Website
  • Phone Number
  • Address
  • Email
• If a value is missing, the agent continues without failing.

3. Data Export

• Collected leads are saved to an Excel file.
• The output path is configured using OUTPUT_DIR.
• The UI displays progress and provides a download link once complete.

Installation

Prerequisites

• Python 3.8+
• pip

Step 1: Enter the backend directory

cd /home/user/Desktop/python/aiseason/session_4/LeadsGenerationAgent/backend

Step 2: Install dependencies

pip install -r requirements.txt

Step 3: Configure environment variables

Create a .env file in backend/ with values for the Groq API and output settings.

Example .env:

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=groq-1-512k
HEADLESS=True
OUTPUT_DIR=./output
DEBUG=False
HOST=127.0.0.1
PORT=8501

Important variables:

Variable	Description	Example
GROQ_API_KEY	Your Groq API key for the LLM	sk-...
GROQ_MODEL	Groq model name	groq-1-512k
HEADLESS	Run browser in headless mode (True/False)	True
OUTPUT_DIR	Directory to save Excel files	./output

Running the Agent

From the backend/ folder, start the Streamlit app:

python -m app.main

This launches the Streamlit interface in your browser.

Providing a Search Prompt

Enter a natural language query in the UI, such as:

• pizza restaurants in Los Angeles
• software development companies in London
• dentists near San Francisco
• hotels in Tokyo

The agent will parse the prompt, scrape leads, and export the results to Excel.

Locating Generated Excel Files

Output Directory

Excel files are saved to the directory specified by OUTPUT_DIR, typically:

backend/output/

File Naming Convention

Files are named using the business category:

leads_[business_type].xlsx

Examples:

• leads_coffee_shops.xlsx
• leads_pizza_restaurants.xlsx
• leads_software_companies.xlsx

Access Generated Files

ls -la output/

Project Structure

backend/
├── app/
│   ├── agent/
│   │   ├── llm.py
│   │   ├── memory.py
│   │   ├── prompt.py
│   │   ├── real_llm.py
│   │   ├── runner.py
│   │   └── tool_registry.py
│   ├── services/
│   │   ├── browser.py
│   │   ├── email_scraper.py
│   │   ├── exporter.py
│   │   ├── parser.py
│   │   ├── scraper.py
│   │   └── selectors.py
│   ├── ui/
│   │   ├── components.py
│   │   └── streamlit_app.py
│   ├── config.py
│   ├── main.py
│   └── models.py
├── output/
├── requirements.txt
└── .env

Troubleshooting

Missing API Key

Make sure GROQ_API_KEY is set in backend/.env:

cat .env

No Excel Files Generated

Ensure OUTPUT_DIR is configured and writable:

mkdir -p output/

Browser Automation Issues

Install Playwright and the browser runtime:

pip install playwright
playwright install chromium

Dependencies

Key dependencies in requirements.txt:

• langchain
• langchain-groq
• langchain-core
• streamlit
• playwright
• openpyxl
• python-dotenv

License

This project is provided as-is for educational purposes.