Erstellen Sie einen Agenten zur Qualifizierung von AI-Lead-Kandidaten in Python mit FastAPI und Pydantic

Die meisten Unternehmen leiden nicht unter einem Mangel an potenziellen Kunden. Ihr Problem ist vielmehr die Qualifizierung dieser Kunden. Hunderte von Anfragen können über Webformulare, E-Mail-Kampagnen und Marketing-Tools eintreffen, und jemand muss jede einzelne öffnen, die Nachricht lesen, herausfinden, was der Kunde will, das Budget überprüfen und entscheiden, ob sie Aufmerksamkeit verdient. Mit steigendem Volumen wird diese manuelle Sortierung immer teurer.

Die praktische Frage ist, ob ein KI-Agent eingehende Anfragen entgegennehmen, die Absicht des Kunden erkennen, diese anhand von Geschäftsregeln prüfen und die geeigneten Anfragen an den Vertrieb weiterleiten kann. Das ist möglich – doch nicht, indem man jede Anfrage einfach in ein großes Sprachmodell eingibt und auf die Antwort vertraut. Ein zuverlässiges System benötigt strukturierte Ausgaben, klare Regeln, Validierung, Speicherung sowie einen ordnungsgemäßen Arbeitsablauf. Die folgenden Abschnitte zeigen, wie so ein System in Python erstellt werden kann.

Was das System tut

Der Ablauf ist kurz: Es kommt ein potenzieller Kunde, das System interpretiert die Anfrage, bewertet sie, speichert das Ergebnis und löst den nächsten Schritt aus.

Nehmen wir diese Nachricht von einem potenziellen Kunden:

„Unser Vertriebsteam benötigt ein maßgeschneidertes CRM mit etwa 30 Nutzern, das innerhalb von zwei Monaten geliefert werden soll. Wie hoch wären die ungefähren Kosten?“

Ein Mensch würde sofort mehrere Fakten erkennen:

• es gibt einen klaren Geschäftsbedarf
• es handelt sich um Software nach Maß
• das Team hat etwa 30 Nutzer
• es gibt eine Lieferfrist
• die Kosten sind die entscheidende Frage

Ein Agent sollte dieselben Fakten herausfiltern und dem Vertrieb dabei helfen, zu entscheiden, was als Nächstes zu tun ist. Er darf nicht davon ausgehen, dass jede detaillierte Nachricht ein guter potenzieller Kunde ist. Er muss die Informationen anhand der tatsächlichen Qualifikationskriterien des Unternehmens bewerten.

Die Architektur

Der geplante Arbeitsablauf ist unten dargestellt:

┌──────────────────┐
                  │   Incoming Lead  │
                  │ Website / Email  │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │  Lead Ingestion   │
                  │ Validate & Store  │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │   AI Extraction   │
                  │ Intent, Need,     │
                  │ Budget, Timeline  │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │ Business Rules    │
                  │ Qualification     │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │  Lead Scoring     │
                  │ Qualified /       │
                  │ Review / Reject   │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │ PostgreSQL        │
                  │ Store Result      │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │ Automation        │
                  │ CRM / Email /     │
                  │ Sales Notification│
                  └──────────────────┘

Eine Designentscheidung ist wichtiger als alle anderen: Halten Sie das Verständnis der KI von den Geschäftsentscheidungen getrennt. Das LLM extrahiert Informationen aus dem Lead, während Ihr eigener Code entscheidet, wie diese Informationen die Qualifizierung beeinflussen. Durch diese Trennung ist das System einfacher zu testen, zu debuggen und zu ändern.

Schritt 1: Entscheiden, was einen Lead qualifiziert

Geschäftsregeln kommen vor dem Code. Nehmen wir ein Beispiel einer Softwareentwicklungsfirma. Sie könnte einen Lead dann als qualifiziert betrachten, wenn:

