Pass config to tool constructor

snow-ghost · snow-ghost · commit 50561f8b1027 · 2026-02-03T23:11:19.000+05:00
diff --git a/agents.yaml.example b/agents.yaml.example
@@ -44,10 +44,10 @@ agents:
         deepwiki:
           url: "https://mcp.deepwiki.com/mcp"
 
-    # Tools this agent can use (names from tools section in config)
+    # Tools: list of names, or dicts with "name" and optional kwargs (passed to tool at runtime)
     tools:
       - "web_search_tool"
-      - "extract_page_content_tool"
+      - {"name": "extract_page_content_tool", "content_limit": 2000}
       - "create_report_tool"
       - "clarification_tool"
       - "generate_plan_tool"
diff --git a/config.yaml.example b/config.yaml.example
@@ -99,9 +99,8 @@ agents:
         deepwiki:
           url: "https://mcp.deepwiki.com/mcp"
 
-    # Tools this agent can use (must be registered in tool registry)
-    # Recommended: use snake_case format (e.g., "web_search_tool")
-    # PascalCase format (e.g., "WebSearchTool") is supported for backward compatibility
+    # 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}
     tools:
       - "web_search_tool"
       - "extract_page_content_tool"
diff --git a/docs/en/framework/configuration.md b/docs/en/framework/configuration.md
@@ -94,16 +94,29 @@ tools:
 
 **Using Tools in Agents:**
 
+Each item in the `tools` list can be:
+
+- **String** – tool name (resolved from the `tools:` section or `ToolRegistry`)
+- **Object** – dict with required `"name"` and optional parameters passed to the tool at runtime as kwargs (e.g. search settings for search tools)
+
 ```yaml
 agents:
   my_agent:
     base_class: "SGRToolCallingAgent"
     tools:
-      - "web_search_tool"  # From ToolRegistry
-      - "reasoning_tool"  # From tools section
-      - "custom_tool"  # From tools section
+      - "web_search_tool"
+      - "reasoning_tool"
+      # Per-tool config: name + kwargs (e.g. search settings)
+      - name: "extract_page_content_tool"
+        content_limit: 2000
+      - name: "web_search_tool"
+        max_results: 15
+        max_searches: 6
+        # tavily_api_key, max_searches, etc. can be set here instead of in global search:
 ```
 
+Search-related settings (`tavily_api_key`, `tavily_api_base_url`, `max_results`, `content_limit`, `max_searches`) can be set globally in `search:` or per-tool in the tool object. Tool kwargs override agent-level `search` for that tool.
+
 !!! note "Tool Resolution Order"
     When resolving tools, the system checks in this order:
     1. Tools defined in `tools:` section (by name)
diff --git a/examples/sgr_deep_research/agents.py b/examples/sgr_deep_research/agents.py
@@ -61,7 +61,10 @@ async def _prepare_tools(self) -> Type[NextStepToolStub]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
@@ -102,7 +105,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
@@ -144,7 +150,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
diff --git a/examples/sgr_deep_research_without_reporting/agents.py b/examples/sgr_deep_research_without_reporting/agents.py
@@ -61,7 +61,10 @@ async def _prepare_tools(self) -> Type[NextStepToolStub]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
@@ -103,7 +106,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
@@ -146,7 +152,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:
             tools -= {
                 ClarificationTool,
             }
-        if self._context.searches_used >= self.config.search.max_searches:
+        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:
             tools -= {
                 WebSearchTool,
             }
diff --git a/sgr_agent_core/agent_definition.py b/sgr_agent_core/agent_definition.py
@@ -6,6 +6,9 @@
 from pathlib import Path
 from typing import Any, Self, Union
 
+# Element of AgentDefinition.tools: name (str), class (type), or dict with "name" + kwargs
+ToolItem = Union[str, type[Any], dict[str, Any]]
+
 import yaml
 from fastmcp.mcp_config import MCPConfig
 from pydantic import BaseModel, Field, FilePath, ImportString, computed_field, field_validator, model_validator
@@ -175,7 +178,26 @@ class AgentDefinition(AgentConfig):
     name: str = Field(description="Unique agent name/ID")
     # ToDo: not sure how to type this properly and avoid circular imports
     base_class: type[Any] | ImportString | str = Field(description="Agent class name")
