Меня зовут Максим Шакуров, я ML-инженер в VK. В этой статье — рассказ о создании DataCopilot, ИИ-системы, которая помогает сотрудникам находить данные, генерировать SQL и работать с внутренней документацией.

Мы начали с анализа реальных запросов, поступающих в поддержку Data Office и команду платформы данных. Большинство из них сводились к трём типам:

• Поиск нужных данных среди тысяч витрин.
• Генерация валидного SQL и ClickHouse-кода.
• Ответы на вопросы по внутренней документации.

Из этих задач родились три ключевые функции будущего бота. DataCopilot помогает ориентироваться в каталоге витрин, объясняет, что и где хранится, подсказывает, как заполнить заявку на доступ, отвечает на вопросы по документации и генерирует готовые SQL-скрипты для ETL-процессов.

За февраль 2026 года системой воспользовались 731 сотрудник, а retention составил 68% — 499 человек вернулись. По нашим оценкам, это экономит десятки часов рабочего времени ежедневно и снижает нагрузку на поддержку.

Почему мы выбрали мультиагентную архитектуру

Изначально мы рассмотрели классический RAG-подход: Redis как векторное хранилище, BERT для эмбеддингов, bge-m3 как реранкер и LLM с поддержкой tool calling. Но столкнулись с ограничениями:

• Сложность масштабирования: изменения в одном блоке могут вызвать регрессию в других.
• Перегрузка контекста: при сложных запросах модель смешивает предметные области — например, одновременно ищет таблицы, пишет код и цитирует документацию.
• Избыточность: агенту, генерирующему SQL, не нужно знать, как форматировать ответ пользователю.

Решение — разнести функции по независимым агентам. Мы выбрали архитектуру Swarm (Рой) с помощью LangGraph. Каждый агент — эксперт в своей узкой области, с собственными промптами и инструментами. Они общаются между собой, передавая контекст и результаты, и декомпозируют сложные задачи на атомарные шаги.

Четыре агента-эксперта

• Support (Оркестратор): определяет интент пользователя, классифицирует запрос и координирует работу других агентов. Содержит общий промпт системы и управляет маршрутизацией.
• Data Search (Сыщик): ищет нужные витрины через RAG по каталогу данных. Объясняет, как работать с таблицей, но не имеет доступа к содержимому — только к метаданным. Если у пользователя нет прав, агент генерирует ссылку для запроса доступа через IDM.
• Doc Assistant (Библиотекарь): ищет ответы в технической документации — по SQL-диалектам, BI-сервисам, оркестраторам задач. Подсказывает синтаксис и даёт ссылки на источники.
• SQL Generator (Кодер): пишет корректный SQL. Знает проприетарный синтаксис, получает схемы таблиц, работает с партициями и умеет валидировать код по traceback’у.

Важно: подключение к хранилищу осуществляется через ограниченную сервисную роль. Агенты работают только с метаданными, а все действия логируются для аудита.

Агенты физически разделены — каждый в своём сервисе, доступ к ним через HTTP. Это даёт устойчивость, удобное развёртывание и возможность обновлять компоненты независимо. Хотя в компактных системах все агенты могут жить в одном сервисе.

Ключевые архитектурные решения

1. Анализ метаинформации: агент-кодер запрашивает схему таблицы перед генерацией SQL. Это обеспечивает точность — правильные имена колонок и типы данных.
2. Предварительная валидация: перед отправкой пользователю скрипт запускается в режиме validate. При ошибке traceback возвращается агенту для самокоррекции.
3. Делегирование при неизвестном синтаксисе: если функция неизвестна, агент-кодер передаёт запрос агенту документации. Тот находит справку и возвращает контекст, не прерывая цепочку выполнения.

Эти подходы увеличили долю успешных запросов более чем в два раза. Для стандартных SQL-диалектов часть проверок может быть избыточной, но в проприетарных средах они критичны.

Наблюдаемость: как отлаживать мультиагентную систему (Langfuse)

Анализировать логи в мультиагентной системе сложно — сообщения смешиваются, теряется контекст. Мы выбрали Langfuse с self-hosted развёртыванием: не делимся данными с внешними облаками и получаем удобный интерфейс для аналитики.

