Наш опыт работы с клиентом, которому мы помогли превратить один большой AI-монорепозиторий в структурированную экосистему агентов, инструментов и регистров.
Всем здравствуйте! Меня зовут Mykhailo Kapustin, я Co-Founder & CTO трансатлантического холдинга компаний ASRP (Advanced Scientific Research Projects), AI & Blockchain энтузиаст. В работе над этой статьёй мне помогал Kyryl Zmiienko, Senior Artificial Intelligence Engineer (AI/ML) ASRP, чьи советы и техническое видение сыграли важную роль при формировании предложенных решений.
Недавно к ASRP обратился клиент, который за годы работы на немецком рынке разработал обширный набор внутренних инструментов — от библиотек для обработки PDF, изображений и данных до систем автоматизации и анализа. Сейчас его команда активно внедряет агентные технологии и стремится сделать эти инструменты доступными для агентов — чтобы те могли использовать их как модули, комбинировать между собой и самостоятельно строить новые цепочки действий без участия разработчиков.
Для оперативного старта клиент создал один большой монорепозиторий, в котором разместил и агентов, и инструменты. Такой подход позволял быстро развернуть среду, где агенты могли общаться между собой локально и использовать нужные тулзы прямо из соседних папок. При создании нового агента клиент просто копировал нужные инструменты в его директорию, адаптируя конфигурацию под задачу.
Для партнёров компания устанавливала этот софт локально, но в планах была масштабная SaaS-платформа с кастомным интерфейсом и централизованным управлением агентами.
Со временем стало ясно, что такой подход не масштабируется.
Не существовало единого стандарта или реестра инструментов, где можно было бы увидеть, какие инструменты уже реализованы и какие из них стоит подключить агенту.
Не было списка доступных агентов — каждый жил изолированно.
Процесс создания новых агентов требовал постоянного копирования кода, что засоряло репозиторий.
Отсутствовал контроль версий инструментов, из-за чего сложно было развивать и поддерживать их дальше.
После детального анализа исходных данных и структуры проекта я сформировал ряд рекомендаций по дальнейшему сопровождению и масштабированию системы, а также выделил три стратегические линии развития. При выборе архитектуры важно было учитывать специфику бизнеса клиента — необходимость локальных установок у партнёров, будущий переход к SaaS-модели и простоту поддержки без зависимости между агентами. Основная цель заключалась в том, чтобы создать такую инфраструктуру, где агенты и инструменты могли бы управляться централизованно, сохранив при этом гибкость, версионность и скорость внедрения.
📂 Пример структуры проекта
library/
├── tools/
│ ├── extract.pdf.py
│ ├── search.web.py
│ └── system.file.py
└── agents/
└── participant_researcher/
├── tools/
│ └── extract.pdf.py # локальная переопределённая версияТри архитектурные линии развития проекта:
Локальное файловое решение с ленивой загрузкой (lazy import) — лёгкий и быстрый путь к стабилизации существующего монорепозитория. Автоматический индекс инструментов и наличие ручного манифеста позволяют быстро внедрять обновления и подготовить систему к дальнейшему росту.
Пакетный менеджер и экосистема модульных тулзов — система управления зависимостями и версиями, которая обеспечивает гибкость и чистоту архитектуры без необходимости перехода к распределённой сети. Подходит компаниям, которым нужен порядок и контроль без тяжёлого DevOps-стека.
Инфраструктура уровня AgentOps (MCP & A2A) — агенты становятся распределённой сетью сервисов, взаимодействующих между собой по протоколам, с централизованным мониторингом, версионированием и безопасной оркестрацией. Это стратегическое enterprise-решение для компаний, нацеленных на масштаб и долгосрочную интеграцию.
Теперь, когда структура возможных решений определена, можно перейти к анализу их практической ценности: какие выгоды каждая из моделей даёт бизнесу, какие компромиссы она влечёт, и как выбрать оптимальный сценарий под конкретный уровень зрелости продукта.
Глобальный файловый реестр и “ленивая” загрузка инструментов
Если текущая цель проекта — собрать множество агентов и инструментов в одном репозитории и запускать их локально для решения прикладных задач (например, создавать составных агентов или выполнять пайплайны анализа).
Суть подхода: все инструменты хранятся централизованно в одной папке (например, library/tools), а при запуске система автоматически сканирует этот каталог и формирует индекс (например, tools_index.yaml) с описанием доступных тулзов — их путями, версиями и типами.
Можно начать с простой, но масштабируемой архитектуры:
project_root/
├── agents/
│ ├── researcher/
│ │ ├── main.py
│ │ └── config.yaml
│ └── summarizer/
│ └── main.py
├── tools/
│ ├── extract.pdf.py
│ ├── search.web.py
│ └── system.file.py
└── registries/
├── tool_registry.py
└── agent_registry.pyТакое разделение создаёт три слоя ответственности:
agents/ — логика поведения агентов (они оркестрируют задачи);
tools/ — атомарные действия (извлечение, поиск, преобразование данных);
registries/ — механизмы обнаружения, кэширования и загрузки.
Пример простого реестра инструментов
# registries/tool_registry.py
from pathlib import Path
import importlib.util, json
class ToolRegistry:
def __init__(self, path="tools", cache=".cache/tools_index.json"):
self.path = Path(path)
self.cache = Path(cache)
self.index = {}
def scan(self):
"""Автоматически ищет все файлы .py в каталоге tools"""
tools = {}
for file in self.path.glob("*.py"):
name = file.stem
tools[name] = {"file_path": str(file), "mtime": file.stat().st_mtime}
self.index = tools
self.cache.parent.mkdir(parents=True, exist_ok=True)
json.dump({"tools": tools}, open(self.cache, "w"), indent=2)
return tools
def load(self, tool_name):
"""Динамически загружает модуль по имени"""
entry = self.index.get(tool_name)
if not entry:
raise KeyError(f"Tool {tool_name} not found")
spec = importlib.util.spec_from_file_location(tool_name, entry["file_path"])
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return moduleТеперь агент может подключать только нужные инструменты:
from registries.tool_registry import ToolRegistry
registry = ToolRegistry()
registry.scan()
pdf_tool = registry.load("extract.pdf")
pdf_tool.run("document.pdf")Пример манифеста доступных инструментов:
tools:
extract.pdf:
tool_id: extract.pdf
version: 1.2.0
category: extraction
description: Extract structured data from PDF files
capabilities: ['read_fs', 'llm_call']
usage_guide: |
Use this tool for extraction operations.
Capabilities: read_fs, llm_callПример манифеста доступных агентов:
agents:
- id: web-researcher
name: web-researcher
description: ''
category: general
version: 1.0.0
tools: []Агенты обращаются к этому индексу и подгружают только те инструменты, которые им действительно нужны, что делает систему лёгкой и предсказуемой.
Такой подход не требует CI/CD, приватного npm-реестра или сложного окружения — всё работает «из коробки» и идеально подходит для локальных установок, пилотных проектов и изолированных сред, где десятки агентов могут сосуществовать в одном проекте.
Вы даже можете подключить LLM-агента, который сам обращается к реестру и принимает решение, каких субагентов или инструментов лучше подключить под задачу.
Например, агент-координатор анализирует запрос пользователя (“проанализируй PDF и подготовь сводку”) и через tools_registry определяет, что для этого нужны extract.pdf и summarize.text.
Такой подход превращает выбор инструментов из ручного процесса в интеллектуальное планирование — где сама модель управляет архитектурой выполнения.
Однако у него есть ограничения:
Контроль версий минимальный: обновление инструмента мгновенно влияет на всех агентов, а откат возможен только вручную.
Для небольших систем это не критично, но по мере роста проекту всё труднее сохранять стабильность.
Filesystem-registry — это зрелый компромисс: быстрый, прозрачный и понятный способ централизовать инструменты, который позволяет выиграть время и упорядочить код.
В будущем такой слой легко трансформируется в полноценный пакетный менеджер или AgentOps-инфраструктуру — без резких миграций и потери стабильности.
Пакетный менеджер и модульная экосистема тулзов
Каждый новый агент требует свой набор тулзов — кто-то работает с PDF, кто-то с API или изображениями — и в итоге все начинают дублировать одни и те же модули, вручную обновлять версии и следить, чтобы ничего не сломалось. Репозиторий постепенно разрастается, а любая правка в одном инструменте тянет за собой каскад проблем у других агентов.
Чтобы из хаоса перейти к порядку, инструменты нужно перестать рассматривать как «файлы внутри репозитория» и начать относиться к ним как к пакетам — самостоятельным модулям со своей версией, документацией и жизненным циклом.
Вместо бесконечного копирования можно вынести тулзы в отдельные доменные пакеты, например pdf-toolset, image-processing, data-analysis, и подключать их к агентам через корпоративный пакетный менеджер — по тому же принципу, как это делают разработчики с npm или PyPI.
Рядом с каждым агентом появляется конфигурационный файл — package.json или requirements.txt, — где указаны все зависимости проекта: нужные инструменты, SDK, модули и их версии.
Теперь агент при инициализации подтягивает нужные компоненты из внутреннего реестра пакетов компании. Код агента остаётся чистым — зависимости не попадают в Git, а список всегда прозрачен: любой разработчик видит, какие именно версии и инструменты используются.
На практике такой переход требует реальной инженерной работы.
Инструменты нужно вынести из монорепозитория, сгруппировать по доменам, развернуть внутренний реестр пакетов и автоматизировать процесс обновлений.
Кроме того, необходимо адаптировать самих агентов — научить их корректно работать с инструментами, которые теперь подключаются как внешние пакеты.
Это потребует обновления конфигураций, окружений и CI/CD-процессов, чтобы при запуске проекта зависимости подтягивались автоматически и в нужных версиях.
Это не “косметическая оптимизация”, а архитектурное изменение, требующее внимания к интеграции, тестированию и документации.
Но результат — качественный шаг вперёд.
Агенты становятся независимыми и предсказуемыми, инструменты получают контроль версий, а репозиторий — чистую, управляемую структуру.
С этого момента монолит перестаёт быть жёстким ограничением: агенты хранятся вместе лишь организационно, но технически уже могут быть вынесены в отдельные репозитории или даже развёрнуты как сервисы в A2A-сети.
Это естественный переходный этап от монолита к распределённой архитектуре — более доступный и дешёвый, чем полноценный AgentOps, но при этом создающий все необходимые предпосылки для него.
Для бизнеса это означает:
конец дублированию и ручному обновлению кода;
прозрачность зависимостей и контроль версий;
снижение риска непредсказуемых поломок;
и главное — архитектурную гибкость, позволяющую развивать проект поэтапно, без остановки разработки и потери стабильности.
Однако не всем бизнесам нужна столь глубокая перестройка прямо сейчас.
Иногда важно быстро навести порядок в существующем монолите, не вынося код во внешние пакеты.
Инфраструктура уровня AgentOps (MCP & A2A)
Если рассматривать развитие агентных систем стратегически, то наивысший уровень зрелости — это переход к инфраструктуре класса AgentOps, где агенты работают не как модули внутри одного монолита, а как автономные сервисы, которые общаются между собой, подключают инструменты и развиваются независимо.
Такой переход основан на двух ключевых технологиях: MCP (Model Context Protocol) и A2A (Agent-to-Agent communication).
MCP (Model Context Protocol) — это открытый стандарт, который позволяет языковым моделям (LLMs) и агентам подключаться к внешним источникам данных, инструментам и API. Он задаёт единый формат общения между агентом и инструментом: агент знает, какие функции доступны, как их вызывать и как получать результат.
Например, агент, отвечающий за анализ PDF-документов, может через MCP вызвать инструмент для извлечения текста, передать результат агенту, занимающемуся семантическим анализом, и далее агенту, который создаёт визуализацию — всё без ручных связей между модулями и без вмешательства разработчика.
A2A (Agent-to-Agent communication) — следующий уровень.
Если MCP позволяет агенту использовать инструменты, то A2A даёт возможность агентам взаимодействовать и сотрудничать друг с другом. Это значит, что один агент может делегировать задачу другому, выстраивать совместные цепочки действий и даже обращаться к агентам, написанным на других фреймворках.
Благодаря A2A становится возможна интеграция между компаниями и системами — ваш агент может использовать, например, внешнего финансового агента другой организации или сторонний модуль анализа изображений, просто указав ссылку и протокол взаимодействия.
Для клиента это открывает совершенно новые возможности:
Больше нет необходимости хранить всё в одном монолите. Репозиторий можно разделить на независимые компоненты — агенты, инструменты, библиотеки. Это уменьшает риск конфликтов, упрощает обновления и делает кодовую базу прозрачной.
Можно нанимать отдельные команды под конкретных агентов или направления бизнеса. Команда по работе с документами не мешает команде, развивающей аналитического агента или модули интеграции. Каждая часть продукта развивается автономно, но остаётся связанной общей архитектурой.
Легче внедрять версионность моделей и инструментов. Теперь можно фиксировать, какая версия модели используется в каждом агенте, откатываться на стабильные сборки и планово обновлять без риска “сломать” соседние модули.
Готовность к масштабированию. Система становится ближе к архитектуре микросервисов, где агенты можно разворачивать независимо, балансировать нагрузку и подключать новые компоненты без остановки других.
Да, это решение требует инвестиций: внедрение DevOps-практик, CI/CD-процессов, контейнеризации и систем оркестрации.
Но AgentOps — это инвестиция в устойчивость и управляемость, которая позволяет компании выстраивать не просто набор агентов, а внутреннюю интеллектуальную экосистему, где каждый агент знает, кто он, с кем может общаться и какие инструменты доступны в организации.
В долгосрочной перспективе это означает:
прозрачное масштабирование без зависимости от монолита;
лёгкую интеграцию с внешними сервисами и агентами других компаний;
независимое развитие команд и направлений без технического долга.
Таким образом, подход уровня AgentOps позволяет превратить набор разрозненных агентов и инструментов в управляемую экосистему, где каждый компонент взаимодействует с другими через открытые стандарты MCP и A2A.
Это архитектура, которая обеспечивает масштабируемость, изоляцию команд и контроль версий — но требует продуманной инфраструктуры и большего времени на внедрение.
Вывод
Любая экосистема агентов проходит три стадии:
Собственный файловый реестр - подойдет для MVP.
Контролируемый порядок — появляются пакеты, модули, реестры, версии, зависимости, для MLP.
Интеллектуальная инфраструктура (AgentOps) — где агенты становятся сервисами, способными взаимодействовать, масштабироваться и обучаться, для Enterprise.
AgentOps — это не модный термин, а естественный финал зрелости системы.
Это точка, в которой архитектура перестаёт быть ограничением, а становится преимуществом.
Компании, которые переходят к этому уровню, получают не просто управляемость кода — они создают основу для экосистемы ИИ, где агенты растут вместе с бизнесом.
