UNF86

DeerFlow 2.0 — разбор архитектуры

8 min read

DeerFlow 2.0 от ByteDance: разбираем архитектуру «суперагентского» фреймворка

Введение

DeerFlow (Deep Exploration and Efficient Research Flow) — open-source проект от ByteDance, который начинался как фреймворк для автоматизированного глубокого исследования (Deep Research), а во второй версии превратился в универсальную платформу для запуска AI-агентов. В феврале 2026 года DeerFlow 2.0 занял первое место в GitHub Trending — на момент написания статьи у проекта более 2000 коммитов и активное сообщество.

Ключевая идея: DeerFlow — это не библиотека, которую нужно собирать по кусочкам, а готовый «harness» (обвязка) для агентов. Из коробки он даёт агенту файловую систему, память, навыки, песочницу для выполнения кода и возможность порождать суб-агентов. Построен поверх LangGraph и LangChain.

Зачем переписали с нуля? Первая версия была заточена под research-сценарии. Но сообщество стало использовать DeerFlow для генерации слайдов, дашбордов, data-пайплайнов, контентных конвейеров. Стало ясно, что нужна не research-утилита, а универсальный runtime для агентов. Вторая версия не содержит общего кода с первой — это полная переработка архитектуры.

Архитектура

Общая схема

DeerFlow 2.0 состоит из трёх слоёв:

  1. Frontend — веб-интерфейс на Next.js для взаимодействия с агентами
  2. Gateway — API-сервер (FastAPI), который управляет тредами, аутентификацией, маршрутизацией запросов
  3. Harness — ядро системы: оркестрация агентов, инструменты, песочница, память

Lead Agent и оркестрация

В центре — Lead Agent (ведущий агент). Это LangGraph-граф с состоянием (ThreadState), который принимает запрос пользователя и решает, как его выполнить. У него четыре режима работы:

  • Flash — быстрый ответ без дополнительных шагов
  • Standard — стандартное выполнение с использованием инструментов
  • Pro (Plan Mode) — агент сначала составляет план (todo-лист), затем выполняет шаги последовательно
  • Ultra — с порождением суб-агентов для параллельного выполнения подзадач

Lead Agent создаётся через фабрику create_deerflow_agent(), которая принимает модель, инструменты, системный промпт и набор middleware. Важная деталь: сама фабрика не читает конфиг-файлы — это чистая функция, что упрощает тестирование и встраивание.

Суб-агенты

Для сложных задач Lead Agent порождает суб-агентов через SubagentExecutor. Каждый суб-агент:

  • Получает изолированный контекст — не видит историю основного агента и других суб-агентов
  • Имеет свой набор инструментов и условия завершения
  • Может работать параллельно с другими суб-агентами
  • Возвращает структурированный результат (SubagentResult) со статусом, текстом ответа, трейс-айди

Суб-агенты запускаются в отдельном ThreadPoolExecutor. Lead Agent синтезирует результаты всех суб-агентов в финальный ответ. Типичный сценарий: исследовательская задача раскладывается на 10-12 суб-агентов, каждый исследует свой аспект, затем результаты сводятся в один отчёт, презентацию или сайт.

Middleware-архитектура

Агенты оборачиваются цепочкой middleware:

  • DanglingToolCallMiddleware — восстанавливает сломанные последовательности tool-call, когда провайдер прерывает цикл
  • ClarificationMiddleware — позволяет агенту задать уточняющий вопрос пользователю
  • ToolErrorHandlingMiddleware — обработка ошибок инструментов
  • SummarizationMiddleware — сжатие контекста при длинных сессиях
  • GuardrailsMiddleware — проверка безопасности запросов и ответов

Это позволяет гибко настраивать поведение агента без изменения его основной логики.

Skills: навыки агентов

Что такое Skill

Skill (навык) в DeerFlow — это Markdown-файл (SKILL.md) с YAML-метаданными в начале. Он описывает методологию выполнения определённого типа задач: какие шаги делать, какие best practices соблюдать, на какие ресурсы опираться.

