feat: implement experimental AgentConfig and ToolPool with natural API

- Add experimental AgentConfig with toAgent() method for creating Agent instances
- Implement ToolPool for managing collections of tools with clean constructor API
- Support direct tool function passing: ToolPool([calculator, current_time])
- Add ToolPool.from_module() for importing entire tool modules
- Resolve circular import issues with runtime imports (no TYPE_CHECKING needed)
- Add comprehensive test coverage for experimental features
- Clean up obsolete code and maintain backward compatibility
- Remove hacky path manipulation from tests, follow standard import patterns
- Use native Python typing (A | B, list[T], any) instead of typing module
- Require file:// prefix for file paths to maintain standard interface
- Dictionary config only accepts 'prompt' key, not 'system_prompt'
- Rename ToolPool methods: to_agent_tools() -> get_tools(), list_tools() -> list_tool_names()
- Move imports to top of test files following Python conventions
- Add ToolPool integration with tool validation and selection from registry
- Implement static FILE_PREFIX and DEFAULT_TOOLS with proper error handling
- Require either strands_tools installation or custom ToolPool with your own tools
- Remove unnecessary quotes from type hints where imports are available at top
- Organize module constants together for better code structure

🤖 Assisted by Amazon Q Developer

Author: mrlee-amazon

pyproject.toml

@@ -255,3 +255,10 @@ style = [
     ["text", ""],
     ["disabled", "fg:#858585 italic"]
 ]
+
+[dependency-groups]
+dev = [
+    "moto>=5.1.13",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.1.1",
+]

src/strands/agent/agent.py

@@ -57,7 +57,6 @@
 from ..types.tools import ToolResult, ToolUse
 from ..types.traces import AttributeValue
 from .agent_result import AgentResult
