EvilFreelancer · Sep 16, 2026 · Aug 27, 2026 · Aug 27, 2026 · Aug 27, 2026
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -32,3 +32,63 @@ jobs:
 
       - name: Create report
         run: coverage report
+
+  test-core-only:
+    name: Core-only install stays lean
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      # Guards the extras split: a stray top-level import of an optional
+      # package would silently put every heavy dependency back into the
+      # default install.
+      - name: Install without extras
+        run: pip install .
+
+      - name: Assert optional packages are absent
+        shell: bash
+        run: |
+          cd "$(mktemp -d)"
+          python - <<'PY'
+          import importlib.util
+
+          optional = ["fastmcp", "jambo", "tavily", "fastapi", "uvicorn", "acp", "langfuse", "rank_bm25"]
+          present = [name for name in optional if importlib.util.find_spec(name) is not None]
+          assert not present, f"optional packages installed by the core profile: {present}"
+          print("core profile clean")
+          PY
+
+      - name: Assert the package works without them
+        shell: bash
+        run: |
+          cd "$(mktemp -d)"
+          python - <<'PY'
+          import sys
+
+          import sgr_agent_core
+          from sgr_agent_core import AgentConfig, AgentFactory, ToolRegistry, WebSearchTool
+
+          loaded = [m for m in ("fastmcp", "tavily", "fastapi", "uvicorn", "acp", "langfuse") if m in sys.modules]
+          assert not loaded, f"optional packages imported at module scope: {loaded}"
+          assert AgentConfig().mcp.mcpServers == {}
+          assert ToolRegistry.get(WebSearchTool.tool_name) is WebSearchTool
+          assert AgentFactory is not None
+          print("core-only import OK", sgr_agent_core.__version__)
+          PY
+
+      - name: Assert entrypoints name the missing extra
+        shell: bash
+        run: |
+          cd "$(mktemp -d)"
+          for cmd in sgr sgracp; do
+            output=$("$cmd" --help 2>&1 || true)
+            echo "$output"
+            echo "$output" | grep -q "sgr-agent-core\[" || {
+              echo "::error::$cmd did not report the missing extra"
+              exit 1
+            }
+          done
diff --git a/Dockerfile b/Dockerfile
@@ -23,8 +23,10 @@ COPY pyproject.toml MANIFEST.in README.md LICENSE ./
 COPY sgr_agent_core/ ./sgr_agent_core/
 COPY examples/ ./examples/
 
-# Install package from root
-RUN pip install --no-cache-dir .
+# Install package from root. The core install is minimal, so pull the [examples]
+# extra: it chains to [all] (MCP, search, server, ACP, Langfuse) and adds what
+# the bundled examples/ need on top.
+RUN pip install --no-cache-dir ".[examples]"
 
 # Remove build dependencies
 RUN apt purge -y build-essential \

diff --git a/README.md b/README.md
@@ -68,6 +68,15 @@ If you want to use SGR Agent Core as a Python library (framework):
 pip install sgr-agent-core
 ```
 
+The core install is small on purpose — `pydantic`, `PyYAML`, `openai`, `httpx` —
+enough to define agents and tools and run them through `sgrsh`. Integrations are
+opt-in extras: `mcp`, `search` (Tavily), `server` (the `sgr` HTTP API), `acp`,
+`langfuse`. To get the full set:
+
+```bash
+pip install "sgr-agent-core[all]"
+```
+
 See the [Installation Guide](https://vamplabai.github.io/sgr-agent-core/getting-started/installation/) for detailed instructions and the [Using as Library](https://vamplabai.github.io/sgr-agent-core/framework/first-steps/) guide to get started.
 
 ### Running Research Agents
@@ -84,7 +93,8 @@ cp examples/sgr_deep_research/config.yaml.example examples/sgr_deep_research/con
 # - tools.extract_page_content_tool.tavily_api_key: Your Tavily API key (optional)
 ```
 
