Архитектура
Трёхуровневая архитектура Crawbl разделяет зоны ответственности и позволяет независимо масштабировать каждый слой. Эта страница — единый справочник по тому, как устроена платформа, как через неё проходят запросы и какие технологии лежат в основе каждого уровня.
Как работает Crawbl
Пользователь задаёт вопрос
Пользователь отправляет запрос через любой клиент: мобильное приложение, REST API или WebSocket-соединение.
Crawbl координирует работу
Уровень оркестрации получает запрос и определяет, что нужно сделать: маршрутизация, проверка разрешений, управление доступом к провайдерам.
Агенты работают изолированно
AI-задачи выполняются в изолированных runtime-контейнерах. У каждого пользователя есть свой Agent Runtime — не общий процесс на всех.
Изоляция обеспечивает масштабируемость и контроль.
Результаты возвращаются чётко
Результаты приходят в виде ответов, предложений или запросов на подтверждение. Пользователь видит итог, а не детали реализации.
- Обычный чат-бот отвечает один раз. Crawbl продолжает работать после первого ответа.
- Один запрос может превратиться в цепочку действий, проверок подтверждений, сохранённого контекста и фоновой работы.
- Это разница между инструментом, который говорит, и инструментом, который помогает довести дело до конца.
Обзор трёх уровней
Уровень 1: Клиентский интерфейс
Пользовательский уровень предоставляет несколько точек доступа:
| Интерфейс | Назначение |
|---|---|
| Мобильное приложение | Основной пользовательский интерфейс (Flutter) |
| REST API | Синхронные операции, CRUD-действия |
| WebSocket | События в реальном времени, потоковые ответы |
Все клиенты работают с одним бэкендом — нет отдельного бэкенда для мобильного приложения и отдельного для API. Когда ты добавляешь возможность в оркестратор, её получают все клиенты. У платформы единая граница безопасности на уровне API.
Весь клиентский трафик проходит через уровень оркестрации. Runtime-среды никогда не доступны напрямую снаружи.
Уровень 2: Уровень оркестрации
Средний уровень — это Go-сервис, называемый оркестратором. Если в документации встречается термин "control plane" — это именно он: центральный бэкенд, координирующий всю остальную систему.
Аутентификация и авторизация
- Проверка JWT-идентификации для пользователей мобильного приложения
- Программный доступ через API-ключи
- Разрешения в рамках рабочего пространства
Маршрутизация запросов
- Направляет запросы к нужному Agent Runtime
- Балансирует нагрузку между runtime-средами
- Обрабатывает отказы и восстановление
LLM-медиация
- Выбор провайдера (Anthropic, OpenAI, Google и др.)
- Контроль затрат и отслеживание использования
- Rate limiting и управление квотами
Integration Hub
- Управление OAuth-токенами для внешних сервисов
- Учётные данные хранятся в сервисе управляемых секретов
- Обработка webhook-ов для внешних событий
Аудит и соответствие требованиям
- Полное логирование запросов
- Проверка прав доступа
- Возможности формирования отчётов о соответствии
Оркестратор взаимодействует с Agent Runtime через внутренний HTTP и никогда не открывает их в публичный интернет. Публичный трафик заканчивается на уровне ingress, а оркестратор находит нужный runtime через внутреннюю сеть кластера.
Уровень 3: Runtime-уровень
Нижний уровень — это место, где реально работают AI-агенты. Каждый пользователь получает изолированный контейнер Agent Runtime — один небольшой runtime на пользователя с собственной памятью и хранилищем, а не один огромный общий процесс для всех.
| Свойство | Реализация |
|---|---|
| Изоляция | Общее runtime-пространство с ClusterIP-сервисами для каждого swarm, изолированными через backend-медиацию |
| Безопасность | Нет прямого доступа в интернет, всё через оркестратор |
| Состояние | Постоянные тома для данных рабочего пространства |
| Масштабирование | Горизонтальное автомасштабирование подов по запросу |
| Восстановление | Автоматический перезапуск при сбое, состояние сохраняется |
Вспомогательная инфраструктура:
- PostgreSQL для данных всей платформы (пользователи, рабочие пространства, беседы)
- Redis для fan-out событий в реальном времени (Socket.IO pub/sub, индикаторы набора текста, новые сообщения)
Runtime-уровень масштабируется независимо от уровня оркестрации. Всплеск активных агентов не требует расширения ресурсов оркестратора, и каждый runtime-под достаточно мал, чтобы сотни из них поместились на скромном кластере.
Паттерны взаимодействия
Поток запросов
Вызов инструментов
Когда агенту нужно использовать внешний инструмент:
- Agent Runtime отправляет запрос на инструмент оркестратору через MCP
- Оркестратор проверяет разрешения и выполняет инструмент против внешнего сервиса
- Результат возвращается в Agent Runtime для контекста
Такая медиация гарантирует, что все внешние вызовы логируются и доступны для аудита, разрешения пользователей применяются в единой точке, а секреты никогда не покидают control plane.
Почему это разделение важно
Изоляция безопасности
Поды агентов никогда не обращаются в интернет напрямую. Оркестратор опосредует всё, поэтому ты можешь проверять и контролировать весь внешний доступ в одном месте.
Независимое масштабирование
Control plane и runtime-уровень масштабируются по отдельности. Всплеск активных агентов не требует расширения ресурсов оркестратора.
Гибкость клиентов
Новые интерфейсы — Slack-бот, расширение VS Code, CLI — должны лишь обращаться к API оркестратора. Изменения на уровне runtime не нужны.
Переносимость между облаками
Runtime-уровень — это чистый Kubernetes. Смена облачного провайдера означает изменение конфигурации кластера, а не переписывание логики агентов.
- Приложению нужно только собрать запрос и показать результат.
- Платформа берёт на себя сложные части: маршрутизацию работы, проверку подтверждений и хранение состояния.
- Это упрощает продукт и делает платформу проще в развитии со временем.
Технологический стек
Уровень оркестрации (Control Plane)
| Компонент | Технология | Назначение |
|---|---|---|
| Язык | Go 1.25+ | Высокая производительность, строгая типизация, отличная работа с конкурентностью |
| Фреймворк | Кастомный движок оркестрации | Плагинная архитектура для расширяемости |
| API | REST + WebSocket | Полноценная аутентификация, события в реальном времени |
| Инфраструктура | Kubernetes + Infrastructure as Code | Облачно-независимые провизионирование и оркестрация |
| GitOps | Непрерывное развёртывание через GitOps | Декларативное управление, автоматические обновления |
Runtime-уровень (Data Plane)
| Компонент | Технология | Назначение |
|---|---|---|
| Agent Runtime | Crawbl Agent Runtime (Go + ADK-Go) | Мультиагентное выполнение, gRPC-сервер на порту 42618 |
| Изоляция | Общее runtime-пространство, ClusterIP-сервисы для каждого swarm | Границы безопасности на уровне пода через backend-медиацию |
| Масштабирование | HPA | Горизонтальное автомасштабирование подов по нагрузке |
| Хранилище | Постоянные тома | Состояние runtime и персистентность рабочего пространства |
Вспомогательная инфраструктура
| Сервис | Технология | Назначение |
|---|---|---|
| База данных | PostgreSQL | Метаданные платформы и пользовательские данные |
| Кеширование | Redis | Обработка событий в реальном времени, управление сессиями |
| Обмен сообщениями | Socket.IO | Взаимодействие между компонентами в реальном времени |
| Секреты | Сервис управляемых секретов | Управление учётными данными с автоматической синхронизацией |
| Наблюдаемость | Логирование + мониторинг | Полноценная трассировка и оповещения |
Обоснование технологических решений
Почему Go для оркестратора?
- Компилируемый, эффективный, с низкой задержкой
- Горутины обрабатывают тысячи одновременных соединений
- Строгая типизация выявляет ошибки на этапе компиляции
- Развёртывание одним бинарником, быстрый старт
Почему Go для Agent Runtime?
- Distroless-образ ~26 МБ; сотни подов умещаются на скромном кластере
- ADK-Go предоставляет мультиагентный граф и модель делегирования SubAgent
- gRPC bidirectional streaming между оркестратором и runtime со строгой типизацией
- Один бинарник, быстрый старт, никакого интерпретатора или VM
Почему Kubernetes?
- Namespace-ы обеспечивают границы безопасности для каждого тенанта
- Встроенное автомасштабирование и балансировка нагрузки
- Работает в любом облаке или on-premises
- Зрелый инструментарий для GitOps, управления секретами и наблюдаемости