Створыце агента для атрыбутавання кандыдаў на ролю кіраўніка ў сферы AI на Python з FastAPI і Pydantic

Большасць компаній не страждае ад нехваткі прыходзячых кліентаў. Іхнія проблемы — у тым, каб адсортаваць іх. Чырвоныя запыткі можу прыходзіць праз формы на веб-сайтах, кампаніі па электранях і інструменты маркетынгу, і хтось усё рава павінен адкрываць кожны з іх, чытаць паведамленне, з’ясаваць, чаго хоча кліент, пераканацца ў бюджэце і вырашыць, чыры гэта заслуговае на увагу. Калі колькасць запытак зрастае, такая ручная сортаванне стае даскладным і дорогім.

Практычны вопыт — чы можа агент на базе ШЫ прыймаць прыходзячыя запыткі, з’ясаваць ўсілкі кліента, пераканацца ў яных па правілах бізнесу і направіць наяўныя кліенты ў віддзел прымытку замоваў. Гэта можа быць, але не шляхом простага вставлення кожнай запыткі ў ШЫ і павернення ў тым, што ён адпавісі. Надзеяны сістэма патрабуе структураванага выходу, чыстаўых правілаў, пераканання, зберагчэння і правільнага алгорытму работы. Наступныя раздзелы паказваюць, як стварыць такую сістэму на Python.

Што робіць сістэма

Працэс ўсьмохнены: прыходзіць патрон, сістэма яго адначасова адгукваецца, аналізуе, оцінюе, зберагае рэзультат і запускае наступны крок.

Узьмімо гэтыя словы ад паўстаноўчага кліента:

„Нашай камандзе прадажоў патрэбны CRM, прызначаны спецыяльна для нас, з прыблізна 30 месцаў, якія трэба доставіць за два месцы. Скількі гэта будзе коштаць прыблізна?“

Чалавек мог бы адразу выявіць калькі фактов:

• еўсць чыстае бізнес-патрабаванне
• праект — гэта індывідуальны програмны продукт
• у каманды прыблізна 30 корыстнікаў
• еўсць часавы прыметак для доставкі
• цэна ёсць ключовым пытаннем

Агент таксама павінен выявіць гэтыя факты і памагчы камандзе прадажоў выбраць наступныы крок. Ён не павінен прыпускаць, што кожны дзейневы паведамленне ёсць хорашым патронам. Ён мусі ацэніць інфармацыю на адной лініі з рэальнымі крэтэрыямі адбору компаніі.

Архітэктура

Планаваны працэс выканання паказаны ніжэй:

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

Адзін выбор у дызайне мае прыорытэт над усімі іншымі: трэба выдзеліць розумеўне ШЫ ад бізнес-рашэнняў. LLM выкарыстоўваецца для выкарыстоўвання інфармацыі з запрошэння кліента, а ваш сэнсарны код вяршыць рашэнні пра тое, як гэтая інфармацыя вплывае на атрыбуты кандыдата. Дзякуючы такаму раздзелу сістэму лёгкае тэставаць, дыягноставаць і змяніць.

Шаг 1: Адначыце, што робіць кандыдата атрыбутаваным

Бізнес-правілы маюць прыорытэт над кодам. Вярнімся да прыкладу агэнцыі з розрабоцыі програмнага забава. Яна можа атрыбутаваць кандыдата як атрыбутаванага, калі:

1. кліент мае рэальную патрэбу ў програмнаму забаве
2. гэтая патрэба падходзіць да аддарамоў, якія прысутны у агэнцыі
3. у запрошэнні ёсць достатнькі дэталі, каб зрозумець праект
4. бюджэт або намер кліента падпадае пад стандарты агэнцыі
5. запрошэнне не ў якосты спаму і не ў якосты явна нерэлевантнага запіту

Этыя правілы ўзятыя як прыклад, і рэальны бізнес павінен сам встановіць свае прагі. У заполненай інформацыі можа быць така даныя: служба — гэта індывідуальная разработка CRM, бюджэт — ₹5,00,000, тэрмін выпалення — два месцы, колькасць корыстувачаў — 30, ступень абсалютнасці намеру — высокі, а рашэнне — кваліфікованае.