Каждый запрос пользователя — отдельный трейс. В нём видно:

• историю сообщений,
• вызовы инструментов,
• тайминги,
• логику передачи управления между агентами.

Это помогло решить реальные проблемы:

• Работа с партициями: мы улучшили инструмент разведки — теперь агент анализирует соседние партиции и использует конструкцию RANGE() для временных срезов. Это резко повысило качество скриптов по историческим данным.
• Нарушение маршрутизации: агент документации иногда перехватывал управление и сам отвечал пользователю. Мы добавили строгое правило — возвращать информацию и передавать управление обратно. Ошибки маршрутизации исчезли.

Пример работы: сквозной сценарий

Запрос: «Где лежат логи нашего тестового стенда (sandbox) и напиши скрипт для подсчёта количества ошибок 404 за январь»

1. Оркестратор (Support): определяет, что нужны и данные, и код. Передаёт контекст агенту Data Search.
2. Data Search: находит путь //sandbox/test_env/logs/1d и схему таблицы. Передаёт задачу SQL Generator.
3. SQL Generator — разведка: вызывает explore_path_structure, получает список партиций за январь 2026 и рекомендацию использовать функцию чтения партиций.
4. Генерация и ошибка: агент пишет запрос с функцией RANGE, но валидация возвращает ошибку: «Unknown builtin: RANGE. Use FROM RANGE(_) instead».
5. Самокоррекция: агент исправляет синтаксис, повторно валидирует — на этот раз успешно.
6. Финальный ответ: пользователь получает готовый скрипт и ссылку на успешную проверку в тестовом кластере.

Итоги и планы

Мы создали масштабируемую систему, где каждый агент — независимый модуль. Можно обновлять промпты, добавлять инструменты и дебажить отдельные части, не нарушая общую логику.

Сейчас мы работаем над следующим шагом: научить агентов запускать тяжёлые скрипты в фоне и возвращать не код, а готовые дашборды и графики с результатами.

Наша реализация — не шаблон для копирования, но опыт с LangGraph, валидацией и наблюдаемостью может быть полезен при создании ИИ-систем в закрытых корпоративных средах.

Привет, Хабр! Меня зовут Максим Шакуров, я ML-инженер в VK.

Сегодня индустрия активно внедряет LLM для оптимизации рабочих процессов. Наша команда решила идти не от самой технологии, а от реальных потребностей. Чтобы найти процессы с наибольшим потенциалом для автоматизации, мы начали с аудита текущей рутины: проанализировали, с какими запросами аналитики и менеджеры приходят в чаты поддержки к инженерам Data Office (специалистам, отвечающим за сбор, хранение и миграцию корпоративных данных) и к разработчикам нашей платформы данных (команде, которая поддерживает и дорабатывает DWH). Оказалось, что львиная доля типовых запросов сводится к трём категориям:

Из этих категорий логично выросли три ключевые функции нашего будущего бота:

• Поиск нужных данных среди тысяч витрин.
• Генерация валидного SQL и ClickHouse-кода под задачу пользователя.
• Ответы по внутренней документации.

Отсюда сложился образ нашей будущей системы: она помогает ориентироваться в каталоге витрин, может рассказать, что и где хранится, помогает заполнить заявку на доступы, отвечает на вопросы по специфической документации и пишет скрипты, которые люди могут сразу забрать к себе в ETL-процессы.

Чтобы обозначить ценность получившегося решения, приведу числа за февраль 2026 года: нашей новой системой воспользовался 731 сотрудник, при этом Retention составил 68% (499 человек вернулись). По нашим оценкам, это ежедневно экономит десятки часов чистого времени специалистов. Статистика показывает, что инструмент помог снизить нагрузку по типовым запросам сотрудников компании.

В этой статье я расскажу, как мы реализовали такого помощника, перейдя от классического RAG к роевой архитектуре ИИ-агентов. Этот материал будет полезен разработчикам и менеджерам, которым нужно запустить масштабируемую ИИ-систему в закрытом контуре компании для работы с проприетарными данными. Я покажу, какой путь мы прошли, с какими архитектурными вызовами столкнулись и как вы можете адаптировать этот опыт для своего проекта.