1. der Kunde ein echtes Softwareanliegen hat
2. das Anliegen zu den Dienstleistungen der Firma passt
3. die Nachricht genügend Details enthält, um das Projekt zu verstehen
4. das Budget oder die Kaufabsicht die Anforderungen der Firma erfüllt
5. die Nachricht kein Spam oder eine offensichtlich irrelevante Anfrage ist

Diese Regeln dienen nur zur Veranschaulichung, und ein echtes Unternehmen sollte seine eigenen Schwellenwerte festlegen. Ein ausgefülltes Formular könnte wie folgt aussehen: Der Service ist die maßgeschneiderte CRM-Entwicklung, das Budget beträgt 500.000 ₹, die Frist sind zwei Monate, die Unternehmensgröße 30 Nutzer, die Intensität ist hoch und die Entscheidung ist qualifiziert.

Die KI sollte die Daten extrahieren. Die Geschäftsregeln sollten die endgültige Entscheidung treffen.

Schritt 2: Das Python-Projekt erstellen

Python eignet sich für diese Aufgabe dank seines Ökosystems für APIs, Integrationen mit großen Sprachmodellen, Datenverarbeitung und Automatisierung. Die Projektstruktur sieht wie folgt aus:

ai-lead-agent/
│
├── app/
│   ├── main.py
│   ├── config.py
│   │
│   ├── agents/
│   │   └── lead_agent.py
│   │
│   ├── schemas/
│   │   └── lead.py
│   │
│   ├── services/
│   │   ├── lead_service.py
│   │   └── scoring_service.py
│   │
│   └── db/
│       └── database.py
│
├── tests/
│   └── test_scoring.py
│
├── requirements.txt
└── .env

Installieren Sie die erforderlichen Pakete:

pip install openai pydantic fastapi uvicorn python-dotenv

Die Komponenten sind:

• FastAPI für die Backend-API
• Pydantic für die strukturierte Validierung
• die OpenAI-API für das LLM-Beispiel
• PostgreSQL als Produktionsdatenbank
• reines Python für die Lead-Bewertung

Der LLM-Anbieter kann später durch einen anderen ersetzt werden.

Schritt 3: Definieren Sie ein strukturiertes Lead-Schema

Ein häufiger Fehler in KI-Anwendungen besteht darin, freien Text als Endausgabe zu verwenden. Eine solche Antwort ist schwer zuverlässig zu verarbeiten:

This looks like a good lead.
The customer wants a CRM and seems interested.

Das Ziel ist vorhersehbares JSON. Erstellen Sie app/schemas/lead.py und beginnen Sie mit den Imports:

from typing import Optional, Literal
from pydantic import BaseModel, Field

Dann definieren Sie die Modelle, beginnend mit dem eingehenden Lead und fortfahrend mit der Analyse, die das Modell zurückgeben muss:

class LeadInput(BaseModel):
    name: str
    email: str
    company: Optional[str] = None
    message: str
class LeadAnalysis(BaseModel):
    summary: str    service_type: Optional[str] = None    intent: Literal[
        "high",
        "medium",
        "low",
        "unknown"
    ]    budget: Optional[float] = None    currency: Optional[str] = None    timeline: Optional[str] = None    is_spam: bool = False    missing_information: list[str] = Field(
        default_factory=list
    )    qualification_notes: str    recommended_action: Literal[
        "contact_sales",
        "request_more_information",
        "reject",
        "manual_review"
    ]

Nun hat die KI-Antwort eine definierte Struktur. Wenn das Modell einen ungültigen Wert zurückgibt, kann die Anwendung diesen ablehnen oder verarbeiten, anstatt falsche Daten stillschweigend zu speichern.

Schritt 4: Die Lead-Analysefunktion erstellen

Danach kommt app/agents/lead_agent.py. Das Modell sollte interpretieren, was der Lead sagt, und darf nichts Erfindenes hinzufügen, was nicht vorhanden ist. Beginnen Sie mit den Imports:

import json
import os