Штучны інтэлект павінен выкарыстоўваць гэтыя даныя. Фінальнае рашэннее должны прыміць правілы бізнесу.

Крок 2: Стварэнне праекту на Python

Python падходзіць для гэтай задачы завдзяк сваему экасістэму для API, інтэграцый з LLM, апрацоўкі даных і автаматызацыі. Структура праекту выглядае так:

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

З’явіце неабяцковыя пакеты:

pip install openai pydantic fastapi uvicorn python-dotenv

Элементы ўключаюць:

• FastAPI для бэкэнд-API
• Pydantic для структураванага верыфікацыі
• API OpenAI для прыклада LLM
• PostgreSQL як база дадзеных у працоўнай сітцы
• звычны Python для ацэнкі партнероў

Прадаўца LLM можа быць пазней заменены на іншага.

Шаг 3: Адзначыць структураваны шэма партнера

Паўзловыя памылкі ў аплікацыях AI — гэта прыйманне вольнага тэксту як фінальнага рэзультата. Такія адпаведзі цяжка надзеясніваць надзеянна:

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

Мэтой яе ўзаемна зрозумелы JSON. Створыце app/schemas/lead.py і пачніце з імпортаў:

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

Потым задаюцца модэлі, пачынаючы з прыйшлага кандыдата і продовжваючы аналізам, які мусіць вернуць модэль:

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

Цячас адказ AI мае чыткі фармат. Калі модэль вярта некорэктную значэнне, прыкладнэнне можа яго адхіліць або обработаць, замест таго каб тыха сховваць некарэктныя даны.

Шаг 4: Стварэнне функцыі аналізу потэнцыйных кліяў

Далей ідзе app/agents/lead_agent.py. Модэль павінна расцёніць тое, што кажа потэнцыйны кліент, і не павінна выдумваць нічога, чаго няма. Пачніце з імпортаў:

import json
import os

Далей выконвачыцца сама функцыя аналізу. Яна надае даныя модэлю, прасіць пра выхід, які падходзіць па схеме, і пераканаецца ў правядлівасці таго, што вяртаецца:

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)

Чаму тэпература равна нулю

Для выкарыстоўвання трэба стабільнасць, а не творчы стыль пісьма. Нізкая тэпература зменшае разніцу між адпаведзямі, але не гарантуе правільнасці. Таму яшчэ патрэбны перакананне схемы і бізнес-правіла.

Назвы модэляў і функцыі API таксама зміняюцца з часам. Калі вы впрыменяеце гэта для працы ў працэсе, выберыце модэль і метод структураванага выходу, якія зараз падтрымлівае ваш прадаўцы.

Шаг 5: Дадаць правіла кваліфікацыі

Гэю частку не трэба цэлым чынам перадаваць LLM. Падазроўваю, што прыкладныя крэтарыі агэнцыі ўключаюць:

• праект являе сабою значны програмны работа
• калі задаецца бюджэт, ён не менейшы за ₹2,00,000
• паведамленне не ў якосты спаму
• ёсць достатнья інфармацыя, каб зрозумець трэбаванне

Створыце app/services/scoring_service.py, пачынając з імпорту:

from app.schemas.lead import LeadAnalysis

Потым функцыя атрыбутавання, якая начынаецца з нуля, сабіра прычыны кожной корэктаванні і вяртае негайны нуль для спаму:

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
    }

Гэта простая, ілюстратыўная схема ацэнкі. Рэальная агэнцыя можа вазьмаць пад увагу іншыя фактары:

• размах праекту
• сектар промышленнасці
• месца розташоўкі
• наявнасць адпаведнай службы
• ступень трыбоцтва кліента
• пярэднія абранні з кліентам
• доверлівасць да зазначанага бюджэту
• падобныя запросы

Перад тым, як дазволіць функцыі ацэнкі аўтаматычна адхіляць запросы, перапрацаваць яе на рэальных прыкладах.

Шаг 6: З’яўляйце звязак між агентам і FastAPI

Створыце app/main.py і імпортуйце FastAPI:

from fastapi import FastAPI