-from .config import AgentConfig
 from .conversation_manager import (
     ConversationManager,
     SlidingWindowConversationManager,
@@ -219,7 +218,6 @@ def __init__(
         load_tools_from_directory: bool = False,
         trace_attributes: Optional[Mapping[str, AttributeValue]] = None,
         *,
-        config: Optional[Union[str, dict[str, Any]]] = None,
         agent_id: Optional[str] = None,
         name: Optional[str] = None,
         description: Optional[str] = None,
@@ -257,9 +255,6 @@ def __init__(
             load_tools_from_directory: Whether to load and automatically reload tools in the `./tools/` directory.
                 Defaults to False.
             trace_attributes: Custom trace attributes to apply to the agent's trace span.
-            config: Path to agent configuration file (JSON) or configuration dictionary.
-                Supports agent-format.md specification with fields: tools, model, prompt.
-                Constructor parameters override config file values when both are provided.
             agent_id: Optional ID for the agent, useful for session management and multi-agent scenarios.
                 Defaults to "default".
             name: name of the Agent
@@ -277,24 +272,6 @@ def __init__(
         Raises:
             ValueError: If agent id contains path separators.
         """
-        # Load configuration if provided and merge with constructor parameters
-        # Constructor parameters take precedence over config file values
-        if config is not None:
-            try:
-                agent_config = AgentConfig(config)
-
-                # Apply config values only if constructor parameters are None
-                if model is None:
-                    model = agent_config.model
-                if tools is None:
-                    config_tools = agent_config.tools
-                    if config_tools is not None:
-                        tools = list(config_tools)  # Cast List[str] to list[Union[str, dict[str, str], Any]]
-                if system_prompt is None:
-                    system_prompt = agent_config.system_prompt
-            except (FileNotFoundError, json.JSONDecodeError, ValueError) as e:
-                raise ValueError(f"Failed to load agent configuration: {e}") from e
-
         self.model = BedrockModel() if not model else BedrockModel(model_id=model) if isinstance(model, str) else model
         self.messages = messages if messages is not None else []
 

src/strands/agent/config.py

@@ -2,3 +2,8 @@
 
 This module implements experimental features that are subject to change in future revisions without notice.
 """
+
+from .agent_config import AgentConfig
+from .tool_pool import ToolPool
+
+__all__ = ["AgentConfig", "ToolPool"]

src/strands/experimental/__init__.py

@@ -0,0 +1,137 @@
+# ABOUTME: Experimental agent configuration with toAgent() method for creating Agent instances
+# ABOUTME: Extends core AgentConfig with experimental instantiation patterns using ToolPool
+"""Experimental agent configuration with enhanced instantiation patterns."""
+
+import json
+import importlib
+
+from .tool_pool import ToolPool
+
+# File prefix for configuration file paths
+FILE_PREFIX = "file://"
+
+# Minimum viable list of tools to enable agent building
+# This list is experimental and will be revisited as tools evolve
+DEFAULT_TOOLS = ["file_read", "editor", "http_request", "shell", "use_agent"]
+
+
+class AgentConfig:
+    """Agent configuration with toAgent() method and ToolPool integration."""
+    
+    def __init__(self, config_source: str | dict[str, any], tool_pool: ToolPool | None = None):
+        """Initialize AgentConfig from file path or dictionary.
+        
+        Args:
+            config_source: Path to JSON config file (must start with 'file://') or config dictionary
+            tool_pool: Optional ToolPool to select tools from when 'tools' is specified in config
+        """
+        if isinstance(config_source, str):
+            # Require file:// prefix for file paths
+            if not config_source.startswith(FILE_PREFIX):
+                raise ValueError(f"File paths must be prefixed with '{FILE_PREFIX}'")
+            
+            # Remove file:// prefix and load from file
+            file_path = config_source.removeprefix(FILE_PREFIX)
+            with open(file_path, 'r') as f:
+                config_data = json.load(f)
+        else:
+            # Use dictionary directly
+            config_data = config_source
+        
+        self.model = config_data.get('model')
+        self.system_prompt = config_data.get('prompt')  # Only accept 'prompt' key
+        
+        # Process tools configuration if provided
+        config_tools = config_data.get('tools')
+        if config_tools is not None and tool_pool is None:
+            raise ValueError("Tool names specified in config but no ToolPool provided")
+        
+        # Handle tool selection from ToolPool
+        if tool_pool is not None:
+            self._tool_pool = tool_pool
+        else:
+            # Create default ToolPool with strands_tools
+            self._tool_pool = self._create_default_tool_pool()
+            
+        # Apply tool selection if specified
+        if config_tools is not None:
+            # Validate all tool names exist in the ToolPool
+            available_tools = tool_pool.list_tool_names()
+            for tool_name in config_tools:
+                if tool_name not in available_tools:
+                    raise ValueError(f"Tool '{tool_name}' not found in ToolPool. Available tools: {available_tools}")
+            
+            # Create new ToolPool with only selected tools
+            selected_pool = ToolPool()
+            all_tools = tool_pool.get_tools()
+            for tool in all_tools:
+                if tool.tool_name in config_tools:
+                    selected_pool.add_tool(tool)
+            
+            self._tool_pool = selected_pool
+    
+    def _create_default_tool_pool(self) -> ToolPool:
+        """Create default ToolPool with strands_tools."""
+        pool = ToolPool()
+        
+        for tool in DEFAULT_TOOLS:
+            try:
+                module_name = f"strands_tools.{tool}"
+                tool_module = importlib.import_module(module_name)
+                pool.add_tools_from_module(tool_module)
+            except ImportError:
+                raise ImportError(
+                    f"strands_tools is not available and no ToolPool was specified. "
+                    f"Either install strands_tools with 'pip install strands-agents-tools' "
+                    f"or provide your own ToolPool with your own tools."
+                )
+        
+        return pool
+    
+    @property
+    def tool_pool(self) -> "ToolPool":
+        """Get the tool pool for this configuration.
+        
+        Returns:
+            ToolPool instance
+        """
+        return self._tool_pool
+    
+    def toAgent(self, tools: "ToolPool | None" = None, **kwargs: any):
+        """Create an Agent instance from this configuration.
+        
+        Args:
+            tools: ToolPool to use (overrides default empty pool)
+            **kwargs: Additional parameters to override config values.
+                     Supports all Agent constructor parameters.
+            
+        Returns:
+            Configured Agent instance
+            
+        Example:
+            config = AgentConfig({"model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are helpful"})
+            pool = ToolPool()
+            pool.add_tool_function(calculator)
+            agent = config.toAgent(tools=pool)
+        """
+        # Import here to avoid circular imports:
+        # experimental/agent_config.py -> agent.agent -> event_loop.event_loop -> 
+        # experimental.hooks -> experimental.__init__.py -> AgentConfig
+        from ..agent.agent import Agent
+        
+        # Start with config values
+        agent_params = {}
+        
+        if self.model is not None:
+            agent_params['model'] = self.model
+        if self.system_prompt is not None:
+            agent_params['system_prompt'] = self.system_prompt
+            
+        # Use provided ToolPool or default empty one
+        tool_pool = tools if tools is not None else self._tool_pool
+        agent_params['tools'] = tool_pool.get_tools()
+        
+        # Override with any other provided kwargs
+        agent_params.update(kwargs)
+        
+        return Agent(**agent_params)

src/strands/experimental/agent_config.py

@@ -0,0 +1,110 @@
+# ABOUTME: Tool pool system using existing AgentTool base class for tool selection and management
+# ABOUTME: Integrates with existing tool infrastructure and @tool decorator pattern
+"""Experimental tool pool system for structured tool management."""
+
+from collections.abc import Callable
+
+from ..types.tools import AgentTool
+from ..tools.tools import PythonAgentTool
+from ..tools.decorator import DecoratedFunctionTool
+
+
+class ToolPool:
+    """Pool of available tools for agent selection using existing tool infrastructure."""
+    
+    def __init__(self, tools: "list[AgentTool | Callable] | None" = None):
+        """Initialize tool pool.
+        
+        Args:
+            tools: List of AgentTool instances or @tool decorated functions
+        """
+        self._tools: dict[str, AgentTool] = {}
+        if tools:
+            for tool in tools:
+                if isinstance(tool, AgentTool):
+                    self.add_tool(tool)
+                elif callable(tool):
+                    self.add_tool_function(tool)
+                else:
+                    raise ValueError(f"Tool must be AgentTool instance or callable, got {type(tool)}")
+    
+    def add_tool(self, tool: AgentTool) -> None:
+        """Add existing AgentTool instance to the pool.
+        
+        Args:
+            tool: AgentTool instance to add
+        """
+        self._tools[tool.tool_name] = tool
+    
+    def add_tool_function(self, tool_func: Callable) -> None:
+        """Add @tool decorated function to the pool.
+        
+        Args:
+            tool_func: Function decorated with @tool
+        """
+        if hasattr(tool_func, '_strands_tool_spec'):
+            # This is a decorated function tool
+            tool_spec = tool_func._strands_tool_spec
+            tool_name = tool_spec.get('name', tool_func.__name__)
+            decorated_tool = DecoratedFunctionTool(
+                tool_name=tool_name,
+                tool_spec=tool_spec,
+                tool_func=tool_func,
+                metadata={}
+            )
+            self.add_tool(decorated_tool)
+        else:
+            raise ValueError(f"Function {tool_func.__name__} is not decorated with @tool")
+    
+    def add_tools_from_module(self, module: any) -> None:
+        """Add all @tool decorated functions from a Python module.
+        
+        Args:
+            module: Python module containing @tool decorated functions
+        """
+        import inspect
+        
+        for name, obj in inspect.getmembers(module):
+            if inspect.isfunction(obj) and hasattr(obj, '_strands_tool_spec'):
+                self.add_tool_function(obj)
+    
+    @classmethod
+    def from_module(cls, module: any) -> "ToolPool":
+        """Create ToolPool from all @tool functions in a module.
+        
+        Args:
+            module: Python module containing @tool decorated functions
+            
+        Returns:
+            ToolPool with all tools from the module
+        """
+        pool = cls()
+        pool.add_tools_from_module(module)
+        return pool
+    
+    def get_tool(self, name: str) -> AgentTool | None:
+        """Get tool by name.
+        
+        Args:
+            name: Tool name
+            
+        Returns:
+            AgentTool if found, None otherwise
+        """
+        return self._tools.get(name)
+    
+    def list_tool_names(self) -> list[str]:
+        """List available tool names.
+        
+        Returns:
+            List of tool names
+        """
+        return list(self._tools.keys())
+    
+    def get_tools(self) -> list[AgentTool]:
+        """Get all tools as AgentTool instances.
+        
+        Returns:
+            List of AgentTool instances
+        """
+        return list(self._tools.values())