Crea un agente de calificación de líderes en IA en Python con FastAPI y Pydantic

La mayoría de las empresas no sufren de escasez de potenciales clientes. Su problema radica en calificarlos. Pueden llegar cientos de consultas a través de formularios web, campañas por correo electrónico y herramientas de marketing, y alguien todavía tiene que abrir cada una, leer el mensaje, averiguar qué quiere el cliente, verificar su presupuesto y decidir si merece atención. A medida que aumenta el volumen, ese proceso manual de selección se vuelve costoso.

La pregunta práctica es si un agente de IA puede tomar los potenciales clientes que llegan, comprender su intención, probarlos contra las reglas empresariales y dirigir a los adecuados al departamento de ventas. Es posible, pero no pegando cada consulta en un modelo de lenguaje grande y confiando en la respuesta. Un sistema fiable necesita una salida estructurada, reglas explícitas, validación, almacenamiento y un flujo de trabajo sólido. Las secciones siguientes crean uno así en Python.

Qué hace el sistema

El flujo es sencillo: llega un lead, el sistema lo interpreta, lo evalúa, guarda el resultado y activa el siguiente paso.

Tomemos este mensaje de un cliente potencial:

“Nuestro equipo de ventas necesita un CRM a medida, con unos 30 usuarios, que deba entregarse en dos meses. ¿Cuánto costaría aproximadamente?”

Una persona identificaría varios datos de inmediato:

• existe una necesidad empresarial clara
• el proyecto consiste en software a medida
• el equipo tiene aproximadamente 30 usuarios
• existe un plazo de entrega
• el costo es el punto clave

Un agente debe extraer los mismos datos y ayudar al equipo de ventas a decidir qué hacer a continuación. No debe asumir que cada mensaje detallado sea un buen lead; debe evaluar la información según los criterios reales de calificación de la empresa.

La arquitectura

El flujo de trabajo planificado se muestra a continuación:

┌──────────────────┐
                  │   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│
                  └──────────────────┘

Hay una elección de diseño que es más importante que las demás: mantener la comprensión de la IA separada de las decisiones comerciales. El LLM extrae información del lead, mientras que su propio código decide cómo esa información afecta la calificación. Con esta separación, el sistema es más fácil de probar, depurar y modificar.

Paso 1: Decidir qué califica como lead

Las reglas comerciales vienen antes que el código. Tomemos como ejemplo una agencia de desarrollo de software. Podría considerar que un lead califica cuando:

1. el cliente tiene un requisito real de software
2. el requisito coincide con los servicios que ofrece la agencia
3. el mensaje contiene suficientes detalles para comprender el proyecto
4. el presupuesto o la intención de compra cumple con los requisitos de la agencia
5. el mensaje no es spam ni una consulta obviamente irrelevante

Estas reglas son ilustrativas, y una empresa real debería establecer sus propios umbrales. Un registro completado podría indicar: el servicio es el desarrollo personalizado de CRM, el presupuesto es de ₹5,00,000, el plazo es de dos meses, el tamaño de la empresa es de 30 usuarios, la intención es alta y la decisión está calificada.

La IA debe extraer los datos. Las reglas empresariales deben tomar la decisión final.

Paso 2: Crear el proyecto en Python

Python es adecuado para esta tarea gracias a su ecosistema de APIs, integraciones con LLM, procesamiento de datos y automatización. La estructura del proyecto se ve así:

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

Instale los paquetes necesarios:

pip install openai pydantic fastapi uvicorn python-dotenv

Los componentes son:

• FastAPI para la API de backend
• Pydantic para la validación estructurada
• la API de OpenAI para el ejemplo de LLM
• PostgreSQL como base de datos en producción
• Python puro para la puntuación de leads

Más adelante se puede cambiar el proveedor de LLM por otro.

Paso 3: Definir un esquema estructurado para los leads

Un error común en las aplicaciones de IA es aceptar texto libre como salida final. Una respuesta de este tipo es difícil de procesar de manera fiable:

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

El objetivo es un JSON predecible. Crea app/schemas/lead.py y comienza con las importaciones:

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

Luego se definen los modelos, comenzando con el lead entrante y continuando con el análisis que el modelo debe devolver:

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"
    ]