Danach kommt die Analysefunktion selbst. Sie sendet den Eingabedatenstrom an das Modell, fordert eine Ausgabe gemäß dem Schema an und überprüft, was zurückkommt:

from openai import OpenAIfrom app.schemas.lead import (
    LeadInput,
    LeadAnalysis
)
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
)
SYSTEM_PROMPT = """
You are a lead analysis assistant for a software
development agency.Your task is to analyze incoming customer leads.Extract:
- Customer requirement
- Service type
- Buying intent
- Budget if explicitly mentioned
- Timeline if explicitly mentioned
- Spam indicators
- Missing informationRules:
1. Never invent a budget.
2. Never invent a timeline.
3. If information is missing, return null.
4. Return valid structured JSON.
5. Do not make a final business decision based
   only on assumptions.
"""
def analyze_lead(lead: LeadInput) -> LeadAnalysis:    user_prompt = f"""
    Analyze this incoming lead:    Name: {lead.name}
    Email: {lead.email}
    Company: {lead.company}
    Message: {lead.message}
    """    response = client.chat.completions.create(
        model="gpt-4o-mini",
        temperature=0,
        response_format={
            "type": "json_object"
        },
        messages=[
            {
                "role": "system",
                "content": SYSTEM_PROMPT
            },
            {
                "role": "user",
                "content": user_prompt
            }
        ]
    )    result = json.loads(
        response.choices[0].message.content
    )    return LeadAnalysis.model_validate(result)

Warum die Temperatur null ist

Zur Extraktion benötigt man Konsistenz, nicht kreative Formulierungen. Eine niedrige Temperatur verringert die Schwankungen zwischen den Antworten, garantiert aber nicht die Richtigkeit. Deshalb sind Schema-Validierung und Geschäftsregeln weiterhin notwendig.

Auch die Namen der Modelle sowie die Funktionen der API ändern sich im Laufe der Zeit. Wenn Sie dies für die Produktion umsetzen, wählen Sie ein Modell sowie eine Methode zur strukturierten Ausgabe, die Ihr Anbieter derzeit unterstützt.

Schritt 5: Fügen Sie die Qualifizierungsregeln hinzu

Dieser Teil sollte nicht vollständig dem LLM überlassen werden. Nehmen wir an, die Beispielkriterien der Agentur lauten:

• das Projekt ist relevante Softwareentwicklung
• wenn ein Budget angegeben wird, beträgt es mindestens ₹2.000.000
• die Nachricht ist kein Spam
• es liegen ausreichende Informationen vor, um die Anforderung zu verstehen

Erstellen Sie app/services/scoring_service.py, beginnend mit dem Import:

from app.schemas.lead import LeadAnalysis

Dann sammelt die Bewertungsfunktion, die bei null beginnt, die Gründe für jede Anpassung und gibt für Spam sofort null zurück:

def score_lead(analysis: LeadAnalysis) -> dict:    score = 0
    reasons = []    if analysis.is_spam:
        return {
            "score": 0,
            "status": "rejected",
            "reasons": ["Spam detected"]
        }    if analysis.service_type:
        score += 25
        reasons.append(
            "Service requirement identified"
        )    if analysis.intent == "high":
        score += 30
        reasons.append(
            "High buying intent"
        )    elif analysis.intent == "medium":
        score += 15
        reasons.append(
            "Medium buying intent"
        )    if analysis.budget is not None:
        if analysis.budget >= 200000:
            score += 25
            reasons.append(
                "Budget meets example threshold"
            )
        else:
            reasons.append(
                "Budget below example threshold"
            )    if analysis.timeline:
        score += 10
        reasons.append(
            "Timeline provided"
        )    if analysis.missing_information:
        score -= 10
        reasons.append(
            "Some information is missing"
        )    score = max(0, min(score, 100))    if score >= 70:
        status = "qualified"    elif score >= 40:
        status = "review"    else:
        status = "unqualified"    return {
        "score": score,
        "status": status,
        "reasons": reasons
    }

