Pass config to tool constructor

Author: snow-ghost

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"

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"

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)

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,
             }

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,
             }

sgr_agent_core/agent_definition.py

@@ -10,6 +10,8 @@
 from fastmcp.mcp_config import MCPConfig
 from pydantic import BaseModel, Field, FilePath, ImportString, computed_field, field_validator, model_validator
 
+# Element of AgentDefinition.tools: name (str), class (type), or dict with "name" + kwargs
+ToolItem = Union[str, type[Any], dict[str, Any]]
 logger = logging.getLogger(__name__)
 
 
@@ -175,7 +177,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 +234,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 +249,9 @@ 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}, "

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,

sgr_agent_core/agents/sgr_agent.py

@@ -83,7 +83,7 @@ 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"}
         )

sgr_agent_core/agents/sgr_tool_calling_agent.py

@@ -124,7 +124,7 @@ 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"}
         )

sgr_agent_core/agents/tool_calling_agent.py

@@ -74,7 +74,7 @@ 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"}
         )