У рэшце файла схема, функцыя аналізу і служба атрыбутавання з’едынаюцца за дапамою аддаптнага пункту:

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
    }

Запускайце сервер:

uvicorn app.main:app --reload

Потым ачыніце інтэрактыўныя документы API:

http://127.0.0.1:8000/docs

З таму вы можэце адказаць на запіт і пераглянуць структураваны адказ.

Шаг 7: Прабуйце рэалістычны запіт

Адправьце прыклад запіту, падобны гэтаму:

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

Можлівы рэзультат выкарыстоўвання выглядае так:

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

Служба аналізу рэйтынга пасля чаго ацэніць выкараныя даныя, і рэзультат будзе выглядаць так:

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

Пам’ятайце, што гэты выхід — толькі ілюстрацыя таго, чаго можна спакаваць, а не рэзультат выканання API у рэальным часе.

Крок 8: Зберагачыце даныя кліентаў у PostgreSQL

Для рэальнага бізнес-выкарыстання недастатнька толькі ўтрымванне рэзультатаў у памяці, таму неабходна ўтрымванне дадзеных у довгачасовай памяці. Простая табелю пачынаецца так:

CREATE TABLE leads (
    id BIGSERIAL PRIMARY KEY,

Іншыя столбцы паказваюць даклэджы пра лідэра і аналіз:

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

Колонка analysis зберагае первоначальны структураваны выхад AI, што дапамагае, калі трэба выявіць прычыну таго, чаму пэўны кліент атрымаў пэўную класыфікацыю.

Для прыменення ў рэальных умовах таксама неабходна планаваць:

• унікальны ідэнтыфікатор для кожнага кліента
• спосаб выяўлення дуплікатаў
• індэксы, якія паводзяцца за статусам і часам стварэння
• шыфраванне і строгі контроль даступу, адколькі даны кліента ўскладненыя
• міграцыі схемы
• хісторыю аўдыту

Шаг 9: Дадаць автаматызацыю

У гэты момент агент стае чымсьці большым, чым проста API. Уявіце сабе гэтыя крокі:

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

Калі прыходзіць кваліфікаваны партнер, сістэма можа:

1. зберагчыць інфармацыю пра партнера ў базе дадзеных
2. паведаміць каманду з продажоў
3. стварыць запіс у CRM
4. прадзеліць партнера адпаведнам прэдставіцелю з продажоў
5. запланаваць наступны кантакт
6. ацыянаваць статус партнера

Слой автаматызацыі можа быць n8n, фонавы працоўнік або сістэма на адной канвеі. У працэсе вырабоцтва нерозумна пакладацца на адну сінхронную HTTP-запрос. Болей моцны дызайн включае канвею ў сваю структуру:

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

Потэм партнеры працоўнаеўцы обрабляюцца асінхронна, і няудачныя запускі можна прабаваць зноў.

Шаг 10: Дадаць перагляд чалавека

Гэта можа быць найважнейшы элемент. Штучны інтэлект можа неправа расценіць партнера. Разглянем гэты прыклад:

„Зараз мы параблікуем варыянты CRM і ў нас няма вялікаг бюджэту, хоця мы хацелі б знайсці прыблізную цэну.“

Мадэль можа пазначыць інтэнцыю як серэдню або высокую, тады як компанія воліць перадаць партнера чалавеку, а не автаматычна атрыбутаваць яго як прыдатнага. Самэль гэтаму існуюць тры статусы:

• Прыдатны: партнер пасходзіць па правілах і пераходзіць да каманды з продажоў.
• На пераглядзе: у партнера ёсць корыстны контэнт, але рашэнне павінен прымець чалавек.
• Непрыдатны: партнер не пасходзіць па заданым крытэрыям.

Перагляд чалавека найбольш дапамагае, калі:

• не быў зазначаны бюджэт
• Патрэба застаецца нечыярым.
• Мадэль, здаецца, не впэўнена ў сваёй вынікай.
• Дакладныя даныя ў паведамленні супераслігаюцься.
• Адправальнік працуе ў галузі, якую компанія не адслужвае.

Хорашая сістэма AI не прыховвае невялікасці. Яна робіць невялікасці віднымі.

Што робіць гэтае агентам?

Звычны вызов LLM — гэта проста вхідныя даны, мадэль, вынік:

Input → LLM → Output

Рабочы працэс агента выпрацоўвае больш. Ён розумее прыйняты задачэ, выкарыстоўвае адпаведную інфармацыю, прыкладвае інструменты або бізнес-правіла, выбірае наступны крок, зберагае стан, запускае дзеянне, а таксама прабуе знову або паднімае проблему на вышэйшы ранг, калі ўтвараюцца труднасці. Для фільтра лідоў паўная дарога выглядае так:

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

Штучныя нейронныя сеткі — гэта толькі адна з складовых. Застосунак на бакэндзе робіць увесь працэс надзеяным, і гэта разліка мае значэнне.

Удосконаленні перад запускам у працэ

Першая версія дастыць можлівасць паглядзець на алгорытм работы, але яе не трэба выдаваць такой, якая ёсць.

Апрацоўка у фоне. Аналіз патронавацькіх даных трэба выканаць за дапамою чэргі задач, такой як Celery з Redis, RQ, чэргі, керованай хмарам, або сістэмы задач, базуецца на базе дадзеных. Гэта дапамагае працаваць з павторнымыя спробамі і велікім об’ёмам дадзеных.

Автадыектаванне дуплікатав. Одні і тыя ж патронавацькія даны можу прыйсці два разы — ад сайту і ад кампаніі паштою. Пораўняйце електронную пашту, назву компаніі і іншыя ідэнтыфікаторы.

Версіюванне запітаў. Зберагаюце версію запіта разам з кожным рэзультатам штучнай нейроннай сеткі. Калі змянююцца крэтынты, вы зможаце з’ясаваць, які запіт і правілы стварылі пакананы рэзультат.

Возможнае аналізаванне стану. Следзіце за затрымкамі працы ШЫ, памылкамі API, выкарыстоўваннем токенав, косцю за кожнага потэнцыяльнага кліента, распадам рэзультатаў атрыбутацыі і тым, як часта людзі перакладзаюць рашэнні агента.

Набор дадзеных для ацэнкі. Складзіце рэальных потэнцыяльных кліентаў з атрыбутамі, перакантролаванымі людзьмі, і працаваце з сістэмай на ўсіх іх. Гэта дае набагато большую інформацыю, чым ацэнка агента на адным хорашым прыкладзе.

Безпека. Полныя адключыце канты прыступу API ад коду фронтэнду, перакантролюйце кожны прыходзячы запіт, захаваце персональныя даны і обмежыце права на перагляд потэнцыяльных кліентаў.

Урокі архітэктуры

Стварэнне агента AI — гэта не проста вызов LLM. Настоямы інжынерныя аспекты крыюцца ў самай модэлі: чыстая бізнес-задача, структураваныя даны, надзеяныя способы верыфікацыі, дэтэрміністычныя правіла, стабільнасць, автаматызацыя, людская пераглядка і манітарынг. Без гэтага рэзультатам будзе чат-бот, які здаецца розумным, але не рашае бізнес-задачу.

Фільтр кандыдаў не толькі павінен даўаць адпаведзь. Ён таксама павінен ствараць корыстны, працоўны працэс. Модэль розумее хаотычныя паведамленні кліяў, Python керуе гэтым працэсам, бізнес-правіла візначаюць крэатывнасць кандыдаў, PostgreSQL зберагае стан, а автаматызацыя паў’язуе рэзультаты з камандай з продажоў. Разам яны ператвараюць дэманстрацыю AI у робочы прыкладнік.

Прыгным крокам ёсць падключэнне API да рэальнага джэрага партнёраў, дадаўшы фонавыя заданні і стварэнне панелі керування для працавікама продажоў, каб тыя моглі ацэніць, калія партнёры падходзяць. Мета не ў тым, каб заменіць кожнае рашэнне па продажах на AI. Гэта ў тым, каб скасаваць павтаральную работу, каб людзі моглі сфокусавацца на тых партнёрах, якія таго заслуговуюць.