Das ist ein einfaches, veranschaulichendes Bewertungsschema. Eine echte Agentur könnte weitere Faktoren berücksichtigen:

• Projektgröße
• Branche
• Standort
• Ob der Service verfügbar ist
• Wie dringend der Kunde ist
• Frühere Interaktionen
• Vertrauen in das angegebene Budget
• Doppelte Anfragen

Testen Sie die Bewertungsfunktion anhand echter Beispiele, bevor Sie sie dazu nutzen, Anfragen automatisch abzulehnen.

Schritt 6: Verbinden Sie den Agenten mit FastAPI

Erstellen Sie app/main.py und importieren Sie FastAPI:

from fastapi import FastAPI

Der Rest der Datei verbindet das Schema, die Analysefunktion und den Scoring-Service hinter einer Endpunkt zusammen:

from app.schemas.lead import LeadInput
from app.agents.lead_agent import analyze_lead
from app.services.scoring_service import score_lead
app = FastAPI(
    title="AI Lead Filtering Agent"
)
@app.get("/health")
def health_check():
    return {
        "status": "ok"
    }
@app.post("/analyze-lead")
def analyze_incoming_lead(
    lead: LeadInput
):    analysis = analyze_lead(lead)    score = score_lead(analysis)    return {
        "lead": lead,
        "analysis": analysis,
        "qualification": score
    }

Starten Sie den Server:

uvicorn app.main:app --reload

Dann öffnen Sie die interaktiven API-Dokumentationen:

http://127.0.0.1:8000/docs

Von dort aus können Sie einen Lead einreichen und die strukturierte Antwort überprüfen.

Schritt 7: Probieren Sie einen realistischen Lead aus

Senden Sie eine Musteranfrage wie diese:

{
  "name": "Rahul Sharma",
  "email": "rahul@example.com",
  "company": "Example Technologies",
  "message": "We need a custom CRM for around 30 users. Our budget is approximately 500000 INR and we want to launch within 2 months."
}

Ein plausibles Extraktionsergebnis sieht wie folgt aus:

{
  "summary": "Customer needs a custom CRM.",
  "service_type": "CRM development",
  "intent": "high",
  "budget": 500000,
  "currency": "INR",
  "timeline": "2 months",
  "is_spam": false,
  "missing_information": [],
  "qualification_notes": "Clear requirement, budget, and timeline.",
  "recommended_action": "contact_sales"
}

Dienst für die Bewertung bewertet anschließend die extrahierten Daten und gibt Ergebnisse wie folgt aus:

{
  "score": 90,
  "status": "qualified",
  "reasons": [
    "Service requirement identified",
    "High buying intent",
    "Budget meets example threshold",
    "Timeline provided"
  ]
}

Denken Sie daran, dass diese Ausgabe nur eine Veranschaulichung dessen ist, was zu erwarten ist, und keine Messung aus einem tatsächlichen API-Aufruf darstellt.

Schritt 8: Potenzielle Kunden in PostgreSQL speichern

Für den echten Geschäftseinsatz reicht es nicht aus, die Ergebnisse nur im Speicher zu halten, daher ist eine dauerhafte Speicherung erforderlich. Eine einfache Tabelle sieht so aus:

CREATE TABLE leads (
    id BIGSERIAL PRIMARY KEY,

Die verbleibenden Spalten enthalten die Details des Leads sowie die Analyse:

    name VARCHAR(150) NOT NULL,    email VARCHAR(255) NOT NULL,    company VARCHAR(255),    message TEXT NOT NULL,    service_type VARCHAR(255),    intent VARCHAR(20),    budget NUMERIC(14, 2),    currency VARCHAR(10),    timeline VARCHAR(100),    is_spam BOOLEAN DEFAULT FALSE,    ai_score INTEGER,    qualification_status VARCHAR(30),    analysis JSONB,    created_at TIMESTAMPTZ DEFAULT NOW()
);

