Внутри CAMEL: глубокий анализ архитектуры мультиагентного фреймворка

Аннотация

Что происходит, когда статью с NeurIPS 2023 о том, как заставить ИИ-агентов общаться друг с другом, превращают в продакшн-фреймворк? Получается CAMEL — одна из самых амбициозных открытых систем мультиагентной оркестрации на сегодняшний день. Мы взяли всю кодовую базу CAMEL и поместили её под микроскоп с помощью Code Indexer [6] — автоматизированного движка статического анализа, который разобрал каждую функцию, проследил каждую цепочку вызовов и оценил каждый паттерн безопасности в 1 122 Python-файлах. Результат — портрет фреймворка, который значительно перерос свои академические корни — со всеми вытекающими плюсами и минусами.

Почему это важно

Мультиагентные системы — следующий рубеж в разработке ИИ-приложений. Вместо одного монолитного ИИ, который делает всё, работа распределяется между специализированными агентами: один планирует, другой пишет код, третий проверяет, четвёртый деплоит. CAMEL [1] был одним из первых фреймворков, формализовавших эту идею, и проекты вроде MiroFish [7] — симулятора роевого интеллекта, который мы недавно анализировали — уже строят свою агентную инфраструктуру на примитивах CAMEL. Понимание архитектуры такого фундаментального фреймворка — не просто академическое упражнение: оно напрямую влияет на каждую систему, построенную на его основе.

Методология анализа

Мы проиндексировали весь репозиторий CAMEL с помощью Code Indexer [6], получив 12 376 семантических чанков и 65 576 рёбер перекрёстных ссылок. Конвейер анализа включал: извлечение символов на уровне AST (8 371 символ), вычисление цикломатической сложности, автоматическую классификацию модулей, семантический поиск уязвимостей на основе эмбеддингов, анализ потоков данных (taint analysis), вычисление радиуса поражения для обнаруженных уязвимостей, анализ связности изменений по истории git и оценку когезии файлов. Полный глубокий аудит выполнился менее чем за 3 минуты — такой масштаб структурного анализа был бы непрактичен для ручной проверки.

Ключевые метрики

Распределение языков

CAMEL — преимущественно Python-проект, но его инструментарий для автоматизации браузера вносит значительный TypeScript/JavaScript-компонент. 138 Markdown-файлов отражают немалый (но всё ещё недостаточный) объём документации, а JSON- и YAML-конфигурации поддерживают обширную поверхность интеграций фреймворка.

Архитектура: три столпа

Автоматический классификатор модулей распределил 576 файлов по функциональным категориям, выявив архитектуру с доминированием моделей. Движок аналитических инсайтов аудита зафиксировал два структурных паттерна: отсутствие слоя репозиториев (146 моделей при 5 сервисах) и признаки «анемичной доменной модели» — когда бизнес-логика находится вне классов моделей. Это не баги — это проектные решения, типичные для исследовательских фреймворков, приоритизирующих скорость экспериментов над корпоративными паттернами.

graph TD
    subgraph Agent["Слой агентов"]
        CA["ChatAgent"]
        MCP_A["MCPAgent"]
        KA["KnowledgeAgent"]
        CA --> MCP_A
        CA --> KA
    end
    subgraph Society["Слой общества"]
        RP["RolePlaying"]
        WF["Workforce"]
        COORD["Координатор"]
        PLAN["Планировщик"]
        DYN["Динамические воркеры"]
        WF --> COORD
        WF --> PLAN
        WF --> DYN
    end
    subgraph Infra["Инфраструктура"]
        MF["ModelFactory"]
        MEM["Дуальная память"]
        TK["50+ тулкитов"]
        RET["Ретриверы"]
    end
    CA --> RP
    CA --> WF
    CA --> MF
    CA --> MEM
    CA --> TK
    CA --> RET

Ядро: ChatAgent под капотом

Всё в CAMEL начинается с ChatAgent — класса из 144 символов, который управляет системными сообщениями, памятью, регистрацией инструментов, стримингом ответов и мультимодальной обработкой. Метрики сложности рассказывают историю: метод _aprocess_stream_chunks_with_accumulator набрал 5 713 по шкале цикломатической сложности. Для контекста: большинство стандартов разработки считают функции со сложностью выше 10 кандидатами на рефакторинг. Этот единственный метод обрабатывает накопление стриминговых ответов, обнаружение вызовов инструментов, маршрутизацию мультимодального контента и восстановление после ошибок — всё во вложенных условных ветвях.

