ИИ-асссистенты для бизнеса

Шаблон ТЗ для разработки ИИ-ассисента на базе действующего проекта

Привет, Антон Миславский - разработчик ИИ-ассисентов. Ниже приведу ТЗ для разрабоки ИИ-асссистента для бизнеса на основе моего действующего проекта для агентства недвижимости, агентства по релокации, открытию банковских счетов и виз

ТЗ: Разработка ИИ-ассистента для обработки лидов (WhatsApp + amoCRM / Kommo)

1) Цели и KPI

Цель: автоматизировать первичный контакт и квалификацию лидов, разгрузить менеджеров, ускорить «speed-to-lead».
KPI (измеримые):
  • T1. Время первого ответа : ≤ 60 сек (24/7).
  • T2. Доля квалифицированных лидов (Q-rate): +30–50%.
  • T3. Доля лидов с назначенной встречей: +15%.
  • T4. Снижение ручных ответов на нецелевые запросы: –70%.
  • T5. Полнота заполнения карточки в CRM: >95% обязательных полей.

2) Каналы и охват

  • Входящий канал: WhatsApp (Wazzup вебхуки).
  • Исходящие сообщения: WhatsApp (Wazzup Send API).
  • CRM: amoCRM/Kommo (REST API v4).
  • Языки: RU/EN/HE/FR/GE/ES/IT, автоопределение по входящему сообщению.

3) Воронка и логика

Воронки:
  • BANK_ACCOUNT_UAE_OPENING - открытие банковский счетов
  • REAL_ESTATE_RENT_BUY - покупка недвижимости
  • GENERIC_FAQ - общие вопросы
  • SPAM/TEST - СПАМ лид
  • COMPETITOR - конкурент

Квалификация (пример для «счёт в Дубае»):

  • Резидентство, тип юрлица (FZ/LLC), обороты, источник средств, KYC документы, сроки

Роутинг:

  • qualified=true → передать в CRM ответственному + забронировать слот (если календарь подключён).
  • qualified=false/risky → отказ/альтернативы/база знаний.

Правила первого касания:

  • Менеджер должен ответить ≤15 мин (рабочее), ≤60 мин (нерабочее). ИИ — пинг/эскалация.

4) Архитектура (высокоуровнево)

  • Fast API для ассинхронности(/webhook ловит Wazzup вход).
  • OpenAI Assistants v2: один ассистент на сценарий, thread на диалог.
  • Redis Upstash: хранение состояния чата, дедупликация, throttle, блокировки.
  • amoCRM/Kommo: создание/обновление лидов/контактов/задач, заполнение кастомных полей.
  • Wazzup/GreenAPI: отправка сообщений, медиавложения, статусы доставок.
  • Логи: структурные (JSON), уровень INFO/DEBUG/ERROR, correlation-id на диалог.

5) Технологии и версии

  • Python 3.11+, FastAPI, requests/httpx, redis, pydantic (валидация), uvicorn (опц.).
  • openai новая (Assistants v2). Используем:
  • import openai и from openai import OpenAI (нужно для openai.NotFoundError).
  • БД не требуется (на первом этапе) — состояние в Redis.

6) Переменные окружения (.env)

# Flask
FLASK_ENV=production
SECRET_KEY=<<<random>>>

# Wazzup
W_API_TOKEN=<<<token>>>
W_CHANNEL_ID=<<<id>>>
W_WEBHOOK_VERIFY_TOKEN=<<<string>>>

# amoCRM
AMO_SUBDOMAIN=<<<subdomain>>>
AMO_CLIENT_ID=<<<id>>>
AMO_CLIENT_SECRET=<<<secret>>>
AMO_REDIRECT_URI=<<<redirect>>>
AMO_ACCESS_TOKEN=<<<token>>>
AMO_REFRESH_TOKEN=<<<token>>>
AMO_PIPELINE_ID=<<<id>>>
AMO_STATUS_NEW_ID=<<<id>>>
AMO_RESPONSIBLE_USER_ID=<<<id>>>

# OpenAI
OPENAI_API_KEY=<<<key>>>
OPENAI_ASSISTANT_ID=<<<assistant_id_primary>>>

# Redis Upstash
REDIS_URL=<<<tls://...>>>
REDIS_TOKEN=<<<upstash_token>>>

# Misc
TIMEZONE=Asia/Jerusalem

7) Redis: ключи и TTL

  • lead:thread:{wa_chat_id} → { "thread_id": "...", "assistant_id": "..." } TTL 30d
  • lead:lock:{wa_msg_id} → предотвращение повторной обработки (TTL 1h)
  • lead:rate:{wa_chat_id} → антиспам/антифлуд (TTL 60s)
  • lead:ctx:{wa_chat_id} → компактный контекст (стадия воронки, ответы на анкеты) TTL 7d

8) REST-эндпоинты

8.1 /webhook [POST] — входящий Wazzup вебхук

Тело (пример):
{
"event": "message",
"message": {
"id": "wa_msg_id",
"chat_id": "whatsapp:+9715....",
"from_me": false,
"text": "Хочу открыть счёт в Дубае",
"media": null,
"timestamp": 1730000000
}
}
Ответ: 200 OK всегда (ошибки только в логах).
Действия:
  1. Дедуп по message.id.
  2. Классификация/язык.
  3. Извлечь или создать thread_id (OpenAI Assistants v2).
  4. Отправить в тред системный контекст + сообщение.
  5. Дождаться run-завершения, получить ответ, при необходимости вызвать tools:
  • tool=crm.upsert_lead_contact
  • tool=calendar.schedule (опц.)
  • tool=wazzup.send
  1. Ответить пользователю через Wazzup.