Die analysis-Spalte bewahrt die ursprüngliche, strukturierte KI-Ausgabe bei, was hilft, wenn man herausfinden muss, warum ein Lead eine bestimmte Klassifizierung erhalten hat.

Für die Produktion sollten Sie außerdem Folgendes berücksichtigen:

• einen eindeutigen Identifikator pro Lead
• eine Methode zur Erkennung von Duplikaten
• Indizes für Status und Erstellungszeit
• Verschlüsselung sowie strenge Zugriffskontrollen, da Lead-Daten sensibel sind
• Schema-Migrationen
• einen Audit-Trail

Schritt 9: Automatisierung hinzufügen

Ab diesem Punkt ist der Agent mehr als nur eine einfache API. Stellen Sie sich diesen Ablauf vor:

New Lead
   │
   ▼
Save in PostgreSQL
   │
   ▼
Analyze with AI
   │
   ▼
Calculate Qualification
   │
   ├── Qualified ────────► Notify Sales
   │
   ├── Review ───────────► Human Review Queue
   │
   └── Unqualified ─────► Store for Reporting

Wenn ein qualifizierter potenzieller Kunde eintrifft, kann das System Folgendes tun:

1. den potenziellen Kunden in der Datenbank speichern
2. das Vertriebsteam benachrichtigen
3. ein CRM-Eintrag erstellen
4. einen Vertriebsmitarbeiter zuweisen
5. einen Nachfolgetermin planen
6. den Status des potenziellen Kunden aktualisieren

Die Automatisierungsstufe kann n8n, ein Hintergrundprozess oder ein auf Warteschlangen basierendes System sein. In der Produktion ist es unklug, den gesamten Prozess von einer einzigen synchronen HTTP-Anfrage abhängig zu machen. Ein robusteres Design verwendet eine Warteschlange als Vermittler:

Lead API
   │
   ▼
Message Queue
   │
   ▼
Background Worker
   │
   ▼
AI Analysis
   │
   ▼
Database
   │
   ▼
Automation

Die Leads werden anschließend asynchron verarbeitet, und fehlgeschlagene Aufgaben können erneut versucht werden.

Schritt 10: Menschliche Überprüfung hinzufügen

Das könnte der wichtigste Schritt sein. KI kann einen Lead falsch interpretieren. Betrachten Sie diese Nachricht:

"Im Moment vergleichen wir CRM-Optionen und haben kein Budget festgelegt, obwohl wir eine Vorstellung vom Preis haben möchten."

Das Modell könnte die Absicht als mittel oder hoch einstufen, während das Unternehmen den Lead lieber an einen Menschen weiterleiten möchte, anstatt ihn automatisch als qualifiziert zu markieren. Deshalb gibt es drei Statusseiten:

• Qualifiziert: Der Lead entspricht den Regeln und wird an das Vertriebsteam weitergeleitet.
• Überprüfung: Der Lead enthält nützliche Informationen, doch eine menschliche Entscheidung ist erforderlich.
• Nicht qualifiziert: Der Lead erfüllt die festgelegten Kriterien nicht.

Menschliche Überprüfung ist am nützlichsten, wenn:

• kein Budget angegeben wurde
• Der Bedarf ist unklar.
• Das Modell scheint unsicher bezüglich seiner eigenen Ausgabe zu sein.
• Die Details in der Nachricht widersprechen sich gegenseitig.
• Der Absender arbeitet in einer Branche, die das Unternehmen nicht bedient.

Ein gutes KI-System versteckt Unsicherheiten nicht. Es macht Unsicherheiten sichtbar.

Was macht das zu einem Agenten?

Ein einfacher Aufruf eines LLM umfasst lediglich Eingabe, Modell und Ausgabe:

Input → LLM → Output