-2. Run the API server using the `sgr` utility:
+2. Run the API server using the `sgr` utility (needs the `server` extra, plus
+   `search` for the Tavily-backed research tools):
 
 ```bash
 sgr --config-file examples/sgr_deep_research/config.yaml

diff --git a/docs/en/framework/first-steps.md b/docs/en/framework/first-steps.md
@@ -10,6 +10,10 @@ Install the library via pip:
 pip install sgr-agent-core
 ```
 
+That is all the examples below need. Integrations — MCP, Tavily search, the HTTP
+server, ACP, Langfuse — are opt-in extras; see the
+[Installation Guide](../getting-started/installation.md) for the full list.
+
 ### **Example 1: Creating an Agent Directly**
 
 The conventional way to create an agent is through the class constructor.</br>

diff --git a/docs/en/framework/langfuse.md b/docs/en/framework/langfuse.md
@@ -6,7 +6,13 @@ is automatically recorded as a trace with inputs, outputs, latency, and token us
 
 ## Quick Start
 
-Add the `langfuse` block to your `config.yaml`:
+Install the `langfuse` extra:
+
+```bash
+pip install "sgr-agent-core[langfuse]"
+```
+
+Then add the `langfuse` block to your `config.yaml`:
 
 ```yaml
 langfuse:
@@ -163,8 +169,8 @@ langfuse: true
 
 If `langfuse.enabled` is `true` in configuration but the `langfuse` package is not installed
 or cannot be imported, agent startup raises `LangfuseImportError` with a clear message.
-Install the project dependencies (`langfuse` is a core dependency of SGR Agent Core) or
-disable Langfuse by setting `langfuse.enabled` to `false`.
+`langfuse` is an optional dependency: install it with `pip install "sgr-agent-core[langfuse]"`,
+or disable Langfuse by setting `langfuse.enabled` to `false`.
 
 ### "Authentication error: Langfuse client initialized without public_key"
 

diff --git a/docs/en/framework/tools.md b/docs/en/framework/tools.md
@@ -490,6 +490,12 @@ This ensures agents complete tasks within configured limits.
 
 Tools can also be created from MCP (Model Context Protocol) servers. These tools inherit from `MCPBaseTool` and are automatically generated from MCP server schemas.
 
+MCP support ships in the `mcp` extra:
+
+```bash
+pip install "sgr-agent-core[mcp]"
+```
+
 **Source:** [sgr_agent_core/base_tool.py](https://github.com/vamplabAI/sgr-agent-core/blob/main/sgr_agent_core/base_tool.py) (MCPBaseTool class)
 
 **Configuration:**

diff --git a/docs/en/framework/tools/extract-page-content-tool.md b/docs/en/framework/tools/extract-page-content-tool.md
@@ -5,6 +5,8 @@
 
 Extracts full detailed content from specific web pages using Tavily Extract API.
 
+Needs the `search` extra: `pip install "sgr-agent-core[search]"`.
+
 **Parameters**
 
 - `reasoning` (str) - why extract these specific pages

diff --git a/docs/en/framework/tools/web-search-tool.md b/docs/en/framework/tools/web-search-tool.md
@@ -5,6 +5,9 @@
 
 Searches the web for real-time information using Tavily Search API.
 
+The `tavily` engine needs the `search` extra (`pip install "sgr-agent-core[search]"`).
+The `brave` and `perplexity` engines talk plain HTTP and work on the core install.
+
 **Parameters**
 
 - `reasoning` (str) - why this search is needed and what to expect

diff --git a/docs/en/getting-started/installation.md b/docs/en/getting-started/installation.md
@@ -12,9 +12,45 @@ Install the core package:
 pip install sgr-agent-core
 ```
 
-### Installation with Optional Dependencies
+The core install is deliberately small: it brings only what every SGR agent
+needs — `pydantic`, `pydantic-settings`, `PyYAML`, `openai` and `httpx`. That is
+enough to define agents and tools, load YAML configuration, use skills, and run
+the `sgrsh` interactive CLI.
 