Проект поставляется с набором готовых навыков:

  • deep-research — систематическое исследование с многоуровневым поиском
  • ppt-generation — создание презентаций
  • web-design-guidelines — создание веб-страниц
  • image-generation — генерация изображений
  • data-analysis — анализ данных
  • podcast-generation — генерация подкастов
  • code-documentation — документирование кода
  • skill-creator — создание новых навыков (мета-навык)

Как это работает

Навыки хранятся в файловой системе:

/mnt/skills/public/         ← встроенные навыки
/mnt/skills/custom/         ← пользовательские навыки

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

Каждый SKILL.md парсится из YAML-фронтматтера: извлекаются name, description, опционально version, author, compatibility. Навыки можно устанавливать через Gateway как .skill-архивы. Есть security scanner для проверки сторонних навыков.

Инструменты (Tools)

Помимо навыков, агент имеет набор инструментов:

  • web_search — поиск в интернете (Tavily, InfoQuest от BytePlus и др.)
  • web_fetch — получение содержимого веб-страниц
  • file operations — чтение, запись, редактирование файлов
  • bash — выполнение shell-команд (в песочнице)
  • MCP-серверы — подключение внешних инструментов через Model Context Protocol

MCP-интеграция поддерживает HTTP/SSE-транспорт и OAuth-потоки (client_credentials, refresh_token).

Память и Context Engineering

Долгосрочная память

Большинство агентов забывают всё после завершения диалога. DeerFlow — нет. Система ведёт персистентную память между сессиями:

Структура памяти (файл memory.json):

  • user.workContext — рабочий контекст пользователя
  • user.personalContext — личный контекст
  • user.topOfMind — текущие приоритеты
  • history.recentMonths — саммари за последние месяцы
  • history.earlierContext — более ранний контекст
  • history.longTermBackground — долгосрочный фон
  • facts — массив фактов с confidence-скором (до 100 фактов, порог confidence ≥ 0.7)

Память хранится локально, per-user, с поддержкой per-agent хранилищ. Обновления происходят через debounce (по умолчанию 30 секунд) — LLM анализирует переписку и извлекает новые факты.

Хук суммаризации

Когда middleware суммаризации сжимает историю сообщений, перед удалением старых сообщений срабатывает memory_flush_hook — он извлекает полезные факты из удаляемых сообщений и добавляет их в очередь обновления памяти. Система также детектирует коррекции (пользователь исправил агента) и reinforcement (пользователь подтвердил поведение).

Context Engineering

Управление контекстом — одна из сильных сторон DeerFlow:

  1. Изоляция контекста суб-агентов — каждый суб-агент работает в своём контексте, не отвлекается на посторонний шум
  2. Агрессивная суммаризация — промежуточные результаты сжимаются и выгружаются в файловую систему
  3. Строгое восстановление tool-call — при сбоях DeerFlow автоматически чистит метаданные и вставляет placeholder-результаты, чтобы модель не падала на невалидной истории
  4. Инъекция памяти — релевантные факты из долгосрочной памяти вставляются в системный промпт (до 2000 токенов)

Sandbox и безопасность

Три режима песочницы

DeerFlow поддерживает три уровня изоляции:

  1. Local — код выполняется прямо на хосте. Файловые операции привязаны к per-thread директориям. Bash по умолчанию выключен (не является безопасной границей). Включать только для доверенных сценариев.

  2. Docker — каждая задача запускается в изолированном Docker-контейнере. Полноценная изоляция файловой системы и процессов.

  3. Kubernetes — контейнеры запускаются как поды через provisioner-сервис. Подходит для продакшен-деплоя с масштабированием.

Файловая система внутри песочницы

/mnt/user-data/
├── uploads/          ← файлы пользователя
├── workspace/        ← рабочая директория агента
└── outputs/          ← финальные результаты

Агент может читать, писать, редактировать файлы, просматривать изображения. Абстрактный класс Sandbox определяет интерфейс: execute_command, read_file, write_file, list_dir, grep. Конкретные провайдеры (AioSandboxProvider, LocalSandboxProvider) реализуют этот интерфейс.

Guardrails

Система guardrails обеспечивает:

  • Фильтрацию запросов и ответов через configurable middleware
  • Security scanner для сторонних навыков
  • Валидацию имён агентов (защита от path traversal)
  • File operation lock для предотвращения race conditions

Интеграции

MCP (Model Context Protocol)