Архитектура: почему рой, а не обычный RAG?

С проблематикой и верхнеуровневым представлением мы определились, далее перед нами встал вопрос реализации. Первая мысль: сделать очередного RAG-бота и в его базу загрузить всю доступную информацию. В качестве эксперимента мы действительно попробовали реализовать классический подход, но на практике столкнулись с рядом существенных ограничений.Для начала краткая сводка, как устроен RAG.Мы взяли:

• Redis в качестве векторного хранилища;
• BERT — в качестве эмбеддера (превращение текста в вектора);
• bge-m3 — в качестве реранкера (сортирует топ N ответов из БД по релевантности);
• LLM с поддержкой tool calling — в качестве генератора итоговых ответов и вызова внешних инструментов.

Парсим нашу базу знаний и загружаем её в Redis, предварительно превратив каждый чанк в эмбеддинг. Когда пользователь задаёт вопрос, идём в Redis по расстоянию l2 и находим в базе знаний 50 актуальных кусочков. При помощи реранкера сортируем эти 50 кусочков по релевантности (так как расстояние l2 даёт только приблизительное, неточное понимание релевантности данных и запроса). Выбираем 15 актуальных кусочков и собираем промт для модели: ЗНАНИЯ + ЗАПРОС ПОЛЬЗОВАТЕЛЯ.

Сложность масштабируемости.Из единого решения трудно вычленить отдельные логические цепочки, чтобы доработать их изолированно. Внося изменения в один блок, мы не можем гарантировать, что это не вызовет регрессию в остальных частях системы.

Снижение точности маршрутизации и генерации.Если один ИИ-агент получает комплексный запрос (например:«Найди мне таблицу X, напиши скрипт для получения колонок по условию Y и расскажи про синтаксис использованных функций»), то возникает перегрузка контекстом. Пытаясь одновременно искать данные, генерировать код и обращаться к документации, модель начинает смешивать эти предметные области. В результате страдает предсказуемость: повышается вероятность генерации синтаксически неверных функций или выбора нерелевантных таблиц

Избыточность контекста.При генерации скрипта агенту совершенно не обязательно знать логику форматирования итогового ответа. Аналогично, для поиска нужной таблицы в DWH не требуется понимание синтаксиса SQL-запросов. Объединяя все инструкции в единый системный промпт, мы неизбежно перегружаем контекстное окно модели лишним шумом, что напрямую снижает качество конечной генерации.

Стало понятно: нужно разнести функциональность и промпты по разным сущностям. Заставить их взаимодействовать друг с другом, декомпозируя и делегируя выполнение частей комплексной задачи.

Здесь на помощь приходит LangGraph, который имеет несколько заранее реализованных архитектур для создания мультиагентных систем. Из всего многообразия подходов мы остановились на паттернеSwarm (Рой).

В отличие от жёстких иерархических структур (Supervisor-паттерн), Swarm представляет собой сеть узлов, где каждый агент — это независимый эксперт в своей узкой предметной области. У него есть собственный набор системных промптов агентов и набор инструментов. Агенты общаются между собой внутри системы, передавая контекст задачи и результаты выполнения, декомпозируя сложный запрос на атомарные шаги

Знакомство с командой: четыре агента-эксперта

