fixes by review

Author: snow-ghost

config.yaml.example

@@ -107,7 +107,10 @@ agents:
           url: "https://mcp.deepwiki.com/mcp"
 
     # Tools: names, or dicts with "name" and optional kwargs (e.g. search settings per tool)
-    # Example: {"name": "web_search_tool", "max_results": 15, "max_searches": 6}
+    # Example:
+    # - web_search_tool:
+    #    max_results: 15
+    #    max_searches: 6
     tools:
       - "web_search_tool"
       - "extract_page_content_tool"

docs/ru/framework/configuration.md

@@ -73,6 +73,68 @@ config = GlobalConfig.from_yaml("config.yaml")
 
 **Ключевая особенность:** `AgentDefinition` наследует все параметры из `GlobalConfig` и переопределяет только те, которые указаны явно. Это позволяет создавать минималистичные конфигурации, указывая только необходимые изменения.
 
+### Определения инструментов
+
+Инструменты можно описывать в отдельной секции `tools:` в `config.yaml` или `agents.yaml`. Это позволяет:
+
+- Задавать кастомные инструменты с нужными параметрами
+- Ссылаться на инструменты по имени в определениях агентов
+- Переопределять класс инструмента по умолчанию
+
+**Формат определения инструмента:**
+
+В глобальной секции `tools:` каждая запись может содержать:
+
+- **base_class** (необязательно) — путь импорта или имя класса в реестре
+- **Любые другие ключи** — передаются в инструмент при вызове как kwargs (например, `max_results`, `max_searches`, `content_limit` для поисковых инструментов). Агенты, использующие инструмент по имени, получают эти параметры; конфиг в списке `tools` агента переопределяет глобальные значения.
+
+```yaml
+tools:
+  # Простое определение (base_class по умолчанию из ToolRegistry)
+  reasoning_tool:
+    # base_class по умолчанию: sgr_agent_core.tools.ReasoningTool
+
+  # Кастомный инструмент с явным base_class
+  custom_tool:
+    base_class: "tools.CustomTool"  # Относительный путь
+
+  # Глобальные значения по умолчанию (все агенты с этим инструментом получат эти kwargs)
+  web_search_tool:
+    max_results: 12
+    max_searches: 6
+```
+
+**Использование инструментов в агентах:**
+
+Каждый элемент списка `tools` может быть:
+
+- **Строка** — имя инструмента (резолвится из секции `tools:` или `ToolRegistry`)
+- **Объект** — словарь с обязательным полем `"name"` и необязательными параметрами, передаваемыми в инструмент при вызове (например, настройки поиска)
+
+```yaml
+agents:
+  my_agent:
+    base_class: "SGRToolCallingAgent"
+    tools:
+      - "web_search_tool"
+      - "reasoning_tool"
+      # Конфиг по инструменту: name + kwargs (например, настройки поиска)
+      - name: "extract_page_content_tool"
+        content_limit: 2000
+      - name: "web_search_tool"
+        max_results: 15
+        max_searches: 6
+        # tavily_api_key, max_searches и т.д. можно задать здесь вместо глобального search:
+```
+
+Настройки поиска (`tavily_api_key`, `tavily_api_base_url`, `max_results`, `content_limit`, `max_searches`) можно задавать глобально в `search:` или в объекте инструмента. kwargs инструмента переопределяют агентский `search` для этого инструмента.
+
+!!! note "Порядок резолва инструментов"
+    При резолве инструментов система проверяет в порядке:
+    1. Инструменты из секции `tools:` (по имени)
+    2. Инструменты из `ToolRegistry` (по имени в snake_case — рекомендуется, или по имени класса в PascalCase для совместимости)
+    3. Автопреобразование snake_case → PascalCase (например, `web_search_tool` → `WebSearchTool`) для совместимости
+
 ### Примеры конфигурации агентов
 
 Агенты определяются в файле `agents.yaml` или могут быть загружены программно:
@@ -238,6 +300,31 @@ agents:
       - "final_answer_tool"
 ```
 
+#### Пример 5: С определениями инструментов
+
+Агент, использующий определения инструментов из секции `tools`:
+
+```yaml
+# Определяем инструменты в секции tools
+tools:
+  reasoning_tool:
+    # По умолчанию: sgr_agent_core.tools.ReasoningTool
+  custom_file_tool:
+    base_class: "tools.CustomFileTool"  # Кастомный инструмент из локального модуля
+
+agents:
+  file_agent:
+    base_class: "SGRToolCallingAgent"
+
+    llm:
+      model: "gpt-4o-mini"
+
+    # Ссылаемся на инструменты по имени из секции tools или ToolRegistry
+    tools:
+      - "reasoning_tool"       # Из секции tools
+      - "custom_file_tool"     # Из секции tools
+      - "final_answer_tool"    # Из ToolRegistry
+```
 
 ## Рекомендации
 
@@ -246,5 +333,5 @@ agents:
     В production окружении рекомендуется использовать ENV переменные вместо хардкода ключей в YAML
 
 - **Используйте минимальные переопределения** - указывайте только то, что отличается от GlobalConfig
-- **Храните Definitions, a не Agents** - Агенты создаются под непосредственное выполнение задачи,
+- **Храните Definitions, а не Agents** - Агенты создаются под непосредственное выполнение задачи,
 их definitions можно добавлять/удалять/изменять в любое время

examples/sgr_deep_research/agents.py

@@ -61,10 +61,8 @@ async def _prepare_tools(self) -> Type[NextStepToolStub]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }
@@ -105,10 +103,8 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }
@@ -150,10 +146,8 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }

examples/sgr_deep_research_without_reporting/agents.py

@@ -61,10 +61,8 @@ async def _prepare_tools(self) -> Type[NextStepToolStub]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }
@@ -106,10 +104,8 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }
@@ -152,10 +148,8 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (
-            self.config.search.max_searches if self.config.search else 4
-        )
-        if self._context.searches_used >= max_searches:
+        search_config = self.get_tool_config(WebSearchTool)
+        if self._context.searches_used >= search_config.max_searches:
             tools -= {
                 WebSearchTool,
             }

sgr_agent_core/base_agent.py

@@ -5,10 +5,11 @@
 import traceback
 import uuid
 from datetime import datetime
-from typing import Type
+from typing import Any, Type
 
 from openai import AsyncOpenAI, pydantic_function_tool
 from openai.types.chat import ChatCompletionFunctionToolParam, ChatCompletionMessageParam
+from pydantic import BaseModel
 
 from sgr_agent_core.agent_definition import AgentConfig
 from sgr_agent_core.models import AgentContext, AgentStatesEnum
@@ -20,6 +21,7 @@
     ClarificationTool,
     ReasoningTool,
 )
+from sgr_agent_core.utils import config_from_kwargs
 
 
 class AgentRegistryMixin:
@@ -62,6 +64,22 @@ def __init__(
 
         self._execute_task: asyncio.Task | None = None
 
+    def get_tool_config(self, tool_class: Type[BaseTool]) -> BaseModel | dict[str, Any]:
+        """Return resolved config for a tool as a Pydantic model or raw dict.
+
+        If the tool defines config_model (and optionally
+        base_config_attr), merges agent-level base config with
+        tool_configs and returns a validated instance. Otherwise returns
+        the raw dict from tool_configs.
+        """
+        raw = self.tool_configs.get(tool_class.tool_name, {})
+        config_model = getattr(tool_class, "config_model", None)
+        if config_model is None:
+            return raw
+        base_attr = getattr(tool_class, "base_config_attr", None)
+        base = getattr(self.config, base_attr, None) if base_attr and self.config else None
+        return config_from_kwargs(config_model, base, raw)
+
     async def provide_clarification(self, messages: list[ChatCompletionMessageParam]):
         """Receive clarification from an external source (e.g. user input) in
         OpenAI messages format."""

sgr_agent_core/base_tool.py

@@ -14,7 +14,6 @@
     from sgr_agent_core.agent_definition import AgentConfig
     from sgr_agent_core.models import AgentContext
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -30,6 +29,10 @@ class BaseTool(BaseModel, ToolRegistryMixin):
 
     tool_name: ClassVar[str] = None
     description: ClassVar[str] = None
+    # Optional: Pydantic model for this tool's config; agent.get_tool_config(tool_class) returns it
+    config_model: ClassVar[type[BaseModel] | None] = None
+    # If set, agent config attribute to merge as base (e.g. "search") when resolving tool config
+    base_config_attr: ClassVar[str | None] = None
 
     async def __call__(self, context: AgentContext, config: AgentConfig, **kwargs) -> str:
         """The result should be a string or dumped JSON."""

sgr_agent_core/tools/extract_page_content_tool.py

@@ -34,6 +34,9 @@ class ExtractPageContentTool(BaseTool):
         - For date/number questions, cross-check extracted values with search snippets
     """
 
+    config_model = SearchConfig
+    base_config_attr = "search"
+
     reasoning: str = Field(description="Why extract these specific pages")
     urls: list[str] = Field(description="List of URLs to extract full content from", min_length=1, max_length=5)
 

sgr_agent_core/tools/web_search_tool.py

@@ -44,6 +44,9 @@ class WebSearchTool(BaseTool):
         - If the snippet directly answers the question, you may not need to extract the full page
     """
 
+    config_model = SearchConfig
+    base_config_attr = "search"
+
     reasoning: str = Field(description="Why this search is needed and what to expect")
     query: str = Field(description="Search query in same language as user request")
     max_results: int = Field(

tests/test_base_agent.py

@@ -11,9 +11,10 @@
 
 import pytest
 
+from sgr_agent_core.agent_definition import AgentConfig, ExecutionConfig, LLMConfig, PromptsConfig, SearchConfig
 from sgr_agent_core.base_agent import BaseAgent
 from sgr_agent_core.models import AgentContext, AgentStatesEnum
-from sgr_agent_core.tools import BaseTool, ReasoningTool
+from sgr_agent_core.tools import BaseTool, ReasoningTool, WebSearchTool
 from tests.conftest import create_test_agent
 
 
@@ -331,6 +332,60 @@ class TestToolWithEnum(BaseTool):
         assert tool_context["status"] == "done"
 
 
+class TestBaseAgentGetToolConfig:
+    """Tests for get_tool_config resolution."""
+
+    def test_get_tool_config_returns_model_when_tool_has_config_model(self):
+        """get_tool_config returns Pydantic model instance for tools with
+        config_model."""
+        agent = create_test_agent(
+            BaseAgent,
+            task_messages=[{"role": "user", "content": "Test"}],
+            toolkit=[WebSearchTool],
+        )
+        agent.tool_configs = {"websearchtool": {"max_searches": 6}}
+        agent.config = AgentConfig(
+            llm=LLMConfig(api_key="k", base_url="https://api.openai.com/v1"),
+            prompts=PromptsConfig(system_prompt_str="p", initial_user_request_str="p", clarification_response_str="p"),
+            execution=ExecutionConfig(),
+            search=None,
+        )
+        out = agent.get_tool_config(WebSearchTool)
+        assert isinstance(out, SearchConfig)
+        assert out.max_searches == 6
+
+    def test_get_tool_config_merges_base_from_agent_config(self):
+        """get_tool_config merges base from base_config_attr (e.g.
+        config.search)."""
+        agent = create_test_agent(
+            BaseAgent,
+            task_messages=[{"role": "user", "content": "Test"}],
+            toolkit=[WebSearchTool],
+        )
+        agent.tool_configs = {"websearchtool": {}}
+        agent.config = AgentConfig(
+            llm=LLMConfig(api_key="k", base_url="https://api.openai.com/v1"),
+            prompts=PromptsConfig(system_prompt_str="p", initial_user_request_str="p", clarification_response_str="p"),
+            execution=ExecutionConfig(),
+            search=SearchConfig(tavily_api_key="key", max_searches=10),
+        )
+        out = agent.get_tool_config(WebSearchTool)
+        assert isinstance(out, SearchConfig)
+        assert out.max_searches == 10
+        assert out.tavily_api_key == "key"
+
+    def test_get_tool_config_returns_dict_when_tool_has_no_config_model(self):
+        """get_tool_config returns raw dict when tool has no config_model."""
+        agent = create_test_agent(
+            BaseAgent,
+            task_messages=[{"role": "user", "content": "Test"}],
+            toolkit=[ReasoningTool],
+        )
+        agent.tool_configs = {"reasoningtool": {"foo": "bar"}}
+        out = agent.get_tool_config(ReasoningTool)
+        assert out == {"foo": "bar"}
+
+
 class TestBaseAgentAbstractMethods:
     """Tests for abstract methods that must be implemented by subclasses."""