📞 AI-Аналитик Качества Звонков (Call Quality Analyst)

Автоматизированная система контроля качества отдела продаж на базе Cloud.ru Evolution AI Agents.

💡 О Решении

Руководители отделов продаж (РОП) тратят до 10 часов в неделю на ручное прослушивание звонков. Это дорого, долго и неэффективно — охватывается лишь 5-10% разговоров.

AI-Аналитик решает эту проблему, обеспечивая 100% покрытие звонков. Это мультиагентная система, которая:

1. Подключается к CRM (Битрикс24).
2. Находит целевые звонки.
3. Транскрибирует аудио в текст (используя Sber SaluteSpeech).
4. Проверяет соблюдение скриптов продаж по заданным чек-листам.
5. Бот в телеграме генерирует сводные отчеты (PDF/Excel) и дает рекомендации менеджерам.

🚀 Демонстрация

• Видео-презентация
• Презентация (PDF)

---

🏆 Соответствие Критериям Оценки (Technical Score)

Мы спроектировали архитектуру, следуя стандартам Cloud.ru MCP и требованиям хакатона.

Функциональность агентной системы

• Сложная логика поиска: Реализован инструмент search_calls с фильтрацией по менеджерам, датам и статусам, а не просто "дай все".
• Обработка ошибок: Все инструменты обернуты в try/except с возвратом стандартизированных McpError (коды -32603, -32602).
• Human-in-the-loop: Учтены ограничения безопасности CRM. Агент умеет делегировать задачу скачивания файла пользователю посредством ссылки, если API не дает прямого доступа, и подхватывать ссылку на лету.
• Валидация: Используется Pydantic для строгой типизации всех входных параметров инструментов.

Архитектура и качество кода

• Микросервисная архитектура: Решение разбито на 3 независимых MCP-сервера в монорепозитории:
  • mcp_bitrix24 — интеграция с CRM.
  • mcp_call_processor — транскрибация и диаризация (SaluteSpeech).
  • mcp_checklist_manager — управление критериями оценки.
• Stateless & S3: Данные чек-листов должны храниться в Cloud.ru Evolution Object Storage (S3), что обеспечивает сохранение состояния при перезапуске контейнеров (выполняет требование cloud-native).
• Чистый код: Единый стиль, Type Hints, использование fastmcp.
• Телеметрия: Внедрен OpenTelemetry для трейсинга запросов и Prometheus метрики для мониторинга вызовов API.

Готовность к включению в Evolution AI Agents

• Полная совместимость: Все серверы написаны на FastMCP и используют транспорт streamable-http.
• Стандартизация: Для каждого сервиса подготовлены:
  • Dockerfile — оптимизированные образы на базе python:3.12-slim с использованием uv для быстрой сборки.
• Безопасность: Секреты (API ключи, токены) прокидываются только через переменные окружения.

---

🛠 Техническая Архитектура

graph TD
    User((Пользователь)) -->|Telegram| Bot[Telegram Bot Interface]
    Bot -->|API Request| Agent[AI Agent (Cloud.ru Platform)]
    
    subgraph "MCP Cluster"
        Agent <-->|MCP Protocol| B24[MCP Bitrix24]
        Agent <-->|MCP Protocol| STT[MCP Call Processor]
        Agent <-->|MCP Protocol| DB[MCP Checklist Manager]
    end
    
    B24 <-->|REST API| CRM[Битрикс24]
    STT <-->|API| Salute[Sber SaluteSpeech]
    DB <-->|S3 API| S3[Evolution Object Storage]

🚀 Запуск и Установка

Локальный запуск (Docker Compose)

Проект полностью контейнеризирован. Для запуска всех сервисов одной командой:

1. Клонируйте репозиторий:

   git clone https://github.com/Zzzpize/cloud-ru-hackathon

2. Создайте файл .env в корне (на основе .env.example).
3. Запустите стек:

   docker-compose up --build

Сервисы будут доступны на портах:

• mcp_bitrix24: 8001
• mcp_call_processor: 8002
• mcp_checklist_manager: 8003

⚙️ Конфигурация (.env)

Для запуска проекта создайте файл .env в корне репозитория.

🔹 Интеграция с Битрикс24 (mcp_bitrix24)

Переменная	Описание
BITRIX24_WEBHOOK_URL	Входящий вебхук для доступа к REST API Битрикс24. Должен иметь права на CRM, Disk и Users.

🔹 Распознавание речи (mcp_call_processor)

Используется API Sber SaluteSpeech.

Переменная	Описание
SBER_OAUTH_CLIENT_ID	Client ID для авторизации (получается в Sber Studio)
SBER_OAUTH_CLIENT_SECRET	Secret Key для авторизации

Деплой в Cloud.ru

⚠️ Проблемы

С связи с постоянными ошибками на сервисе, команда не смогла загрузить проект на Cloud.ru, но локальные тесты полностью показывают работоспособность

📖 Примеры использования

Пользователь: "Оцени звонки Александра Руднева за последние 2 дня"

Агент:

1. Обращается к mcp_bitrix24 → находит ID сотрудника.
2. Ищет звонки этого сотрудника за указанный период.
3. Скачивает аудио и отправляет в mcp_call_processor.
4. Сверяет текст с актуальным чек-листом из mcp_checklist_manager. Результат: Текстовый отчет с оценкой (например, "72/100") и найденными ошибками.

---

👥 Команда и Роли

• Боронин Фёдор (Team Lead / DevOps): Архитектура MCP, интеграция с Битрикс24, CI/CD.
• Босенко Тимофей (Product Manager): Customer Development, финансовая модель, сценарии использования, презентация.
• Зиновьев Дмитрий (ML Engineer): Разработка mcp_call_processor, интеграция Sber SaluteSpeech, алгоритмы диаризации.
• Ятрушев Павел (Backend Developer): Разработка mcp_checklist_manager, реализация S3-хранилища, логика CRUD.

🔮 Планы по развитию

1. Real-time анализ: Анализ звонка прямо в процессе разговора (Streaming API).
2. Генерация карточек сделок: Автоматическое заполнение полей CRM на основе транскрибации.
3. Коучинг: Персональные рекомендации для менеджеров на основе исторических данных.

---

Проект разработан в рамках Хакатона Cloud.ru 2025.