DeerFlow поддерживает подключение внешних MCP-серверов для расширения набора инструментов. Это стандартизированный протокол от Anthropic для подключения внешних capability к агентам. Поддерживается кэширование инструментов и OAuth-авторизация.

Claude Code

Специальный навык claude-to-deerflow позволяет управлять DeerFlow прямо из терминала Claude Code — отправлять задачи, проверять статус, управлять тредами. Также DeerFlow поддерживает Claude Code как провайдер модели через OAuth.

IM-каналы

DeerFlow можно подключить к мессенджерам как бота:

  • Telegram — через Bot API (long-polling), самый простой вариант
  • Slack — через Socket Mode
  • Feishu/Lark — через WebSocket
  • WeChat — через Tencent iLink
  • WeCom — через WebSocket
  • DingTalk — через Stream Push

Все каналы работают через long-polling или WebSocket — публичный IP не нужен. Поддерживаются команды (/new, /status, /models, /memory, /help) и per-user настройки сессий.

Поддержка моделей

DeerFlow работает с широким набором моделей через LangChain:

  • OpenAI (GPT-4o, GPT-5, Responses API)
  • Anthropic (Claude через Claude Code OAuth)
  • DeepSeek
  • Qwen (через vLLM)
  • Doubao-Seed от ByteDance
  • Любые OpenAI-совместимые провайдеры (OpenRouter и др.)

Практическое применение

DeerFlow 2.0 подходит для нескольких категорий задач:

Исследования и аналитика. Основной сценарий: дать задачу вроде «проанализируй рынок X» — агент раскладывает её на подзадачи, запускает суб-агентов для параллельного исследования, собирает результаты в отчёт. Навык deep-research реализует систематическую методологию: широкий поиск → выделение измерений → глубокое погружение по каждому → синтез.

Генерация контента. Презентации, статьи, веб-страницы, видео, подкасты. Агент сначала исследует тему, затем генерирует контент с использованием профильного навыка.

Автоматизация рабочих процессов. Через IM-каналы DeerFlow становится рабочим ассистентом в Telegram или Slack. Пользователь пишет задачу в чат — агент выполняет её с доступом к поиску, файлам и коду.

Разработка. Интеграция с Claude Code, документирование кода, анализ данных, деплой на Vercel — всё это готовые навыки.

Кастомные агенты. Благодаря системе навыков и конфигурируемым агентам можно создать специализированных ботов для конкретных бизнес-процессов.

Выводы и что взять на вооружение

1. Skill-as-Markdown — элегантный подход. Навыки — это просто Markdown-файлы с методологией. Никакого кода, никаких API — чистый промпт-инжиниринг в структурированном формате. Это делает создание и редактирование навыков доступным для не-программистов.

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

3. Суб-агенты с изолированным контекстом — правильная абстракция для сложных задач. Каждый суб-агент фокусируется на своей подзадаче без шума от остальных. Параллельное выполнение ускоряет работу.

4. Память между сессиями превращает агента из одноразового инструмента в долгосрочного ассистента. Структурированное хранение фактов с confidence-скором и автоматическим извлечением при суммаризации — зрелый подход.

5. Sandbox-first архитектура. Агент не просто «вызывает функции» — у него есть полноценная файловая система и среда выполнения. Это принципиальная разница между чат-ботом с tools и настоящим агентом.

6. IM-интеграция из коробки. Шесть мессенджеров с единым API — это реальная экономия времени для команд, которые хотят развернуть агента в корпоративном чате.

7. Middleware-паттерн для агентов хорошо масштабируется. Guardrails, суммаризация, обработка ошибок — всё это отдельные слои, которые можно комбинировать.

DeerFlow 2.0 — один из наиболее зрелых open-source фреймворков для мультиагентных систем. Он подходит как для быстрого прототипирования (всё работает из коробки), так и для продакшен-деплоя (Docker/K8s, аутентификация, guardrails). Если вы строите систему на основе AI-агентов — стоит изучить как минимум их подходы к context engineering и skill-системе.

Проект: github.com/bytedance/deer-flow | Лицензия: MIT | Язык: Python (backend) + TypeScript (frontend)

← Назад к Ссылки и заметки

Backlinks