How to Build a Lead Qualifier Agent with Claude API (Step-by-Step)

mkdir lead-qualifier-agent
cd lead-qualifier-agent
pip install anthropic python-dotenv

ANTHROPIC_API_KEY=sk-ant-your-key-goes-here

import os
import json
import anthropic
from dotenv import load_dotenv

load_dotenv()

# Initialize the Anthropic client using your API key from .env
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

MODEL = "claude-sonnet-4-6"

# Tool definitions tell Claude what functions are available and how to call them
TOOLS = [
    {
        "name": "validate_contact",
        "description": "Validates that a lead has a real email address and phone number. Returns whether each field is valid and a combined contact_valid boolean.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email": {
                    "type": "string",
                    "description": "The lead's email address"
                },
                "phone": {
                    "type": "string",
                    "description": "The lead's phone number, any format"
                }
            },
            "required": ["email", "phone"]
        }
    },
    {
        "name": "check_budget",
        "description": "Checks whether a lead's stated budget meets the minimum threshold for our services. Returns fit level: high, medium, low, or disqualified.",
        "input_schema": {
            "type": "object",
            "properties": {
                "budget": {
                    "type": "number",
                    "description": "The lead's stated monthly or project budget in USD"
                }
            },
            "required": ["budget"]
        }
    },
    {
        "name": "assess_timeline",
        "description": "Evaluates how soon the lead wants to start. Returns urgency level: immediate, near_term, or low_priority.",
        "input_schema": {
            "type": "object",
            "properties": {
                "timeline": {
                    "type": "string",
                    "description": "The lead's stated timeline, e.g. 'within 30 days', 'Q1 next year', 'just exploring'"
                }
            },
            "required": ["timeline"]
        }
    }
]

import re

def validate_contact(email: str, phone: str) -> dict:
    # Basic email format check using regex
    email_valid = bool(re.match(r"[^@]+@[^@]+\.[^@]+", email))
    # Strip non-digits and check length (US numbers = 10 digits)
    digits = re.sub(r"\D", "", phone)
    phone_valid = len(digits) >= 10
    return {
        "email_valid": email_valid,
        "phone_valid": phone_valid,
        "contact_valid": email_valid and phone_valid
    }

def check_budget(budget: float) -> dict:
    if budget >= 5000:
        fit = "high"
    elif budget >= 1500:
        fit = "medium"
    elif budget >= 500:
        fit = "low"
    else:
        fit = "disqualified"
    return {"budget": budget, "fit": fit}

def assess_timeline(timeline: str) -> dict:
    timeline_lower = timeline.lower()
    if any(word in timeline_lower for word in ["immediate", "asap", "now", "this week", "30 days", "next month"]):
        urgency = "immediate"
    elif any(word in timeline_lower for word in ["quarter", "q1", "q2", "q3", "q4", "3 months", "6 months"]):
        urgency = "near_term"
    else:
        urgency = "low_priority"
    return {"timeline": timeline, "urgency": urgency}

# Router that maps tool names to their Python functions
def run_tool(tool_name: str, tool_input: dict) -> dict:
    if tool_name == "validate_contact":
        return validate_contact(**tool_input)
    elif tool_name == "check_budget":
        return check_budget(**tool_input)
    elif tool_name == "assess_timeline":
        return assess_timeline(**tool_input)
    else:
        return {"error": f"Unknown tool: {tool_name}"}

def run_agent(lead_data: dict) -> str:
    """
    Runs the lead qualification agent loop.
    Keeps cycling until Claude returns a final text response with no tool calls.
    """
    # Build the initial user message with lead details
    user_message = f"""
Please qualify the following lead for our AI services agency.
Use the available tools to validate their contact info, check their budget fit,
and assess their timeline urgency. Then give me a final qualification summary.

Lead data:
- Name: {lead_data.get('name')}
- Email: {lead_data.get('email')}
- Phone: {lead_data.get('phone')}
- Budget (USD): {lead_data.get('budget')}
- Timeline: {lead_data.get('timeline')}
- Company: {lead_data.get('company', 'Not provided')}
- Notes: {lead_data.get('notes', 'None')}
"""

    messages = [{"role": "user", "content": user_message}]

    # Agentic loop — keeps running until Claude stops requesting tools
    while True:
        response = client.messages.create(
            model=MODEL,
            max_tokens=1024,
            tools=TOOLS,
            messages=messages
        )

        # Append Claude's response to the message history
        messages.append({"role": "assistant", "content": response.content})

        # If Claude is done using tools, extract and return the final text
        if response.stop_reason == "end_turn":
            for block in response.content:
                if hasattr(block, "text"):
                    return block.text

        # Otherwise, process every tool call Claude made in this turn
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = run_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                })

        # Feed all tool results back to Claude in a single user message
        if tool_results:
            messages.append({"role": "user", "content": tool_results})

def qualify_lead(lead: dict) -> dict:
    """
    Public interface: takes a lead dict, returns a qualification result dict.
    """
    print(f"\n{'='*50}")
    print(f"Qualifying lead: {lead.get('name')} from {lead.get('company', 'Unknown')}")
    print(f"{'='*50}\n")

    summary = run_agent(lead)

    return {
        "lead_name": lead.get("name"),
        "company": lead.get("company"),
        "qualification_summary": summary
    }


if __name__ == "__main__":
    # Example lead — replace with real data from your form or CRM
    sample_lead = {
        "name": "Maria Gonzalez",
        "email": "[email protected]",
        "phone": "(239) 555-0192",
        "budget": 4500,
        "timeline": "We want to go live within the next 30 days",
        "company": "Suncoast Realty Group",
        "notes": "Interested in AI listing automation and chatbot for their website"
    }

    result = qualify_lead(sample_lead)

    print("\n--- QUALIFICATION RESULT ---")
    print(f"Lead: {result['lead_name']} | {result['company']}")
    print(f"\n{result['qualification_summary']}")

==================================================
Qualifying lead: Maria Gonzalez from Suncoast Realty Group
==================================================

--- QUALIFICATION RESULT ---
Lead: Maria Gonzalez | Suncoast Realty Group

**Lead Qualification Summary — Maria Gonzalez, Suncoast Realty Group**

✅ Contact Validation: PASSED
   - Email ([email protected]): Valid format
   - Phone ((239) 555-0192): Valid — 10-digit US number confirmed

💰 Budget Assessment: MEDIUM FIT
   - Stated budget: $4,500
   - Falls in the medium tier ($1,500–$4,999). Strong enough to proceed.
   - Recommend discussing a phased engagement starting with the chatbot.

⏱️ Timeline: IMMEDIATE
   - Wants to go live within 30 days — high urgency, hot lead.
   - Prioritize scheduling a discovery call this week.

📋 Overall Recommendation: QUALIFY — PRIORITY OUTREACH
   Maria represents a warm, time-sensitive opportunity in real estate AI automation.
   Contact info is clean, budget is workable, and urgency is high. Recommend
   scheduling a 30-minute discovery call within 24 hours.

anthropic.AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}

# The agent never stops — it keeps calling the API in a loop
# No error is thrown, but the script never exits

AttributeError: 'TextBlock' object has no attribute 'input'