-    tools: list[type[Any] | str] = Field(default_factory=list, description="List of tool names to include")
+    tools: list[ToolItem] = Field(
+        default_factory=list,
+        description="List of tool names, classes, or dicts with 'name' and optional kwargs for the tool",
+    )
+
+    @field_validator("tools", mode="before")
+    @classmethod
+    def tools_dict_must_have_name(cls, v: Any) -> Any:
+        """Ensure each dict item in tools has a 'name' key."""
+        if not isinstance(v, list):
+            return v
+        result = []
+        for item in v:
+            if isinstance(item, dict):
+                if "name" not in item:
+                    raise ValueError("Tool dict must have 'name' key")
+                result.append(item)
+            else:
+                result.append(item)
+        return result
 
     @field_validator("base_class", mode="before")
     def base_class_import_points_to_file(cls, v: Any) -> Any:
@@ -213,8 +235,7 @@ def default_config_override_validator(cls, data):
     def necessary_fields_validator(self) -> Self:
         if self.llm.api_key is None:
             raise ValueError(f"LLM API key is not provided for agent '{self.name}'")
-        if self.search and self.search.tavily_api_key is None:
-            raise ValueError(f"Search API key is not provided for agent '{self.name}'")
+        # Search API key can be provided via config.search or per-tool in tools array (kwargs)
         if not self.tools:
             raise ValueError(f"Tools are not provided for agent '{self.name}'")
         return self
@@ -229,7 +250,10 @@ def base_class_is_agent(cls, v: Any) -> type[Any]:
 
     def __str__(self) -> str:
         base_class_name = self.base_class.__name__ if isinstance(self.base_class, type) else self.base_class