Это не баг — это цена создания универсальной абстракции агента. ChatAgent должен обслуживать все модельные бэкенды, все интеграции инструментов, все варианты стриминговых протоколов. Подкласс MCPAgent добавляет сверху управление жизненным циклом MCP-серверов. Система регистрации инструментов использует механизм глубокого клонирования (_clone_tools), обеспечивающий параллельные экземпляры агентов без общего мутабельного состояния.

Слой общества: как агенты работают вместе

Слой общества реализует два режима оркестрации. RolePlaying — ближе к оригинальной статье NeurIPS [1] — создаёт пару агентов ("ассистент" и "пользователь"), которые ведут поочерёдный диалог до решения задачи. Опциональный агент-критик оценивает качество обмена.

Workforce — более амбициозный модуль на 6 000+ строк иерархической декомпозиции задач. Три внутренних агента: Координатор маршрутизирует задачи по возможностям воркеров, Планировщик рекурсивно разбивает сложные задачи на подзадачи, и при неудаче система динамически создаёт новых специализированных воркеров. Метод _listen_to_channel (сложность 5 207) управляет всей шиной межагентных сообщений. Анализ связности изменений показал: workforce.py совместно изменяется с context_utils.py в 71,4% случаев — 7 из 10 патчей оркестратора требуют изменений и в управлении контекстом.

40+ LLM-бэкендов: ModelFactory

ModelFactory — одна из самых практичных фич CAMEL. Реестр связывает идентификаторы платформ с реализациями бэкендов. Чтобы переключиться с OpenAI на Anthropic или с облачного API на локальный vLLM — достаточно поменять одно значение enum. Фабрика поддерживает более 40 провайдеров.

Память: запоминая важное

Как дать ИИ-агенту память? Ответ CAMEL — вести два вида. ChatHistoryBlock даёт доступ к недавним сообщениям через скользящее окно с настраиваемым параметром keep_rate (по умолчанию 0.9). VectorDBBlock хранит эмбеддинги сообщений в Qdrant и извлекает по семантическому сходству. Оба блока работают через единый ScoreBasedContextCreator, который вписывает наиболее релевантные фрагменты в лимит токенов модели.

Для RAG по внешним документам доступны три ретривера: VectorRetriever (семантический поиск), BM25Retriever (ключевые слова) и HybridRetriever, объединяющий оба через Reciprocal Rank Fusion (RRF) — тот же алгоритм, что используется в Elasticsearch. Параметры фьюжна (vector_weight, bm25_weight, rank_smoothing_factor) настраиваемы.

graph LR
    subgraph Memory["Память агента"]
        CHB["ChatHistoryBlock\nПо давности"]
        VDB["VectorDBBlock\nПо семантике"]
    end
    subgraph Retrieval["Поиск по документам"]
        VR["VectorRetriever"]
        BM["BM25Retriever"]
        HR["HybridRetriever\nRRF-фьюжн"]
        VR --> HR
        BM --> HR
    end
    CHB --> CTX["ScoreBasedContextCreator"]
    VDB --> CTX
    CTX --> CA2["ChatAgent"]
    HR --> CA2

Глубокий аудит: что говорят числа

Глубокий аудит оценил CAMEL в 32 из 100 баллов — звучит тревожно, но требует контекста. Оценка вычисляется автоматическими эвристиками единообразно. Исследовательский фреймворк с 230 зависимостями, обширным тестовым каркасом и экспериментальным кодом неизбежно набирает ниже, чем фокусированный продакшн-микросервис. Тем не менее, разбивка по категориям выявляет как ожидаемые компромиссы, так и реальные проблемы.

Поверхность атаки: анализ радиуса поражения