-For development, you can install with additional dependencies:
+### Integration Extras
+
+Everything beyond the core ships as an extra. Install only the ones you use:
+
+| Extra | Adds | Install it when you need |
+|---|---|---|
+| `mcp` | `fastmcp`, `jambo` | MCP servers under the `mcp:` config key |
+| `search` | `tavily-python` | `WebSearchTool` with `engine: tavily`, or `ExtractPageContentTool` |
+| `server` | `fastapi`, `uvicorn` | The `sgr` HTTP API server |
+| `acp` | `agent-client-protocol` | The `sgracp` Agent Client Protocol stdio server |
+| `langfuse` | `langfuse` | `langfuse.enabled: true` observability |
+| `all` | all of the above | The full feature set |
+
+```bash
+# Just what you need
+pip install "sgr-agent-core[mcp,search]"
+
+# Everything — matches the dependency set installed by default up to 0.7.1
+pip install "sgr-agent-core[all]"
+```
+
+The `brave` and `perplexity` search engines of `WebSearchTool` talk plain HTTP,
+so they work on the core install without the `search` extra.
+
+If a feature's extra is missing, SGR Agent Core says so and names the command to
+fix it rather than failing with a bare `ModuleNotFoundError`:
+
+```console
+$ sgr --config-file config.yaml
+The 'sgr' HTTP server requires the optional 'uvicorn' package, which is not installed.
+Install it with:  pip install 'sgr-agent-core[server]'
+```
+
+### Development Extras
 
 ```bash
 # Install with development dependencies
@@ -27,10 +63,14 @@ pip install sgr-agent-core[tests]
 pip install sgr-agent-core[docs]
 ```
 
+`dev` and `tests` include `all`, so the test suite always runs against the full
+feature set.
+
 ### Requirements
 
 * Python 3.11 or higher
 * OpenAI-compatible LLM API key (or local model endpoint)
+* pip 21.2 or newer (the `all`, `tests` and `dev` extras reference other extras)
 
 ### Verify Installation
 

diff --git a/docs/ru/framework/first-steps.md b/docs/ru/framework/first-steps.md
@@ -10,6 +10,10 @@
 pip install sgr-agent-core
 ```
 
+Этого достаточно для всех примеров ниже. Интеграции — MCP, поиск через Tavily,
+HTTP-сервер, ACP, Langfuse — подключаются отдельными extras; полный список см. в
+[руководстве по установке](../getting-started/installation.md).
+
 ### **Пример 1: Создание агента напрямую**
 
 Привычный способ создать агента - через конструктор класса.</br>

diff --git a/docs/ru/framework/langfuse.md b/docs/ru/framework/langfuse.md
@@ -7,7 +7,13 @@ LLM автоматически записывается как трейс с в
 
 ## Быстрый старт
 
-Добавьте блок `langfuse` в ваш `config.yaml`:
+Установите extra `langfuse`:
+
+```bash
+pip install "sgr-agent-core[langfuse]"
+```
+
+Затем добавьте блок `langfuse` в ваш `config.yaml`:
 
 ```yaml
 langfuse:
@@ -165,8 +171,8 @@ langfuse: true
 
 Если в конфигурации `langfuse.enabled: true`, но пакет `langfuse` не установлен или недоступен
 для импорта, при старте агента выбрасывается `LangfuseImportError` с понятным текстом.
-Установите зависимости проекта (`langfuse` входит в основные зависимости SGR Agent Core) либо
-отключите Langfuse, установив `langfuse.enabled` в `false`.
+`langfuse` — опциональная зависимость: установите её командой `pip install "sgr-agent-core[langfuse]"`
+либо отключите Langfuse, установив `langfuse.enabled` в `false`.
 
 ### "Authentication error: Langfuse client initialized without public_key"
 

diff --git a/docs/ru/framework/tools.md b/docs/ru/framework/tools.md
@@ -537,6 +537,12 @@ agents:
 
 Тулы также могут создаваться из MCP (Model Context Protocol) серверов. Эти тулы наследуются от `MCPBaseTool` и автоматически генерируются из схем MCP-сервера.
 