Ahora la respuesta de la IA tiene una forma definida. Si el modelo devuelve un valor inválido, la aplicación puede rechazarlo o manejarlo, en lugar de almacenar en silencio datos incorrectos.

Paso 4: Construir la función de análisis de leads

A continuación está app/agents/lead_agent.py. El modelo debe interpretar lo que dice el lead y no debe inventar nada que no esté presente. Comience con las importaciones:

import json
import os

A continuación viene la función de análisis. Envía la entrada al modelo, solicita una salida que se ajuste al esquema y valida lo que recibe:

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)

Por qué la temperatura es cero

Para la extracción se necesita consistencia, no un texto creativo. Una temperatura baja reduce la variación entre las respuestas, pero no garantiza la corrección. Por eso siguen siendo necesarias la validación del esquema y las reglas de negocio.

Los nombres de los modelos y las funciones de la API también cambian con el tiempo. Al implementar esto en entornos de producción, elija un modelo y un método de salida estructurada que su proveedor soporte actualmente.

Paso 5: Agregar las reglas de calificación

Esta parte no debería entregarse completamente al LLM. Supongamos que los criterios de ejemplo de la agencia son:

• el proyecto corresponde a trabajo de desarrollo de software
• cuando se indica un presupuesto, este debe ser de al menos ₹2,00,000
• el mensaje no es spam
• hay suficiente información para comprender el requisito

Cree app/services/scoring_service.py, comenzando con la importación:

from app.schemas.lead import LeadAnalysis

Luego, la función de puntuación, que comienza en cero, recopila las razones detrás de cada ajuste y devuelve inmediatamente cero para el spam:

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
    }

Se trata de un sistema de puntuación sencillo e ilustrativo. Una agencia real podría tener en cuenta otros factores:

• tamaño del proyecto
• sector industrial
• ubicación
• disponibilidad del servicio
• grado de urgencia del cliente
• interacciones anteriores
• confianza en el presupuesto indicado
• leads duplicados

Pruebe la función de puntuación con ejemplos reales antes de permitir que rechace automáticamente los leads.

Paso 6: Conectar al agente con FastAPI

Cree app/main.py e importe FastAPI:

from fastapi import FastAPI

El resto del archivo vincula el esquema, la función de análisis y el servicio de puntuación a través de un punto de acceso:

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
    }

Iniciar el servidor:

uvicorn app.main:app --reload

Luego abra la documentación interactiva de la API:

http://127.0.0.1:8000/docs

Desde allí puede enviar una oportunidad de negocio e inspeccionar la respuesta estructurada.

Paso 7: Pruebe con una oportunidad realista

Envíe una solicitud de ejemplo como esta:

{
  "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."
}

Un resultado de extracción plausible se ve así:

{
  "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"
}

El servicio de puntuación evalúa luego los datos extraídos, con resultados como estos:

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

Tenga en cuenta que esta salida es una ilustración de lo que se puede esperar, no una medición obtenida de una ejecución en tiempo real de la API.

Paso 8: Almacenar leads en PostgreSQL

Para un uso empresarial real, no basta con conservar los resultados solo en la memoria, por lo que se requiere persistencia. Una tabla simple comienza de esta manera:

CREATE TABLE leads (
    id BIGSERIAL PRIMARY KEY,

Las columnas restantes contienen los detalles del líder y el análisis:

    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()
);

La columna analysis conserva la salida estructurada original de la IA, lo cual es útil cuando necesitas depurar por qué un lead recibió una determinada clasificación.

Para el entorno de producción, también debes planificar:

• un identificador único para cada lead
• una forma de detectar duplicados
• índices que cubran el estado y la fecha de creación
• encriptación y un estricto control de acceso, ya que los datos de los leads son sensibles
• migraciones de esquema
• un registro de auditoría

Paso 9: Agregar automatización

En este punto, el agente deja de ser simplemente una API. Imagina este flujo:

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

Cuando llega un cliente potencial calificado, el sistema podría:

1. almacenar al cliente potencial en la base de datos
2. notificar al equipo de ventas
3. crear un registro en el CRM
4. asignar a un representante de ventas
5. programar un seguimiento
6. actualizar el estado del cliente potencial

La capa de automatización podría ser n8n, un proceso en segundo plano o un sistema basado en colas. En entornos de producción no es sensato hacer que todo el proceso dependa de una sola solicitud HTTP síncrona. Un diseño más robusto incluye una cola en el medio:

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