Taint-анализ — отслеживание потоков данных от недоверенных источников к чувствительным приёмникам — обнаружил 7 критических паттернов. Вычисление радиуса поражения показало, сколько функций может пострадать при эксплуатации уязвимости. Самый масштабный: метод query() в OceanBase vector storage достижим из 50 вызывающих сторон. InternalPythonInterpreter._execute_ast — отмечен из 11 вызывающих, хотя это умышленная функция (песочница для выполнения кода).

Горячие точки сложности

Анализ сложности рисует яркую картину концентрации когнитивной нагрузки. Три подсистемы доминируют: ядро ChatAgent (5 методов выше 3 000), оркестратор Workforce (4 метода выше 4 000) и TypeScript-слой браузерного тулкита (методы до 2 009). Для перспективы: общепринятый порог для «нужен рефакторинг» — сложность 10. Эти методы превышают его на порядки — не из-за плохого проектирования, а потому что реализуют подлинно сложные конечные автоматы.

Тулкиты и MCP: 50+ способов взаимодействия с миром

Подсистема тулкитов — витрина амбиций CAMEL. Свыше 50 интеграций: автоматизация браузера (Python + TypeScript), научные вычисления, коммуникационные платформы (Slack, Discord, Telegram, WeChat, DingTalk), поисковые движки (Google, DuckDuckGo, arXiv, Google Scholar), графовые БД (Neo4j, NetworkX), обработка документов и инфраструктурные инструменты (SQL, терминал, Docker).

CAMEL реализует двунаправленную поддержку MCP (Model Context Protocol): агенты могут подключаться к внешним MCP-серверам, и любой тулкит CAMEL можно развернуть как MCP-сервер. Это значит, что тулкиты CAMEL могут использоваться в Claude, Cursor или любой другой MCP-совместимой системе без изменения кода.

Реальное применение: MiroFish и не только

CAMEL — не просто исследовательский артефакт. В нашем недавнем анализе MiroFish [7] — симулятора роевого интеллекта, моделирующего мультиагентные общества на протяжении симулированных десятилетий — мы обнаружили, что проект построен непосредственно на примитивах CAMEL. MiroFish использует ChatAgent как фундамент для автономных агентов, задействуя системы памяти и интеграцию инструментов фреймворка для создания устойчивых агентных личностей, которые ведут переговоры, формируют альянсы и адаптируют стратегии на протяжении тысяч шагов симуляции.

Бенчмарки: измерение производительности агентов

Здоровье кода: картина технического долга

Документация покрывает лишь 201 из 5 000 символов (4%). В коде 49 закомментированных фрагментов, 43 TODO-комментария и 3 FIXME-маркера. Анализ когезии обнаружил антипаттерн «мусорная куча утилит»: commons.py содержит 37 функций с всего 2 внутрифайловыми вызовами (коэффициент когезии 0.023). Тестовое покрытие по файловой классификации — 31%. Оценка поддерживаемости 0/15 вызвана 9 дубликатами кода и 20 «файлами-богами». Гигиена 0/15 — 30 магических чисел и 14 обнаруженных секретов.

Выводы

CAMEL — фреймворк подлинных амбиций и реальных инженерных последствий. Оркестратор Workforce с методами, превышающими сложность 5 000, — одна из самых серьёзных open-source попыток создать иерархическую самовосстанавливающуюся декомпозицию задач. ModelFactory с 40+ бэкендами обеспечивает развёртывание на практически любой платформе. Двунаправленная поддержка MCP гарантирует совместимость с будущей экосистемой. Проекты вроде MiroFish [7] показывают, что эта архитектура уже поддерживает приложения далеко за рамками оригинального исследования.

Оценка 32/100 — это честное предупреждение, а не приговор. Она говорит: погружение в эту кодовую базу потребует терпения. Концентрация сложности означает, что любая модификация ядра затрагивает глубоко вложенные конечные автоматы. Низкое покрытие документацией означает, что придётся читать код, а не доки. 14 обнаруженных секретов означают, что конфигурацию нужно аудитировать перед деплоем.

Для команд, оценивающих CAMEL как фундамент мультиагентных приложений: фреймворк обеспечивает экстраординарную широту возможностей. Только заходите с открытыми глазами насчёт стоимости поддержки — и рассматривайте модуль Workforce как интересную, но сложную зависимость, которая заслуживает выделенного инженерного внимания, если вы строите на ней что-то критичное.