Ein Agent-Workflow leistet mehr. Er versteht die eingehende Aufgabe, extrahiert die relevanten Informationen, wendet Tools oder Geschäftsregeln an, wählt den nächsten Schritt aus, speichert den Zustand, triggert eine Aktion und versucht es erneut oder eskaliert, wenn etwas schiefgeht. Für den Lead-Filter sieht der vollständige Pfad wie folgt aus:

Incoming Lead
      │
      ▼
AI Analysis
      │
      ▼
Business Rules
      │
      ▼
Qualification Decision
      │
      ▼
Action / Human Review

Die KI ist nur ein Bestandteil. Die Backend-Anwendung sorgt dafür, dass der gesamte Prozess zuverlässig abläuft – und dieser Unterschied ist wichtig.

Verbesserungen vor der Produktion

Eine erste Version reicht aus, um den Arbeitsablauf zu überprüfen, sollte aber nicht in diesem Zustand veröffentlicht werden.

Hintergrundverarbeitung. Führen Sie die Lead-Analyse über eine Task-Queue wie Celery mit Redis, RQ, einer cloud-basierten Queue oder einem datenbankgestützten Job-System durch. Das erleichtert Wiederholungsversuche bei hohem Volumen.

Erkennung von Duplikaten. Ein Lead kann zweimal eintreffen – einmal über die Website und einmal über eine E-Mail-Kampagne. Vergleichen Sie E-Mail-Adresse, Unternehmen sowie weitere Identifikatoren.

Versionierung der Anfragen. Speichern Sie die Version der Anfrage neben jedem KI-Ergebnis. Wenn sich die Qualifikationskriterien ändern, können Sie so feststellen, welche Anfrage und Regeln zu einem früheren Ergebnis geführt haben.

Überwachbarkeit. Überwachen Sie die Latenz der KI, API-Fehler, den Tokenverbrauch, die Kosten pro potenziellem Kunden, die Verteilung der Qualifizierungsergebnisse sowie, wie oft Menschen den Agenten überschreiben.

Ein Bewertungsdatensatz. Sammeln Sie echte potenzielle Kunden mit von Menschen überprüften Labels und testen Sie das System anhand davon. Das sagt weitaus mehr aus als die Beurteilung des Agenten anhand eines einzigen guten Beispiels.

Sicherheit. Halten Sie API-Schlüssel vollständig außerhalb des Frontend-Code, überprüfen Sie jede eingehende Anfrage, schützen Sie personenbezogene Daten und beschränken Sie, wer potenzielle Kunden einsehen darf.

Die Lektion aus der Architektur

Der Aufbau eines KI-Agenten geht nicht nur darum, ein LLM aufzurufen. Die eigentliche Ingenieursarbeit liegt im Umgang mit dem Modell: ein klares Geschäftsproblem, strukturierte Daten, zuverlässige Validierung, deterministische Regeln, Persistenz, Automatisierung, menschliche Überprüfung und Überwachung. Wer diese Aspekte übersieht, erhält einen Chatbot, der intelligent klingt, das Geschäftsproblem jedoch nicht löst.

Ein Lead-Filter sollte nicht nur eine Antwort liefern. Er sollte einen nützlichen, nachvollziehbaren Workflow erstellen. Das Modell versteht unstrukturierte Kundennachrichten, Python steuert den Ablauf, Geschäftsregeln definieren die Qualifizierung, PostgreSQL speichert den Zustand und die Automatisierung verbindet das Ergebnis mit dem Vertriebsteam. Gemeinsam verwandeln sie eine KI-Demo in eine funktionierende Anwendung.

Eine logische Weiterentwicklung besteht darin, die API mit einer echten Lead-Quelle zu verbinden, Hintergrundaufgaben hinzuzufügen und ein Dashboard zu erstellen, über das das Vertriebsteam prüfen kann, welche Leads in Frage kommen. Das Ziel ist es nicht, jede Verkaufsentscheidung durch KI zu ersetzen, sondern repetitive Arbeiten zu reduzieren, damit sich die Mitarbeiter auf diejenigen Leads konzentrieren können, die es verdienen.