Los leads se procesan de forma asíncrona y los trabajos fallidos pueden intentarse nuevamente.

Paso 10: Agregar revisión humana

Esto podría ser la parte más importante. La IA puede interpretar mal un lead. Considere este mensaje:

“Actualmente estamos comparando opciones de CRM y no tenemos presupuesto definido, aunque nos gustaría tener una idea de los precios.”

El modelo podría clasificar la intención como media o alta, mientras que la empresa preferiría dirigir el lead a una persona en lugar de marcarlo automáticamente como calificado. Esa es la razón de los tres estados:

• Calificado: el lead cumple con las reglas y pasa al equipo de ventas.
• En revisión: el lead contiene contenido útil, pero debe decidirlo un humano.
• No calificado: el lead no cumple con los criterios configurados.

La revisión humana es de mayor ayuda cuando:

• no se indicó presupuesto
• La necesidad es vaga.
• El modelo parece incierto respecto a su propio resultado.
• Los detalles del mensaje se contradicen entre sí.
• El remitente opera en una industria a la que la empresa no atiende.

Un buen sistema de IA no oculta la incertidumbre; la hace visible.

Qué hace que esto sea un agente

Una simple llamada a un LLM consiste únicamente en entrada, modelo y salida:

Input → LLM → Output

Un flujo de trabajo de agente hace más. Entiende la tarea recibida, extrae la información relevante, aplica herramientas o reglas de negocio, elige el siguiente paso, almacena el estado, activa una acción y vuelve a intentarlo o escala la situación cuando algo falla. Para el filtro de leads, la ruta completa se ve así:

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

La IA es solo un componente. La aplicación backend hace que todo el proceso sea fiable, y esa distinción es importante.

Mejoras antes de la producción

Una primera versión es suficiente para ver el flujo de trabajo, pero no debe lanzarse tal cual.

Procesamiento en segundo plano. Ejecute el análisis de leads a través de una cola de tareas como Celery con Redis, RQ, una cola gestionada en la nube o un sistema de tareas basado en una base de datos. Esto ayuda con las reintentos y grandes volúmenes.

Detección de duplicados. Un lead puede llegar dos veces, una desde el sitio web y otra desde una campaña por correo electrónico. Compare por correo electrónico, empresa y otros identificadores.

Versionado de los prompts. Almacene la versión del prompt junto a cada resultado de la IA. Cuando cambien las condiciones, podrá saber qué prompt y reglas generaron un resultado anterior.

Observabilidad. Haga un seguimiento de la latencia de la IA, los errores de la API, el uso de tokens, el costo por lead, la distribución de los resultados de calificación y la frecuencia con la que los humanos anulan las decisiones del agente.

Un conjunto de datos de evaluación. Recoja leads reales con etiquetas revisadas por humanos y pruebe el sistema con ellos. Esto dice mucho más que juzgar al agente basándose en un solo ejemplo bueno.

Seguridad. Mantenga las claves de API completamente fuera del código del frontend, verifique cada solicitud entrante, proteja los datos personales y limite quiénes pueden ver los leads.

La lección de la arquitectura

Crear un agente de IA no se trata solo de llamar a un LLM. La verdadera ingeniería radica en el modelo: un problema de negocio claro, datos estructurados, validación fiable, reglas deterministas, persistencia, automatización, revisión humana y monitoreo. Si se omiten estos elementos, el resultado es un chatbot que parece inteligente pero no resuelve el problema de negocio.

Un filtro de leads no debería limitarse a generar una respuesta. Debería crear un flujo de trabajo útil y trazable. El modelo entiende los mensajes desordenados de los clientes, Python ejecuta el flujo, las reglas de negocio definen los criterios de calificación, PostgreSQL almacena el estado y la automatización conecta el resultado con el equipo de ventas. Juntos, convierten una demostración de IA en una aplicación funcional.

Una continuación lógica es conectar la API a una fuente de leads en tiempo real, agregar tareas en segundo plano y crear un panel de control para que los vendedores evalúen qué leads cumplen con los requisitos. El objetivo no es reemplazar todas las decisiones de venta con la IA, sino reducir el trabajo repetitivo para que las personas puedan concentrarse en los leads que realmente lo merecen.