# Карточки агентов — продуктовый подход
#### Приложение 6. Карточки агентов -- продуктовый подход
#### к Акту сдачи-приёмки работ по Этапу 0
**Проект:** Grace CRM Assistant **Договор:** №04-002 от 24.04.2026 **Исполнитель:** ООО «Экобанкинг» **Заказчик:** ООО «АйТек»
---
## О методе описания
Каждый агент описан через продуктовую формулу:
**Продукт** -- что конкретно производит агент **Внутренний клиент** -- кто получает этот продукт (роль или другой агент) **Триггер** -- при каком условии агент запускается **Критерий выполнения** -- как проверить, что агент выполнил свою функцию
Такой подход позволяет однозначно определить границы каждого агента, порядок их взаимодействия и критерии приёмки на каждом этапе разработки.
---
## Контур 1 -- Sales AI (Grace CRM Assistant)
---
### Агент 1. Sync Agent -- Агент синхронизации
**Продукт:**
Актуальный поисковый образ данных Grace CRM в OpenSearch -- гарантирующий, что любой запрос от downstream-агентов отражает реальное состояние CRM на момент последнего запуска.
| Элемент | Содержание |
|-------------------------|-------------------------------------------------------------------------------------------------------|
| **Внутренний клиент** | Quality Agent, Recommendation Agent |
| **Механизм** | CLI -> API Grace CRM -> трансформация -> bulk index в OpenSearch |
| **Триггер** | Cron по расписанию + ручной запуск администратором |
| **Входные данные** | API Grace CRM: projects, activities, clients, tasks, comments, calculations, orders, users, objects |
| **Выходной продукт** | Обновлённые индексы OpenSearch (15 индексов) |
| **Критерий выполнения** | Все индексы обновлены без ошибок; расхождение Grace CRM / OpenSearch = 0 по завершении синхронизации |
| **Красный флаг** | Ошибка синхронизации -> downstream-агенты работают на устаревших данных -> все рекомендации невалидны |
**Режимы работы:**
| Режим | Триггер | Что синхронизируется |
|-----------------|-----------------------------------|--------------------------------------------------|
| Инкрементальный | Cron каждые 15 минут | Изменения с последнего запуска (`updated_since`) |
| Полный | Ежедневно в 02:00 / ручной запуск | Все сущности, полная пересборка индексов |
**Цепочка ответственности:**
```
Grace CRM (source of truth) ↓ APISync Agent ↓ bulk indexOpenSearch (15 индексов) → Quality Agent, Recommendation Agent
```
---
### Агент 2. Quality Agent -- Агент контроля качества данных
**Продукт:**
Ежедневный реестр проектов с критическими пробелами данных -- для менеджеров и РОПа -- с указанием конкретного поля, ответственного и срока устранения.
| Элемент | Содержание |
|-------------------------|-------------------------------------------------------------------------------------------------------|
| **Внутренний клиент 1** | Менеджер -- получает задачу на заполнение по своим проектам |
| **Внутренний клиент 2** | РОП -- получает сводку по команде и эскалацию при просрочке |
| **Триггер** | Ежедневно в 09:00 + при изменении статуса проекта |
| **Входные данные** | OpenSearch: `itech_projects`, `itech_calculations`; правила проверки из конфига |
| **Выходной продукт** | Структурированный реестр: проект -> пробел -> ответственный -> срок; сигнал в Notification Agent |
| **Критерий выполнения** | Доля проектов с полными данными ≥ 85% (вектор роста); каждый пробел имеет назначенного ответственного |
**Правила проверки (настраиваются в конфиге без релиза):**
| Проверка | Поле | Условие нарушения |
|-------------------|--------------------------------------------------------------------------------------|---------------------------------------------------|
| Обязательные поля | `account_id`, `property_id`, `project_status_id`, `probability_new`, `forecast_date` | Пусто |
| Следующий шаг | `next_action_date` | Пусто или дата в прошлом |
| Логика статусов | `calculation_status` | При статусе «КП выставлено» -- расчёт отсутствует |
| Активность | `last_activity_at` | Более 30 дней назад для активного проекта |
---
### Агент 3. Recommendation Agent -- Агент рекомендаций
**Продукт:**
Конкретный следующий шаг по каждому активному проекту -- для менеджера -- сформулированный на основе истории CRM и базы знаний RAGflow, доставляемый не позднее 2 часов после изменения статуса или по запросу.
| Элемент | Содержание |
|-------------------------|------------------------------------------------------------------------------------------------------------------|
| **Внутренний клиент** | Менеджер (первично); РОП (при просрочке реакции менеджера) |
| **Триггер** | Изменение статуса проекта / запрос менеджера / просрочка контакта |
| **Входные данные** | OpenSearch: история проекта, активности, комментарии; RAGflow: кейсы, скрипты, возражения |
| **Выходной продукт** | Рекомендация: действие + срок + обоснование + ссылка на кейс из базы знаний |
| **Критерий выполнения** | Менеджер знает следующий шаг по каждому активному проекту; нет проектов без зафиксированного следующего действия |
| **Вектор роста** | Снижение доли проектов без следующего шага; рост конверсии КП -> заказ |
**Формат рекомендации:**
```
Проект: [название] | Клиент: [название] | Стадия: [статус]
Последний контакт: N дней назад
Рекомендация: [конкретное действие]
Срок: [дата]
Обоснование: [краткое обоснование на основе истории]
Похожий кейс: [ссылка из базы знаний RAGflow]
```
---
### Агент 4. Notification Agent -- Агент уведомлений
**Продукт:**
Адресное уведомление нужному человеку в нужный момент через нужный канал -- без информационного шума -- как условие того, что сигналы системы реально доходят и вызывают реакцию.
| Элемент | Содержание |
|-------------------------|------------------------------------------------------------------------------------------------------------|
| **Внутренний клиент** | Менеджер / РОП / Зам. ГД -- в зависимости от типа события |
| **Триггер** | Сигнал от любого агента системы |
| **Входные данные** | Сигнал от агента + профиль получателя (предпочтительный канал) |
| **Выходной продукт** | Доставленное уведомление с подтверждённой реакцией |
| **Механизм доставки** | Adapter pattern: Mattermost (основной) / Telegram (резерв), канал настраивается per-user |
| **Критерий выполнения** | Реакция (действие или подтверждение) в течение N часов; при отсутствии реакции -- эскалация в Orchestrator |
| **Красный флаг** | Уведомление без реакции сверх SLA -> передаётся Orchestrator для эскалации |
**Матрица маршрутизации:**
| Событие | Получатель | Приоритет |
|----------------------------------------------------------|--------------|------------|
| Пробел в данных по своему проекту | Менеджер | Нормальный |
| Рекомендация по проекту | Менеджер | Нормальный |
| Просрочка реакции менеджера > SLA | РОП | Высокий |
| Критическое событие (крупная сделка, риск ухода клиента) | РОП, Зам. ГД | Высокий |
| Ежедневная сводка по команде | РОП | Плановый |
---
### Агент 5. Orchestrator -- Оркестратор
**Продукт:**
Бесперебойная работа агентной системы как единого целого -- для РОПа и Зам. ГД -- обеспечивающая, что ни одно критическое событие не теряется и каждый сигнал доходит до нужного человека в нужное время.
| Элемент | Содержание |
|-------------------------|------------------------------------------------------------------------------------------------------|
| **Внутренний клиент** | РОП, Зам. ГД |
| **Триггер** | Постоянно -- реагирует на сигналы всех агентов |
| **Входные данные** | Сигналы от всех агентов; SLA-параметры из конфига |
| **Выходной продукт** | Гарантия непрерывности потока сигналов и эскалаций; каждое событие имеет назначенного ответственного |
| **Критерий выполнения** | Отсутствие потерянных эскалаций; система работает без ручного вмешательства |
**Примечание:** Orchestrator не имеет одного артефактного продукта -- его продукт это состояние системы. Это принципиальное отличие от остальных агентов.
---
## Контур 2 -- Knowledge AI (база знаний)
---
### Агент 6. Ingest Agent -- Агент загрузки знаний
**Продукт:**
Проиндексированный документ в RAGflow с корректными метаданными -- готовый к поиску Query Agent и использованию Recommendation Agent.
| Элемент | Содержание |
|-------------------------|-------------------------------------------------------------------------------------------|
| **Внутренний клиент** | Query Agent, Recommendation Agent |
| **Триггер** | Загрузка нового документа ответственным за базу знаний |
| **Входные данные** | Документ (PDF, DOCX, MD) + метаданные: отрасль, тип клиента, стадия сделки, продукт, теги |
| **Выходной продукт** | Проиндексированная запись в RAGflow; обновлённый граф связей |
| **Критерий выполнения** | Документ доступен для поиска Query Agent; все метаданные заполнены |
**Обязательные метаданные документа:**
| Поле | Описание | Пример |
|---------------|-----------------|-------------------------------------|
| `industry` | Отрасль клиента | Энергетика, Строительство |
| `client_type` | Тип клиента | Генподрядчик, Интегратор |
| `deal_stage` | Стадия сделки | Расчёт КП, Переговоры |
| `product` | Продукт | НКУ, ВРУ, БКТП |
| `doc_type` | Тип документа | Кейс, Скрипт, Возражение, Регламент |
| `tags` | Теги | конкуренция, срок, цена |
---
### Агент 7. Query Agent -- Агент поиска знаний
**Продукт:**
Контекстный ответ с цитатой и ссылкой на источник -- для менеджера или Recommendation Agent -- за ≤ 5 секунд.
| Элемент | Содержание |
|-------------------------|-------------------------------------------------------------------------|
| **Внутренний клиент** | Менеджер (прямой запрос); Recommendation Agent (инструментальный вызов) |
| **Триггер** | Текстовый запрос менеджера / вызов от Recommendation Agent |
| **Входные данные** | Текстовый запрос + контекст проекта (отрасль, стадия, тип клиента) |
| **Выходной продукт** | Ответ + цитата из источника + ссылка на документ |
| **Критерий выполнения** | Релевантный ответ ≤ 5 секунд; источник указан всегда |
---
### Агент 8. Lint Agent -- Агент аудита знаний
**Продукт:**
Еженедельный отчёт о противоречиях, устаревших данных и логических разрывах в базе знаний -- для ответственного за базу знаний.
| Элемент | Содержание |
|-------------------------|------------------------------------------------------------------------------------|
| **Внутренний клиент** | Ответственный за базу знаний (роль `knowledge_manager`) |
| **Триггер** | Еженедельно |
| **Входные данные** | Все документы в RAGflow |
| **Выходной продукт** | Отчёт: противоречия, документы старше 6 месяцев, незаполненные разделы |
| **Критерий выполнения** | Выявлены все документы старше 6 месяцев и документы с конфликтующими утверждениями |
---
## Схема взаимодействия агентов
```
Grace CRM
↓ API
[1] Sync Agent ──────────────────────────────────────────────► OpenSearch
│
┌───────────────────────────────┘
│
[5] Orchestrator
(управление, SLA)
│
┌────────────────┴────────────────┐
▼ ▼
[2] Quality Agent [3] Recommendation Agent
(пробелы в данных) (следующий шаг) ◄── RAGflow
│ │ [6] Ingest Agent
└────────────────┬────────────────┘ [7] Query Agent
▼ [8] Lint Agent
[4] Notification Agent
(Mattermost / Telegram)
│
┌────────────────┼────────────────┐
▼ ▼ ▼
Менеджер РОП Зам. ГД
```
---
##