-        tool_names = [t.__name__ if isinstance(t, type) else t for t in self.tools]
+        tool_names = [
+            t.get("name", t) if isinstance(t, dict) else (t.__name__ if isinstance(t, type) else t)
+            for t in self.tools
+        ]
         return (
             f"AgentDefinition(name='{self.name}', "
             f"base_class={base_class_name}, "
diff --git a/sgr_agent_core/agent_factory.py b/sgr_agent_core/agent_factory.py
@@ -1,7 +1,7 @@
 """Agent Factory for dynamic agent creation from definitions."""
 
 import logging
-from typing import Type, TypeVar
+from typing import Any, Type, TypeVar
 
 import httpx
 from openai import AsyncOpenAI
@@ -123,6 +123,35 @@ def _resolve_tools(cls, tool_names: list[str | type], config: GlobalConfig) -> l
         """
         return [cls._resolve_tool(tool_name, config) for tool_name in tool_names]
 
+    @classmethod
+    def _resolve_tools_with_configs(
+        cls, tools_spec: list[Any], config: GlobalConfig
+    ) -> tuple[list[type[BaseTool]], dict[str, dict[str, Any]]]:
+        """Resolve tools from spec (str, type, or dict with 'name' + kwargs).
+
+        Args:
+            tools_spec: List of tool names, classes, or dicts with 'name' and optional kwargs
+            config: Global configuration containing tool definitions
+
+        Returns:
+            Tuple of (list of tool classes, dict of tool_name -> kwargs for each tool)
+        """
+        toolkit: list[type[BaseTool]] = []
+        tool_configs: dict[str, dict[str, Any]] = {}
+        for item in tools_spec:
+            if isinstance(item, dict):
+                name = item["name"]
+                kwargs = {k: v for k, v in item.items() if k not in ("name", "type", "base_class")}
+                tool_class = cls._resolve_tool(name, config)
+                toolkit.append(tool_class)
+                tool_configs[tool_class.tool_name] = kwargs
+            else:
+                tool_class = cls._resolve_tool(item, config)
+                toolkit.append(tool_class)
+                if tool_class.tool_name not in tool_configs:
+                    tool_configs[tool_class.tool_name] = {}
+        return toolkit, tool_configs
+
     @classmethod
     async def create(cls, agent_def: AgentDefinition, task_messages: list[ChatCompletionMessageParam]) -> Agent:
         """Create an agent instance from a definition.
@@ -165,8 +194,8 @@ async def create(cls, agent_def: AgentDefinition, task_messages: list[ChatComple
             logger.error(error_msg)
             raise ValueError(error_msg)
         mcp_tools: list = await MCP2ToolConverter.build_tools_from_mcp(agent_def.mcp)
-        config = GlobalConfig()
-        tools = cls._resolve_tools(agent_def.tools, config)
+        global_config = GlobalConfig()
+        tools, tool_configs = cls._resolve_tools_with_configs(agent_def.tools, global_config)
         tools.extend(mcp_tools)
 
         try:
@@ -180,6 +209,7 @@ async def create(cls, agent_def: AgentDefinition, task_messages: list[ChatComple
                 task_messages=task_messages,
                 def_name=agent_def.name,
                 toolkit=tools,
+                tool_configs=tool_configs,
                 openai_client=cls._create_client(agent_def.llm),
                 agent_config=agent_def,
                 **agent_kwargs,
diff --git a/sgr_agent_core/agents/sgr_agent.py b/sgr_agent_core/agents/sgr_agent.py
@@ -83,7 +83,9 @@ async def _select_action_phase(self, reasoning: NextStepToolStub) -> BaseTool:
         return tool
 
     async def _action_phase(self, tool: BaseTool) -> str:
-        result = await tool(self._context, self.config)
+        result = await tool(
+            self._context, self.config, **self.tool_configs.get(tool.tool_name, {})
+        )
         self.conversation.append(
             {"role": "tool", "content": result, "tool_call_id": f"{self._context.iteration}-action"}
         )
diff --git a/sgr_agent_core/agents/sgr_tool_calling_agent.py b/sgr_agent_core/agents/sgr_tool_calling_agent.py
@@ -124,7 +124,9 @@ async def _select_action_phase(self, reasoning: ReasoningTool) -> BaseTool:
         return tool
 
     async def _action_phase(self, tool: BaseTool) -> str:
-        result = await tool(self._context, self.config)
+        result = await tool(
+            self._context, self.config, **self.tool_configs.get(tool.tool_name, {})
+        )
         self.conversation.append(
             {"role": "tool", "content": result, "tool_call_id": f"{self._context.iteration}-action"}
         )
diff --git a/sgr_agent_core/agents/tool_calling_agent.py b/sgr_agent_core/agents/tool_calling_agent.py
@@ -74,7 +74,9 @@ async def _select_action_phase(self, reasoning=None) -> BaseTool:
         return tool
 
     async def _action_phase(self, tool: BaseTool) -> str:
-        result = await tool(self._context, self.config)
+        result = await tool(
+            self._context, self.config, **self.tool_configs.get(tool.tool_name, {})
+        )
         self.conversation.append(
             {"role": "tool", "content": result, "tool_call_id": f"{self._context.iteration}-action"}
         )
diff --git a/sgr_agent_core/base_agent.py b/sgr_agent_core/base_agent.py
@@ -41,6 +41,7 @@ def __init__(
         agent_config: AgentConfig,
         toolkit: list[Type[BaseTool]],
         def_name: str | None = None,
+        tool_configs: dict[str, dict] | None = None,
         **kwargs: dict,
     ):
         self.id = f"{def_name or self.name}_{uuid.uuid4()}"
@@ -49,6 +50,7 @@ def __init__(
         self.creation_time = datetime.now()
         self.task_messages = task_messages
         self.toolkit = toolkit
+        self.tool_configs = tool_configs or {}
 
         self._context = AgentContext()
         self.conversation = []
diff --git a/sgr_agent_core/services/tavily_search.py b/sgr_agent_core/services/tavily_search.py
@@ -1,12 +1,32 @@
 import logging
+from typing import Any
 
 from tavily import AsyncTavilyClient
 
-from sgr_agent_core.agent_definition import SearchConfig
+from sgr_agent_core.agent_definition import AgentConfig, SearchConfig
 from sgr_agent_core.models import SourceData
 
 logger = logging.getLogger(__name__)
 
+SEARCH_CONFIG_KEYS = (
+    "tavily_api_key",
+    "tavily_api_base_url",
+    "max_searches",
+    "max_results",
+    "content_limit",
+)
+
+
+def search_config_from_kwargs(config: AgentConfig | None, kwargs: dict[str, Any]) -> SearchConfig:
+    """Build SearchConfig from config.search and tool kwargs (kwargs override).
+
+    Used by WebSearchTool and ExtractPageContentTool to get search settings
+    from the tools array config (kwargs) with fallback to agent config.search.
+    """
+    base = config.search.model_dump() if config and config.search else {}
+    overrides = {k: v for k, v in kwargs.items() if k in SEARCH_CONFIG_KEYS and v is not None}
+    return SearchConfig(**{**base, **overrides})
+
 
 class TavilySearchService:
     def __init__(self, search_config: SearchConfig):
diff --git a/sgr_agent_core/tools/extract_page_content_tool.py b/sgr_agent_core/tools/extract_page_content_tool.py
@@ -1,12 +1,13 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from pydantic import Field
 
 from sgr_agent_core.base_tool import BaseTool
 from sgr_agent_core.services import TavilySearchService
+from sgr_agent_core.services.tavily_search import search_config_from_kwargs
 
 if TYPE_CHECKING:
     from sgr_agent_core.agent_definition import AgentConfig
@@ -35,12 +36,16 @@ class ExtractPageContentTool(BaseTool):
     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)
 
-    async def __call__(self, context: AgentContext, config: AgentConfig, **_) -> str:
-        """Extract full content from specified URLs."""
+    async def __call__(self, context: AgentContext, config: AgentConfig, **kwargs: Any) -> str:
+        """Extract full content from specified URLs.
 
+        Search settings (e.g. tavily_api_key, content_limit) are taken from kwargs
+        (tool config) with fallback to config.search.
+        """
+        search_config = search_config_from_kwargs(config, dict(kwargs))
         logger.info(f"📄 Extracting content from {len(self.urls)} URLs")
 
-        self._search_service = TavilySearchService(config.search)
+        self._search_service = TavilySearchService(search_config)
         sources = await self._search_service.extract(urls=self.urls)
 
         # Update existing sources instead of overwriting
@@ -62,7 +67,7 @@ async def __call__(self, context: AgentContext, config: AgentConfig, **_) -> str
             if url in context.sources:
                 source = context.sources[url]
                 if source.full_content:
-                    content_preview = source.full_content[: config.search.content_limit]
+                    content_preview = source.full_content[: search_config.content_limit]
                     formatted_result += (
                         f"{str(source)}\n\n**Full Content:**\n"
                         f"{content_preview}\n\n"
diff --git a/sgr_agent_core/tools/web_search_tool.py b/sgr_agent_core/tools/web_search_tool.py
diff --git a/tests/test_agent_definition.py b/tests/test_agent_definition.py
diff --git a/tests/test_agent_factory.py b/tests/test_agent_factory.py
diff --git a/tests/test_tools.py b/tests/test_tools.py

Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,10 @@ async def _prepare_tools(self) -> Type[NextStepToolStub]:`
`61`	`61`	`tools -= {`
`62`	`62`	`ClarificationTool,`
`63`	`63`	`}`
`64`		`- if self._context.searches_used >= self.config.search.max_searches:`
	`64`	`+ max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (`
	`65`	`+ self.config.search.max_searches if self.config.search else 4`
	`66`	`+ )`
	`67`	`+ if self._context.searches_used >= max_searches:`
`65`	`68`	`tools -= {`
`66`	`69`	`WebSearchTool,`
`67`	`70`	`}`
`@@ -102,7 +105,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:`
`102`	`105`	`tools -= {`
`103`	`106`	`ClarificationTool,`
`104`	`107`	`}`
`105`		`- if self._context.searches_used >= self.config.search.max_searches:`
	`108`	`+ max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (`
	`109`	`+ self.config.search.max_searches if self.config.search else 4`
	`110`	`+ )`
	`111`	`+ if self._context.searches_used >= max_searches:`
`106`	`112`	`tools -= {`
`107`	`113`	`WebSearchTool,`
`108`	`114`	`}`
`@@ -144,7 +150,10 @@ async def _prepare_tools(self) -> list[ChatCompletionFunctionToolParam]:`
`144`	`150`	`tools -= {`
`145`	`151`	`ClarificationTool,`
`146`	`152`	`}`
`147`		`- if self._context.searches_used >= self.config.search.max_searches:`
	`153`	`+ max_searches = self.tool_configs.get(WebSearchTool.tool_name, {}).get("max_searches") or (`
	`154`	`+ self.config.search.max_searches if self.config.search else 4`
	`155`	`+ )`
	`156`	`+ if self._context.searches_used >= max_searches:`
`148`	`157`	`tools -= {`
`149`	`158`	`WebSearchTool,`
`150`	`159`	`}`