• Support (Оркестратор).Его главная цель — определить намерения пользователя, правильно скоординировать и декомпозировать запрос. Оркестратор классифицирует запрос пользователя и определяет сценарий. Содержит в себе большой промпт, описывающий общее поведение системы и пути взаимодействия всех агентов
• Data Search (Сыщик).Главная цель агента — найти путь к нужной витрине через RAG по корпоративному каталогу данных, и объяснить пользователю, как правильно с ней работать. Агент раскрывает бизнес-смысл найденных сущностей и подсказывает, как именно эти данные применимы к задаче. При этом важно отметить: он оперирует исключительно метаданными (схемами и описаниями полей), не имея доступа к самому содержимому таблиц.Фича с доступами.Система строго соблюдает внутренние политики безопасности. Если найденная таблица находится в директории, на доступ к которой у сотрудника нет прав, то агент не раскрывает конфиденциальную информацию. Вместо этого он выдаёт точный путь к ресурсу и генерирует готовую ссылку с инструкцией для легитимного запроса доступов через внутреннюю систему управления правами (IDM).
• Doc Assistant (Библиотекарь).Его главная цель — поиск ответов в массиве технической документации. Агент реализует RAG-подход по базе знаний, которая объединяет инструкции по SQL-диалектам платформы, BI-сервисам, системе оркестрации задач и другим инфраструктурным инструментам. Помогает разобраться в нюансах работы движков, подсказывает корректный синтаксис функций и предоставляет прямые ссылки на соответствующие разделы документации.
• QL generator (Кодер).Его главная цель — написать корректный SQL-запрос. Агент знает проприетарный синтаксис наших БД, умеет получать схему нужной таблицы, ориентироваться во вложенности данных и определять, как именно надо обращаться к хранилищу (к конкретной таблице или диапазону партиций). Также он умеет программно валидировать свой код и исправлять ошибки по traceback’у.

Важный нюанс безопасности:подключение агента к хранилищу для разведки схем и валидации кода осуществляется строго через ограниченную сервисную роль (service account). Агент работает только с метаданными, а все его действия и сгенерированные скрипты сохраняются для прозрачного аудита.

В нашей реализации агенты физически разделены: каждый работает в отдельном сервисе, а Swarm обращается к ним по HTTP. Это дало нам дополнительную устойчивость, более удобное развёртывание и возможность обновлять отдельные части системы без остановки всей мультиагентной цепочки. При этом такой уровень разделения не обязателен: в более компактной реализации оркестратор и агенты вполне могут жить в одном сервисе.Теперь самое интересное: рассмотрим, как агенты связаны и какие инструменты им доступны.

Расскажу про несколько архитектурных решений, которые мы используем для повышения качества генерирования кода:

1. Анализ метаинформации таблиц.Если ваша платформа позволяет получать метаданные SQL- или NoSQL-таблиц, то стоит реализовать отдельный инструмент для агента. В момент генерирования запроса агент обращается к пути расположения данных, проверяет физическое существование таблиц и считывает их схему. Это даёт модели точный контекст для написания корректного скрипта с правильными именами колонок и типами данных.
2. Предварительная валидация скриптов.Перед тем как отдать готовый код пользователю, мы программно запускаем его в базе в режимеvalidate(аналог Dry Run). Если возникает синтаксическая или логическая ошибка, то traceback вместе с исходным кодом автоматически возвращается агенту-генератору для самокоррекции.
3. Делегирование при неизвестном синтаксисе.Если агент-кодер сталкивается со специфической функцией, которая не поддерживается нашей внутренней платформой, то он передаёт управление агенту документации. Вызов сопровождается чётким системным указанием: найти справку по конкретной функции и вернуть контекст обратно агенту написания скриптов для завершения задачи.

Внедрение этих подходов позволило повысить долю успешно сгенерированных запросов к БД более чем в два раза. Если вы используете стандартный и широко известный SQL-диалект без специфических внутренних модификаций, то часть этих проверок может оказаться избыточной.

Observability: как не сойти с ума при дебаге (Langfuse)

Неизбежно наступает момент, когда нужно анализировать работу системы в проде. Искать причины галлюцинаций в сухих текстовых логах бэкенда — занятие мучительное. Логи разных вызовов смешиваются, а понять контекст общения агентов между собой практически невозможно.

Существует много готовых решений для трассировки LLM-приложений (LangSmith, Langfuse и др.). Мы остановились на Langfuse. Его главное преимущество для нас — возможность развернуть self-hosted версию на серверах компании. Мы не делимся конфиденциальными трейсами со сторонними облаками и при этом из коробки получаем понятный интерфейс для аналитики.

У нас логируется каждый шаг: для любого запроса пользователя создается отдельный трейс, где видно всю историю сообщений, тайминги, отработавшие инструменты и, главное, логику передачи управления между агентами.Как это выглядит: у нас есть вызовы на каждый запрос пользователя, каждый трейс можно открыть и посмотреть на историю сообщений пользователя, то как отработал каждый из доступных инструментов и как агенты общались друг с другом.

