Add agent configuration support with JSON/dict configs and tool name resolution

mrlee-amazon · mrlee-amazon · commit 16e6b24f9843 · 2025-09-23T18:08:02.000-04:00
- Add AgentConfig class for loading configuration from JSON files or dicts
- Support model, prompt, and tools configuration options
- Update tool registry to resolve tool names from strands_tools package
- Maintain backward compatibility with existing Agent constructor
- Add comprehensive tests for configuration loading and validation
- Fix all linting, type checking, and formatting issues
diff --git a/src/strands/agent/agent.py b/src/strands/agent/agent.py
@@ -57,6 +57,7 @@
 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,
@@ -218,6 +219,7 @@ 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,
@@ -255,6 +257,9 @@ 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
@@ -272,6 +277,24 @@ 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 []
 
diff --git a/src/strands/agent/config.py b/src/strands/agent/config.py
@@ -0,0 +1,64 @@
+"""Agent configuration parser for agent-format.md support."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+
+class AgentConfig:
+    """Parser for agent configuration files following agent-format.md specification."""
+
+    def __init__(self, config_source: Union[str, Dict[str, Any]]):
+        """Initialize agent configuration.
+
+        Args:
+            config_source: Path to JSON config file or config dictionary
+        """
+        if isinstance(config_source, str):
+            self.config = self._load_from_file(config_source)
+        elif isinstance(config_source, dict):
+            self.config = config_source.copy()
+        else:
+            raise ValueError("config_source must be a file path string or dictionary")
+
+    def _load_from_file(self, file_path: str) -> Dict[str, Any]:
+        """Load configuration from JSON file.
+
+        Args:
+            file_path: Path to the configuration file
+
+        Returns:
+            Parsed configuration dictionary
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            json.JSONDecodeError: If config file contains invalid JSON
+        """
+        path = Path(file_path).expanduser().resolve()
+
+        if not path.exists():
+            raise FileNotFoundError(f"Agent config file not found: {file_path}")
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                if not isinstance(data, dict):
+                    raise ValueError(f"Config file {file_path} must contain a JSON object")
+                return data
+        except json.JSONDecodeError as e:
+            raise json.JSONDecodeError(f"Invalid JSON in config file {file_path}: {e.msg}", e.doc, e.pos) from e
+
+    @property
+    def tools(self) -> Optional[List[str]]:
+        """Get tools configuration."""
+        return self.config.get("tools")
+
+    @property
+    def model(self) -> Optional[str]:
+        """Get model configuration."""
+        return self.config.get("model")
+
+    @property
+    def system_prompt(self) -> Optional[str]:
+        """Get system prompt from 'prompt' field."""
+        return self.config.get("prompt")
diff --git a/src/strands/tools/registry.py b/src/strands/tools/registry.py
@@ -55,8 +55,23 @@ def process_tools(self, tools: List[Any]) -> List[str]:
         tool_names = []
 
         def add_tool(tool: Any) -> None:
-            # Case 1: String file path
+            # Case 1: String - could be file path or tool name from strands_tools
             if isinstance(tool, str):
+                # First try to import from strands_tools.{tool_name}
+                try:
+                    import importlib
+
+                    module_name = f"strands_tools.{tool}"
+                    tool_module = importlib.import_module(module_name)
+                    if hasattr(tool_module, tool):
+                        tool_obj = getattr(tool_module, tool)
+                        # Recursively process the imported tool object
+                        add_tool(tool_obj)
+                        return
+                except (ImportError, AttributeError):
+                    pass
+
+                # If not found in strands_tools, treat as file path
                 # Extract tool name from path
                 tool_name = os.path.basename(tool).split(".")[0]
                 self.load_tool_from_filepath(tool_name=tool_name, tool_path=tool)
diff --git a/tests/strands/agent/test_agent_config.py b/tests/strands/agent/test_agent_config.py
@@ -0,0 +1,239 @@
+"""Tests for agent configuration functionality."""
+
+import json
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from strands.agent import Agent
+from strands.agent.config import AgentConfig
+
+
+class TestBackwardCompatibility:
+    """Test that existing Agent usage continues to work."""
+
+    def test_existing_agent_usage_still_works(self):
+        """Test that Agent can be created without config parameter."""
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock:
+            # This should work exactly as before - no config parameter
+            agent = Agent(model="us.anthropic.claude-3-haiku-20240307-v1:0", system_prompt="You are helpful")
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-3-haiku-20240307-v1:0")
+            assert agent.system_prompt == "You are helpful"
+            assert agent.name == "Strands Agents"  # Default name
+
+
+class TestAgentConfig:
+    """Test AgentConfig class functionality."""
+
+    def test_load_from_dict(self):
+        """Test loading config from dictionary."""
+        config_dict = {
+            "tools": ["calculator", "shell"],
+            "model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+            "prompt": "You are a helpful assistant",
+        }
+
+        config = AgentConfig(config_dict)
+
+        assert config.tools == ["calculator", "shell"]
+        assert config.model == "us.anthropic.claude-sonnet-4-20250514-v1:0"
+        assert config.system_prompt == "You are a helpful assistant"
+
+    def test_load_from_file(self):
+        """Test loading config from JSON file."""
+        config_dict = {
+            "tools": ["./tools/shell_tool.py"],
+            "model": "us.anthropic.claude-3-haiku-20240307-v1:0",
+            "prompt": "You are a coding assistant",
+        }
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump(config_dict, f)
+            temp_path = f.name
+
+        try:
+            config = AgentConfig(temp_path)
+
+            assert config.tools == ["./tools/shell_tool.py"]
+            assert config.model == "us.anthropic.claude-3-haiku-20240307-v1:0"
+            assert config.system_prompt == "You are a coding assistant"
+        finally:
+            Path(temp_path).unlink()
+
+    def test_missing_file_error(self):
+        """Test error handling for missing config file."""
+        with pytest.raises(FileNotFoundError, match="Agent config file not found"):
+            AgentConfig("/nonexistent/path/config.json")
+
+    def test_invalid_json_error(self):
+        """Test error handling for invalid JSON."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write("{ invalid json }")
+            temp_path = f.name
+
+        try:
+            with pytest.raises(json.JSONDecodeError, match="Invalid JSON in config file"):
+                AgentConfig(temp_path)
+        finally:
+            Path(temp_path).unlink()
+
+    def test_invalid_config_source_type(self):
+        """Test error handling for invalid config source type."""
+        with pytest.raises(ValueError, match="config_source must be a file path string or dictionary"):
+            AgentConfig(123)
+
+    def test_missing_fields(self):
+        """Test handling of missing configuration fields."""
+        config = AgentConfig({})
+
+        assert config.tools is None
+        assert config.model is None
+        assert config.system_prompt is None
+
+
+class TestAgentWithConfig:
+    """Test Agent class with configuration support."""
+
+    def test_agent_with_config_dict(self):
+        """Test Agent initialization with config dictionary."""
+        # Mock the strands_tools import
+        mock_tool = MagicMock()
+        mock_tool.name = "file_read"
+        mock_tool.spec = {"name": "file_read", "description": "Mock file read tool"}
+
+        config = {
+            "tools": ["file_read"],
+            "model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+            "prompt": "You are helpful",
+        }
+
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock, patch("importlib.import_module") as mock_import:
+            # Mock the strands_tools.file_read module
+            mock_module = MagicMock()
+            mock_module.file_read = mock_tool
+
+            def side_effect(module_name):
+                if module_name == "strands_tools.file_read":
+                    return mock_module
+                raise ImportError(f"No module named '{module_name}'")
+
+            mock_import.side_effect = side_effect
+
+            agent = Agent(config=config)
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
+            assert agent.system_prompt == "You are helpful"
+            assert len(agent.tool_registry.get_all_tool_specs()) == 1
+
+    def test_agent_with_config_file(self):
+        """Test Agent initialization with config file."""
+        # Mock the strands_tools import
+        mock_tool = MagicMock()
+        mock_tool.name = "shell"
+        mock_tool.spec = {"name": "shell", "description": "Mock shell tool"}
+
+        config_dict = {
+            "tools": ["shell"],
+            "model": "us.anthropic.claude-3-haiku-20240307-v1:0",
+            "prompt": "You are a coding assistant",
+        }
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump(config_dict, f)
+            temp_path = f.name
+
+        try:
+            with (
+                patch("strands.agent.agent.BedrockModel") as mock_bedrock,
+                patch("importlib.import_module") as mock_import,
+            ):
+                # Mock the strands_tools.shell module
+                mock_module = MagicMock()
+                mock_module.shell = mock_tool
+                mock_import.return_value = mock_module
+
+                agent = Agent(config=temp_path)
+
+                mock_bedrock.assert_called_with(model_id="us.anthropic.claude-3-haiku-20240307-v1:0")
+                assert agent.system_prompt == "You are a coding assistant"
+                assert len(agent.tool_registry.get_all_tool_specs()) == 1
+        finally:
+            Path(temp_path).unlink()
+
+    def test_constructor_params_override_config(self):
+        """Test that constructor parameters override config values."""
+        # Mock the strands_tools import
+        mock_tool = MagicMock()
+        mock_tool.name = "file_read"
+        mock_tool.spec = {"name": "file_read", "description": "Mock file read tool"}
+
+        config = {
+            "tools": ["file_read"],
+            "model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+            "prompt": "Config prompt",
+        }
+
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock, patch("importlib.import_module") as mock_import:
+            # Mock the strands_tools.file_read module
+            mock_module = MagicMock()
+            mock_module.file_read = mock_tool
+            mock_import.return_value = mock_module
+
+            agent = Agent(
+                config=config, model="us.anthropic.claude-3-haiku-20240307-v1:0", system_prompt="Constructor prompt"
+            )
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-3-haiku-20240307-v1:0")
+            assert agent.system_prompt == "Constructor prompt"
+            assert len(agent.tool_registry.get_all_tool_specs()) == 1
+
+    def test_config_values_used_when_constructor_params_none(self):
+        """Test that config values are used when constructor parameters are None."""
+        # Mock the strands_tools import
+        mock_tool = MagicMock()
+        mock_tool.name = "file_write"
+        mock_tool.spec = {"name": "file_write", "description": "Mock file write tool"}
+
+        config = {
+            "tools": ["file_write"],
+            "model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+            "prompt": "Config prompt",
+        }
+
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock, patch("importlib.import_module") as mock_import:
+            # Mock the strands_tools.file_write module
+            mock_module = MagicMock()
+            mock_module.file_write = mock_tool
+            mock_import.return_value = mock_module
+
+            agent = Agent(config=config, model=None, system_prompt=None)
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
+            assert agent.system_prompt == "Config prompt"
+            assert len(agent.tool_registry.get_all_tool_specs()) == 1
+
+    def test_agent_without_config(self):
+        """Test that Agent works normally without config parameter."""
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock:
+            agent = Agent(model="us.anthropic.claude-3-haiku-20240307-v1:0", system_prompt="Test prompt")
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-3-haiku-20240307-v1:0")
+            assert agent.system_prompt == "Test prompt"
+
+    def test_config_error_handling(self):
+        """Test error handling for invalid config."""
+        with pytest.raises(ValueError, match="Failed to load agent configuration"):
+            Agent(config="/nonexistent/config.json")
+
+    def test_partial_config(self):
+        """Test Agent with partial config (only some fields specified)."""
+        config = {"model": "us.anthropic.claude-sonnet-4-20250514-v1:0"}
+
+        with patch("strands.agent.agent.BedrockModel") as mock_bedrock:
+            agent = Agent(config=config, system_prompt="Constructor prompt")
+
+            mock_bedrock.assert_called_with(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
+            assert agent.system_prompt == "Constructor prompt"
