Skip to main content
Prerequisites: Completed the Deploy Your First Agent tutorial

​
What You’ll Build

In this tutorial, you’ll create a lead scoring agent that:
  • Scores candidates based on job descriptions using AI
  • Ranks leads automatically with intelligent analysis
  • Generates personalized emails for top candidates
  • Provides a complete SaaS solution with frontend and backend
  • Uses CrewAI flows for multi-agent orchestration

​
The Lead Scoring Challenge

Recruiting and lead qualification is time-consuming:
  • Manual screening: Reviewing hundreds of resumes manually
  • Inconsistent scoring: Different recruiters score differently
  • Email personalization: Writing personalized emails takes hours
  • Scalability: Hard to scale manual processes
RunAgent solves this by automating the entire lead scoring workflow with AI agents that can analyze, score, and communicate with candidates.

​
Architecture Overview

The lead scoring agent uses a multi-layered architecture: 
┌─────────────────┐
│   React Frontend │
│   (Port 5173)   │
└────────┬────────┘
         │ HTTP REST API
         ↓
┌─────────────────┐
│  Flask Backend  │
│   (Port 8000)   │
└────────┬────────┘
         │ RunAgent Python SDK
         ↓
┌─────────────────┐
│  RunAgent Agent │
│  (CrewAI Flow)  │
└─────────────────┘

​
Step 1: Understanding the Agent Structure

The lead scoring agent uses CrewAI flows to orchestrate multiple AI agents: Key Components:
  • LeadDataCollectionCrew: Collects and validates lead data
  • LeadAnalysisCrew: Analyzes candidate profiles
  • LeadScoringCrew: Scores candidates based on job requirements
  • EmailGenerationCrew: Creates personalized emails
Entrypoints:
  • lead_score_flow: Main flow that orchestrates the entire process
  • score_candidate: Score a single candidate

​
Step 2: Agent Configuration

The agent is configured using runagent.config.json: 
{
  "agent_name": "lead-scoring",
  "description": "AI-powered lead scoring with email generation",
  "framework": "crewai",
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "main.py",
        "module": "lead_score_flow",
        "tag": "lead_score_flow"
      },
      {
        "file": "main.py",
        "module": "score_candidate",
        "tag": "score_candidate"
      }
    ]
  }
}

​
Step 3: Core Agent Logic (Gist)

The agent processes candidates through multiple stages: 
# Simplified flow structure
def lead_score_flow(
    candidates: List[Dict],
    job_description: str,
    top_n: int = 3,
    generate_emails: bool = True,
    additional_instructions: str = ""
) -> Dict[str, Any]:
    """
    Main flow that:
    1. Collects and validates candidate data
    2. Analyzes each candidate's profile
    3. Scores candidates based on job requirements
    4. Ranks candidates and selects top N
    5. Generates personalized emails
    """
    # Data collection
    validated_candidates = collect_lead_data(candidates)
    
    # Analysis and scoring
    scored_candidates = score_leads(
        validated_candidates,
        job_description,
        additional_instructions
    )
    
    # Ranking
    top_candidates = rank_candidates(scored_candidates, top_n)
    
    # Email generation
    if generate_emails:
        emails = generate_emails(top_candidates, job_description)
        return {
            "scored_candidates": scored_candidates,
            "top_candidates": top_candidates,
            "emails": emails
        }
    
    return {
        "scored_candidates": scored_candidates,
        "top_candidates": top_candidates
    }

​
Step 4: Backend Integration

The Flask backend provides REST API endpoints: 
# Backend API structure
@app.route('/api/score-leads', methods=['POST'])
def score_leads():
    """
    Endpoint that:
    - Receives candidates and job description
    - Calls RunAgent agent
    - Returns scored results
    """
    client = RunAgentClient(
        agent_id=agent_id,
        entrypoint_tag="lead_score_flow",
        local=False
    )
    
    result = client.run(
        candidates=candidates,
        job_description=job_description,
        top_n=top_n,
        generate_emails=generate_emails
    )
    
    return jsonify(result)

​
Step 5: Frontend Integration

The React frontend provides a user-friendly interface: Key Features:
  • CSV upload for candidate data
  • Job description input
  • Real-time scoring results
  • Email preview and download
  • Top candidates visualization

​
Step 6: Deployment

​
Local Deployment

# 1. Deploy the RunAgent agent
cd examples/lead-agent/lead-score-flow
runagent serve .

# 2. Start the backend
cd ../backend
python app.py

# 3. Start the frontend
cd ../frontend
npm run dev

​
Production Deployment

The agent can be deployed to RunAgent Cloud: 
runagent deploy .

​
What You’ve Accomplished

You’ve built a complete lead scoring SaaS solution:

🤖 AI-Powered Scoring

Automated candidate scoring using multi-agent AI workflows

📊 Intelligent Ranking

Automatic ranking of candidates based on job fit

✉️ Email Generation

Personalized email generation for top candidates

🌐 Full-Stack Solution

Complete SaaS application with frontend and backend

​
Key Features

​
Multi-Agent Orchestration

  • Uses CrewAI flows to coordinate multiple specialized agents
  • Each agent handles a specific aspect of the scoring process
  • Parallel processing for efficient candidate evaluation

​
Intelligent Scoring

  • Analyzes candidate profiles against job requirements
  • Considers skills, experience, and cultural fit
  • Provides detailed scoring breakdowns

​
Email Personalization

  • Generates context-aware emails for each candidate
  • Incorporates specific candidate details
  • Maintains professional tone and structure

​
Example Usage

from runagent import RunAgentClient

client = RunAgentClient(
    agent_id="your_agent_id",
    entrypoint_tag="lead_score_flow",
    local=False
)

result = client.run(
    candidates=[
        {
            "id": 1,
            "name": "John Doe",
            "email": "[email protected]",
            "bio": "Experienced React developer",
            "skills": "React, Node.js, TypeScript"
        }
    ],
    job_description="Looking for a senior React developer...",
    top_n=3,
    generate_emails=True
)

​
Next Steps

Customize Scoring

Customize scoring criteria and weights

Add Features

Add features like candidate tracking and analytics

Production Deployment

Deploy to production with proper scaling

View Full Example

Explore the complete example code

​
Repository

View the complete example code and documentation: Repository: https://github.com/runagent-dev/runagent/tree/main/examples/lead-agent The repository includes:
  • Complete agent implementation with CrewAI flows
  • Flask backend API
  • React frontend application
  • Deployment guides and documentation
  • Example CSV files and test data
🎉 Great job! You’ve learned how to build a production-ready lead scoring system using RunAgent and CrewAI. This demonstrates the power of multi-agent orchestration for complex business workflows!