Multi-Agent Research & Writing System - Project Documentation
📋 Project Overview
This is an advanced Multi-Agent AI System that combines web research and content creation. It uses two specialized AI agents working together: a Researcher Agent that gathers information from the web, and a Writer Agent that synthesizes that information into polished, engaging content. Built with LangGraph, Groq API, and Firecrawl.

🎯 Key Features

1. Two-Agent Collaboration

Researcher Agent - Searches and scrapes web content using Firecrawl tools
Writer Agent - Creates polished, engaging content from research findings
Agents work sequentially in an optimized workflow

2. Web Data Extraction

Firecrawl integration for web scraping and searching
Supports multiple data formats (markdown, HTML, etc.)
Can crawl entire websites or specific pages
Search functionality for finding relevant information

3. Advanced LLM Integration

Uses Groq's Llama 3.3-70b model (fast, powerful)
Researcher uses temperature=0 (focused, factual)
Writer uses temperature=0.7 (creative, engaging)
Automatic tool schema conversion for compatibility

4. Agentic Workflow

Built with LangGraph for state management
React Agent pattern for intelligent decision-making
Conditional routing between agents
Structured state management with type safety

5. Real-Time Interaction

Command-line interface for interactive queries
Live progress indicators showing which agent is working
Comprehensive error handling and logging

🚀 How to Operate
Prerequisites
Before running this project, you need:

API Keys (get these first!)

Groq API Key - Sign up at console.groq.com
Firecrawl API Key - Sign up at firecrawl.dev

Node.js - Required for Firecrawl MCP

Download from nodejs.org
Verify installation: node --version

Installation & Setup

1.Install Python Dependencies
pip install groq langchain-groq langgraph langchain-core langchain-mcp-adapters python-dotenv pydantic
2.Install Firecrawl MCP (Node.js required)
npm install -g firecrawl-mcp
3.Create Environment File (.env)
GROQ_API_KEY=your_groq_api_key_here
FIRECRAWL_API_KEY=your_firecrawl_api_key_here
4.Run the Application
python app.py
Using the Multi-Agent System

Start the Application

Application initializes both agents
Shows available tools and agent status
Ready for your queries

Enter Your Query

Type what you want researched and written about
Example: "Write a detailed article about the latest AI developments in 2025"
Press Enter to submit

Watch the Workflow

🔍 RESEARCHER AGENT starts working

Searches relevant web content
Scrapes web pages for information
Extracts key facts and data

✍️ WRITER AGENT begins synthesizing

Takes researcher's findings
Writes engaging, well-structured content
Produces final polished output

Get Your Result

Final comprehensive response appears in terminal
Type next query or type "quit" to exit

Agent Workflow:
User Input
↓
[RESEARCHER AGENT] ← Uses Firecrawl tools
↓
Gathers research data
↓
[WRITER AGENT] ← No tools, pure generation
↓
Creates polished content
↓
Final Output to UserUser Input
↓
[RESEARCHER AGENT] ← Uses Firecrawl tools
↓
Gathers research data
↓
[WRITER AGENT] ← No tools, pure generation
↓
Creates polished content
↓
Final Output to User

Firecrawl Tools Available

Search - Find information across the web

Input: Search query, limit (number of results)
Output: Search results with URLs and content

Scrape - Extract content from specific URLs

Input: URL, desired formats (markdown/HTML)
Output: Cleaned, formatted page content

Crawl - Explore entire websites

Input: Starting URL, max pages to crawl
Output: All pages' content from that domain

📊 Data Flow
State Management (MultiAgentState):
{
"messages": [...], # Conversation history
"research_complete": False, # Flag when research done
"research_data": "...", # Researcher's findings
"next_agent": "researcher" # Router: who goes next
}
Message Flow

User sends query as HumanMessage
Researcher processes with system prompt
Researcher's response stored in research_data
Writer receives research data + system prompt
Writer generates final content
All messages accumulated and returned

💡 Model Configuration
Researcher Model:
temperature=0 # Deterministic, factual responses
model="llama-3.3-70b-versatile"

Focus: Accuracy, gathering facts, no hallucination

Writer Model:
temperature=0.7 # Creative, varied responses
model="llama-3.3-70b-versatile"

Focus: Engagement, storytelling, polishtemperature=0.7 # Creative, varied responses

model="llama-3.3-70b-versatile"

Focus: Engagement, storytelling, polish

🛠️ Key Functions Explained
fix_tool_for_groq(tool)
Converts MCP tool schemas to Groq-compatible Pydantic models. Handles:

Firecrawl Search → FirecrawlSearchInput
Firecrawl Scrape → FirecrawlScrapeInput
Firecrawl Crawl → FirecrawlCrawlInput

researcher_node(state)

Receives user query
Uses Firecrawl tools to search/scrape web
Gathers factual information
Returns structured research data

writer_node(state)

Receives researcher's findings
Synthesizes into engaging narrative
Produces polished, final output
Returns complete response

route_agent(state)

Determines next agent in workflow
Returns: "writer", "researcher", or "end"
Controls conditional routing

📁 Project Structure:
project_directory/
├── app.py # Main application file
├── .env # API keys (KEEP SECURE)
├── requirements.txt # Python dependencies
└── .gitignore # Exclude .env from git

.env File (Example)
GROQ_API_KEY=gsk_xxxxxxxxxxxxx
FIRECRAWL_API_KEY=fc_xxxxxxxxxxxxx

🐛 Troubleshooting
Missing API Keys

Ensure .env file exists in project root
Check key formats match exactly
Keys should not have quotes around them

❌ WRONG: GROQ_API_KEY="gsk_xxxx"
✅ RIGHT: GROQ_API_KEY=gsk_xxxx
Firecrawl MCP Not Found
bashnpm install -g firecrawl-mcp

Ensure Node.js is installed and updated
Try: which firecrawl-mcp to verify installation

Tool Schema Errors

System automatically fixes incompatible schemas
If errors persist, check Firecrawl API key validity
Verify Firecrawl service is online

Slow or Timeout Responses

Firecrawl may take time scraping large websites
Default limits: 5 search results, 10 page crawls
Adjust limits in FirecrawlSearchInput, FirecrawlCrawlInput

Groq API Rate Limits

Free tier has limited requests per minute
Add delays between queries if hitting limits
Consider upgrading Groq plan for more requests

🔐 Security Best Practices

Never commit .env file to Git

Add to .gitignore: .env

Keep API Keys Private

Don't share or expose keys
Rotate keys periodically

Rate Limiting

Implement delays for production use
Monitor API usage

Error Handling

Avoid printing sensitive data in errors
Log safely to files

📈 Workflow Visualization:
START
↓
┌─────────────────────┐
│ RESEARCHER AGENT │ Uses tools to gather info
│ • Search web │
│ • Scrape pages │
│ • Crawl websites │
└─────────────────────┘
↓
✓ Research data collected
↓
┌─────────────────────┐
│ WRITER AGENT │ Creates content
│ • Synthesize data │
│ • Write engaging │
│ • Polish output │
└─────────────────────┘
↓
✓ Final content ready
↓
END (Return to user)