Build an AI Lead Qualification Agent with Claude and Python
Build an AI agent that reads a sales inquiry, pulls out the key details, scores the lead, drafts a reply and returns clean JSON a CRM can use. Seven beginner-friendly parts take you from your Claude API key to a tested Python and FastAPI service that handles errors and logs safely.
Start with Part 1Overview, Architecture and Your Claude API Key
Start a beginner-friendly series that builds an AI lead qualification agent with the Claude API, Python and FastAPI. See what it returns, how it works, what each lead really costs, and set up the tools you need.
Create a Production-Grade Python Project with uv and FastAPI
Set up the Lead Qualifier project the way production teams do. Create a uv project with a src layout and pinned dependencies, load the Claude API key safely with pydantic-settings, and run a FastAPI app with a health check and interactive docs.
Design the Lead Data Model with Pydantic
Design the exact JSON shape Claude must return for every sales inquiry, using Pydantic models, enums and field descriptions that become Claude's instructions. Learn the limits of structured outputs, and lock the contract in with pytest.
Qualify Your First Lead with Claude Structured Outputs
Write the system prompt, call Claude from FastAPI with the official Python SDK's messages.parse, cache the instructions, defend against prompt injection, and qualify your first real sales inquiry through the API.
Score and Prioritize Leads You Can Explain
Turn Claude's signals into a 0–100 lead score and a high, medium or low priority with plain Python rules, show the reason behind every point, unit-test the scorecard, and watch a prompt-injection attempt score zero.
Handle Errors and Log Safely
Make the Lead Qualifier production-ready. Map every Claude API failure to a clear HTTP status, set timeouts and retries, tag logs with request IDs, and record each lead's token usage and cost without logging any personal data.
Test the Lead Qualifier with pytest
Test the whole Lead Qualifier API with pytest and FastAPI's TestClient, using a fake analyzer instead of Claude. Cover every failure, prove no personal data reaches the logs, add a quality gate and a README, and release version 1.0.0.