8.2 /healthz [GET]

  • Возвращает {"status":"ok","ts":...}.

9) Интеграции: требования и маппинг

9.1 amoCRM поля

  • lead.pipeline_id = AMO_PIPELINE_ID
  • lead.status_id = AMO_STATUS_NEW_ID
  • Кастомные поля:
  • cf_country = страна ПМЖ
  • cf_company_type = FZ/LLC/solo
  • cf_turnover = месячный оборот
  • cf_source_of_funds = источник средств
  • cf_language = RU/EN
  • Контакт: телефон (E.164), имя из WA (если есть), теги ["whatsapp","ai-assistant"].
  • Примечание: вставить краткую сводку квалификации ИИ (5–7 строк).

9.2 Wazzup

  • Отправка: текст, emoji, вложения (pdf/jpg/png), шаблоны (если подключены).
  • Повторы: ретраи 3× с backoff (1s/3s/10s).

10) OpenAI Assistants v2 (настройки)

  • assistant_id: OPENAI_ASSISTANT_ID
  • Инструкции ассистента (system prompt):
  • – стиль: деловой, кратко, без «воды»;
  • – правила воронки: задать 6–8 конкретных вопросов по KYC;
  • – язык ответа = язык входящего;
  • – никогда не обещать того, чего нет;
  • – всегда добавлять «что дальше» (CTA: запрошу документ, предложу слот).
  • Инструменты (functions): описать JSON-схемы:
  1. crm_upsert_lead(payload)
  2. crm_add_note(lead_id, text)
  3. wazzup_send(chat_id, text|media)
  4. calendar_book(email|phone, slot_pref) (опц.)
  • Защита: анти-prompt-injection (правила неизменяемы), обрезка контекста до N последних реплик.

11) Ошибки и ретраи

  • Сетевые/429: @retry (exp backoff) макс. 3–5 раз.
  • OpenAI openai.NotFoundError: пересоздать thread/assistant по месту, залогировать ERROR.
  • Вебхуки: всегда 200, внутренние ошибки — в лог + алерт.
  • Зацикливание tool-вызовов: жёсткий лимит tools_per_run <= 5.

12) Логирование и мониторинг

  • Корреляционный id: cid = f"{wa_chat_id}:{wa_msg_id}"
  • Логи JSON: time, level, cid, stage, event, payload_size, latency_ms.
  • Метрики (Prom-style):
  • msg_in_total, msg_out_total, run_latency_ms, crm_upsert_errors_total, sla_breaches_total.

13) Безопасность и соответствие

  • Хранить минимум персональных данных (PII) в Redis, TTL.
  • Шифрование секретов только в .env/секрет-хранилище Replit.
  • Валидация входящих вебхуков (Wazzup verify token).
  • Логи без полного тела документов; не писать медиа в логи.

14) Тест-план (обязательно)

  • Юниты: парсинг вебхука, дедуп, нормализация телефона, определение языка.
  • Интеграционные: мок Wazzup/KommoCRM/OpenAI.
  • E2E: сценарии:
  1. Горячий лид (все ответы в норме) → создаётся лид, идёт на менеджера.
  2. Нецелевой → вежливый отказ + ресурсы.
  3. Ошибка amoCRM (401) → авто-refresh токена (если реализуем) и повтор.
  4. Повторный дубликат сообщения → игнор.
  5. Большой медиафайл → обработка/ошибка-сообщение.

15) Критерии приёмки

  • A1. Первичный ответ ≤ 60 сек в 99-перцентиле.
  • A2. Создание лида в amoCRM с заполнением всех указанных полей.
  • A3. Дедупликация входящих сообщений по message.id.
  • A4. Ретраи 429/5xx работают, не ломают idempotency.
  • A5. Логи читаемы, с cid, без PII утечек.

16) План работ и артефакты

  • W1: каркас FastAPI, /webhook, .env, healthz, базовые логи.
  • W2: интеграция OpenAI v2, threads/runs, инструменты-заглушки.
  • W3: Wazzup send/receive, Redis состояние, дедуп/антифлуд.
  • W4: amoCRM upsert + маппинг полей, заметки, ответственный.
  • W5: Тест-план, нагрузочное (100 одновременных чатов), финальные логи/метрики.
  • Deliverables: код + README (переменные, как запустить), Postman-коллекция, пример .env.example.

17) Пример: код /webhook (FastAPI, комментарии для дебага)

Примечание: в проде вынести tool-функции в отдельные модули, добавить pydantic-схемы входов/выходов, трейсинг и метрики.

18) Prompt/Инструкции ассистента (скелет)

Ты — AI-ассистент для первичной квалификации лидов.
Правила:
1) Отвечай на языке пользователя, кратко, по делу.
2) Задавай до 8 вопросов для квалификации KYC/деловой цели.
3) Если лид подходит — предложи удобное время/способ связи и вызови инструмент crm_upsert_lead.
4) Если не подходит — вежливо откажи, предложи альтернативы.
5) Никогда не обещай недоступных услуг.
6) Итог каждого диалога: чёткий next step.
Tools (JSON-схемы для v2): описать поля crm_upsert_lead, wazzup_send и пр. (idempotent!).

19) Документация для разработчика

  • README.md: как запустить локально/на Replit, переменные, проверка /healthz.
  • docs/flows.md: диаграмма шагов от вебхука до CRM.
  • Postman/Insomnia коллекция: примеры вебхуков, ответы Wazzup, amoCRM upsert.