+Поддержка MCP поставляется в extra `mcp`:
+
+```bash
+pip install "sgr-agent-core[mcp]"
+```
+
 **Исходный код:** [sgr_agent_core/base_tool.py](https://github.com/vamplabAI/sgr-agent-core/blob/main/sgr_agent_core/base_tool.py) (класс MCPBaseTool)
 
 **Конфигурация:**

diff --git a/docs/ru/framework/tools/extract-page-content-tool.md b/docs/ru/framework/tools/extract-page-content-tool.md
@@ -5,6 +5,8 @@
 
 Извлекает полное детальное содержимое с конкретных веб-страниц с использованием Tavily Extract API.
 
+Требуется extra `search`: `pip install "sgr-agent-core[search]"`.
+
 **Параметры**
 
 - `reasoning` (str) - почему нужно извлечь эти конкретные страницы

diff --git a/docs/ru/framework/tools/web-search-tool.md b/docs/ru/framework/tools/web-search-tool.md
@@ -5,6 +5,9 @@
 
 Выполняет поиск в интернете для получения актуальной информации с использованием Tavily Search API.
 
+Движку `tavily` нужен extra `search` (`pip install "sgr-agent-core[search]"`).
+Движки `brave` и `perplexity` работают по обычному HTTP и доступны в базовой установке.
+
 **Параметры**
 
 - `reasoning` (str) - почему нужен этот поиск и что ожидается найти

diff --git a/docs/ru/getting-started/installation.md b/docs/ru/getting-started/installation.md
@@ -12,9 +12,46 @@ SGR Agent Core можно установить через pip или Docker. В
 pip install sgr-agent-core
 ```
 
-### Установка с дополнительными зависимостями
+Базовая установка намеренно лёгкая: она тянет только то, что нужно любому
+SGR-агенту — `pydantic`, `pydantic-settings`, `PyYAML`, `openai` и `httpx`.
+Этого достаточно, чтобы описывать агентов и инструменты, загружать YAML-конфиг,
+использовать скиллы и запускать интерактивный CLI `sgrsh`.
 
-Для разработки можно установить с дополнительными зависимостями:
+### Опциональные интеграции (extras)
+
+Всё, что выходит за пределы ядра, поставляется отдельными extras.
+Ставьте только то, чем пользуетесь:
+
+| Extra | Что добавляет | Когда нужен |
+|---|---|---|
+| `mcp` | `fastmcp`, `jambo` | MCP-серверы в секции `mcp:` конфигурации |
+| `search` | `tavily-python` | `WebSearchTool` с `engine: tavily` или `ExtractPageContentTool` |
+| `server` | `fastapi`, `uvicorn` | HTTP API-сервер `sgr` |
+| `acp` | `agent-client-protocol` | Stdio-сервер `sgracp` (Agent Client Protocol) |
+| `langfuse` | `langfuse` | Наблюдаемость при `langfuse.enabled: true` |
+| `all` | всё перечисленное | Полный набор возможностей |
+
+```bash
+# Только нужное
+pip install "sgr-agent-core[mcp,search]"
+
+# Всё сразу — набор зависимостей, который ставился по умолчанию до 0.7.1
+pip install "sgr-agent-core[all]"
+```
+
+Движки `brave` и `perplexity` в `WebSearchTool` работают по обычному HTTP,
+поэтому доступны в базовой установке без extra `search`.
+
+Если extra для нужной функции не установлен, SGR Agent Core сообщит об этом и
+подскажет команду установки вместо голого `ModuleNotFoundError`:
+
+```console
+$ sgr --config-file config.yaml
+The 'sgr' HTTP server requires the optional 'uvicorn' package, which is not installed.
+Install it with:  pip install 'sgr-agent-core[server]'
+```
+
+### Extras для разработки
 
 ```bash
 # Установка с зависимостями для разработки
@@ -27,10 +64,14 @@ pip install sgr-agent-core[tests]
 pip install sgr-agent-core[docs]
 ```
 
+`dev` и `tests` включают в себя `all`, поэтому тесты всегда прогоняются на
+полном наборе возможностей.
+
 ### Требования
 
 * Python 3.11 или выше
 * API ключ для LLM, совместимого с OpenAI (или эндпоинт локальной модели)
+* pip 21.2 или новее (extras `all`, `tests` и `dev` ссылаются на другие extras)
 
 ### Проверка установки