Основные концепции
Этот документ описывает ключевые сущности SGR Deep Research Framework.
Vibe-Глоссарий
Смотря какой fabric, смотря сколько details
В профессиональной речи сложно подобрать адаптации некоторым терминам, поэтому в этой документации могут встречаться жаргонизмы, англицизмы и ещё бог весть что :)
Large Language Model (LLM) — большая языковая модель, обученная на больших объёмах данных для генерации и понимания текста. В контексте фреймворка используется для reasoning, планирования и выбора действий агента.
Structured Output (SO) — подход к получению структурированных данных от LLM через явное определение JSON-схемы. Вместо свободного текстового ответа модель возвращает данные в строго определённом формате, что обеспечивает надёжный парсинг и валидацию. В фреймворке используется через параметр response_format
Function Calling (FC) — нативный механизм для вызова функций/инструментов. LLM получает описание доступных функций и может явно запросить их вызов, возвращая структурированные аргументы. Позволяет интегрировать внешние инструменты и API в диалог с моделью. В большинстве инференс движков и API провайдеров LLM используется бекенд для генерации JSON схемы идентичный Structured Output
Reasoning — процесс рассуждения и анализа, в ходе которого агент оценивает текущую ситуацию, анализирует доступную информацию, планирует следующие шаги и принимает решение о выборе действия. В фреймворке reasoning может быть явным (через структурированную схему) или неявным (внутри LLM).
Tool / тул / тулза — исполняемый компонент, который агент может вызывать для выполнения конкретных действий (поиск в интернете, запрос уточнений, создание отчёта и т.д.).
Agent / агент — автономная программная сущность, способная воспринимать окружение, принимать решения и выполнять действия для достижения поставленной цели. В фреймворке агент реализует цикл Reasoning → Action, используя LLM для принятия решений и инструменты для выполнения действий.
Agent
BaseAgent — Родительский класс для всех агентов. Определяет двухфазный цикл выполнения: Reasoning Phase → (Select Action Phase + Call Action Phase)
С точки зрения программной логики можно сказать, что фазы три, но Call Action, строго говоря, не является действием агента - она делегирует задачу тулзе, поэтому кажется более простым и привычным воспринимать как ReAct цикл выполнения. Практическое количество действий и запросов к LLM может сильно различаться от конкретных реализаций
Все созданные агенты автоматически регистрируются в AgentRegistry
Доступные агенты
Фреймворк включает несколько готовых реализаций агентов:
SGRAgent
Schema-Guided Reasoning Agent — полностью базируется на Structured Output подходе. Хорошо себя показывает для моделей, которые плохо справляются с Reasoning / Function Calling самостоятельно.
- Reasoning Phase: Создаётся динамическая JSON схема, содержащая описание всех доступных тулов.
LLM возвращает ответ, помимо размышлений содержащий готовую схему тула в поле
function - Select Action Phase: Тул извлекается напрямую из
reasoning.function— LLM уже выбрал тул в фазе reasoning - Action Phase: Стандартное выполнение выбранного тула
ToolCallingAgent
Native Function Calling Agent — полагается на нативный function calling без явной фазы reasoning. Современные модели достаточно самостоятельны и отдельно обучались именно такому формату работы и урезание их возможностей к размышлению может только мешать. Лучше всего себя показывает в работе с большими, "умными" моделями
- Reasoning Phase: Отсутствует — reasoning происходит внутри LLM
- Select Action Phase: Использует
tool_choice="required"для принудительного вызова тула внутри LLM - Action Phase: Стандартное выполнение выбранного тула
SGRToolCallingAgent
Hybrid SGR + Function Calling Agent — комбинирует структурированный reasoning с нативным function calling. Берёт лучшее от обоих миров. Хорошо себя показывает для большинства задач
- Reasoning Phase: Использует function calling для получения результата системной
ReasoningTool(явный reasoning через структурированную схему) - Select Action Phase: Использует function calling с
tool_choice="required"для выбора конкретного тула на основе контекста reasoning этапа - Action Phase: Стандартное выполнение выбранного тула
ResearchSGRAgent
ResearchToolCallingAgent
ResearchSGRToolCallingAgent
Более прикладные реализации агентов для работы с информацией, имеющие предопределённый набор тулов
Tool
BaseTool — Родительский класс для всех тулов. Представляет собой Pydantic модель. Тул является единой точкой входа для любой логики поведения агента - набор тулов определяет его возможности и специфику.
Все созданные тулы автоматически регистрируются в ToolRegistry
Компоненты тула
-
tool_name— название. Используется для идентификации тула в системе и при вызове через LLM. -
description— описание и инструкции. Используется LLM для понимания назначения и возможностей тула. Если не указано явно, автоматически берётся из docstring класса. -
__call__()— Основной метод вызова логики тула агентом.
MCPTool
MCPBaseTool — Базовый класс для тулов, интегрированных с MCP (Model Context Protocol) серверами. Обрабатывает вызовы через MCP клиент, переводит их в формат тулов фреймворка
Tip
Подробнее о тулах и их использовании: Tools
Definition
AgentDefinition — Шаблон для создания агентов. Содержит в себе всю необходимую конфигурацию для сборки экземпляра под конкретную задачу. По генеральной идее мы имеем: Agent - Универсальная реализация методов основной логики работы агента Definition - Схема и значения настроек агента. Agent object - Agent+Definition: Готовый агент, имеющий изолированный контекст, историю, логи и выполняющий конкретную задачу
AgentConfig
AgentConfig — централизованная конфигурация агента, объединяющая настройки LLM, поиска, выполнения, промптов и MCP. Поддерживает иерархическую систему конфигурации через GlobalConfig и AgentDefinition с автоматическим наследованием и переопределением параметров.
Tip
Подробнее о конфигурации и дефинициях: Configuration Guide
Registry
Registry — централизованные реестры (AgentRegistry, ToolRegistry) для автоматической регистрации и поиска классов.