Такая прозрачность позволяет нам быстро находить системные ошибки. Приведу пару примеров из практики.

Адаптация логики работы с партиционированными данными.В процессе эксплуатации системы мы выявили специфические сценарии, требующие более тонкой настройки агента SQL-генератора. В нашем хранилище логи записываются по путям с датами (например,../1d/07-01-2026, ../1d/08-01-2026и т. д.). Чтобы модель лучше ориентировалась во временных интервалах, мы доработали инструмент сканирования путей. Теперь если переданный путь похож на партицию, то агент автоматически анализирует соседние таблицы. Это даёт ему полный контекст для того, чтобы считывать нужный срез через конструкцию RANGE(). Такое расширение алгоритма кардинально улучшило качество генерирования скриптов для работы с историческими данными.

Нарушение маршрутизации (перехват управления).Пользователи жаловались, что иногда вместо готового скрипта система выдавала просто выдержку из документации с абстрактными примерами функций. Анализ трейсов показал причину: когда агент-кодер запрашивал у агента документации справку по неизвестной функции, то последний перехватывал контекст и сам формировал финальный ответ пользователю. Мы скорректировали системные промпты, добавив строгое правило: агент документации должен возвращать найденную информацию и обязательно передавать управление обратно агенту-кодеру. Эта небольшая правка свела к нулю случаи некорректной маршрутизации.

Боевой пример (сквозной сценарий)

Чтобы закрепить понимание архитектуры, давайте на примере тестовой среды посмотрим, как наша система шаг за шагом обрабатывает комплексный запрос пользователя.

Запрос пользователя:«Где лежат логи нашего тестового стенда (sandbox) и напиши скрипт для подсчёта количества ошибок 404 за январь»

1. Оркестрация (Support Agent).Анализирует интент и понимает, что пользователю нужны как метаданные, так и готовый код. Передаёт базовый контекст агенту DataSearch.
2. Поиск таблиц (Data Search Agent).Вызывает инструментfind_tables. Получает путь к директории в песочнице (например,//sandbox/test_env/logs/1d) и актуальную схему колонок. Формирует подробное ТЗ и передаёт управление агенту-кодеру (SQL generator Agent).
3. Разведка (SQL generator Agent.Получает задачу и вызывает инструментexplore_path_structure, чтобы изучить физическое расположение тестовых данных перед написанием запроса. Инструмент возвращает контекст:{"type": "directory", "found_partitions": ["2026-01-01", ... "2026-01-31"], "suggestion": "USE_PARTITION_READ_FUNCTION"}.
4. Генерация и ошибка валидации.Агент пишет первую версию SQL-кода и прогоняет его через инструментvalidate_query. Движок базы данных возвращает синтаксическую ошибку:"validation_error": "Unknown builtin: RANGE. Consider using FROM RANGE(_) function(s) instead."
5. Самокоррекция.Агент-кодер анализирует полученный traceback, исправляет синтаксис вызова функции для чтения партиций и повторно вызываетvalidate_query. На этот раз ответ базы успешен:{"status": "success", "message": "Query validation passed", "job_url": "https://dwh.internal/test_queries/d561..."}
6. Финальный ответ.SWARM возвращает пользователю готовый, проверенный скрипт и ссылку на успешную валидацию на выделенном тестовом кластере.

Вот так этот конвейер можно представить в виде диаграммы:

Итоги и планы на будущее

В результате мы получили масштабируемую систему, в которой каждый агент — это независимый модуль. Мы можем дебажить, усложнять промпты и добавлять новые инструменты отдельным специалистам нашей архитектуры, не ломая общую логику маршрутизации.

Мы находимся в активной фазе доработки. В ближайших планах — научить агентов выполнять тяжёлые скрипты в фоне и отдавать пользователю не просто код, а готовые дашборды и графики по результатам выполнения.

Я не призываю вас слепо копировать текущую реализацию, но надеюсь, что наш опыт с LangGraph и подход к валидации кода будет полезен при проектировании ваших умных систем. Призываю в комментариях делиться вашим опытом и вопросами — возможно, именно ваши идеи помогут нам внедрить новые крутые подходы!