From a08eb6bacdb1907009f2c8f9597e5242a7f10598 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 11 Sep 2025 20:20:53 -0400 Subject: [PATCH 01/45] Add agent configuration documentation and examples - Create comprehensive configuration guide in user-guide/concepts/agents/configuration.md - Document supported fields: tools, model, prompt - Add usage examples and error handling information - Include parameter precedence and backward compatibility notes - Add configuration page to mkdocs navigation - Create example configuration files for coding assistant and simple agent --- .../agent-configs/coding-assistant.json | 9 ++ docs/examples/agent-configs/simple-agent.json | 4 + .../concepts/agents/configuration.md | 128 ++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 142 insertions(+) create mode 100644 docs/examples/agent-configs/coding-assistant.json create mode 100644 docs/examples/agent-configs/simple-agent.json create mode 100644 docs/user-guide/concepts/agents/configuration.md diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json new file mode 100644 index 00000000..b0b2e290 --- /dev/null +++ b/docs/examples/agent-configs/coding-assistant.json @@ -0,0 +1,9 @@ +{ + "tools": [ + "fs_read", + "fs_write", + "execute_bash" + ], + "model": "claude-3-sonnet", + "prompt": "You are an expert software developer. Help users write clean, efficient, and well-documented code. Always explain your reasoning and provide examples when helpful." +} diff --git a/docs/examples/agent-configs/simple-agent.json b/docs/examples/agent-configs/simple-agent.json new file mode 100644 index 00000000..8e0bcf2a --- /dev/null +++ b/docs/examples/agent-configs/simple-agent.json @@ -0,0 +1,4 @@ +{ + "model": "claude-3-haiku", + "prompt": "You are a helpful assistant." +} diff --git a/docs/user-guide/concepts/agents/configuration.md b/docs/user-guide/concepts/agents/configuration.md new file mode 100644 index 00000000..9b8039ba --- /dev/null +++ b/docs/user-guide/concepts/agents/configuration.md @@ -0,0 +1,128 @@ +# Agent Configuration + +The Strands SDK supports loading agent configuration from JSON files following the [agent-format.md specification](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md) used by Amazon Q Developer CLI. + +## Basic Usage + +You can initialize an Agent using a configuration file: + +```python +from strands import Agent + +# Load from configuration file +agent = Agent(config="/path/to/agent-config.json") + +# Or from a configuration dictionary +config = { + "tools": ["fs_read", "fs_write"], + "model": "claude-3-sonnet", + "prompt": "You are a helpful coding assistant" +} +agent = Agent(config=config) +``` + +## Supported Configuration Fields + +Currently, the following fields from the agent-format.md specification are supported: + +### `tools` +List of tools available to the agent: + +```json +{ + "tools": ["fs_read", "fs_write", "execute_bash"] +} +``` + +### `model` +Model ID to use for the agent: + +```json +{ + "model": "claude-3-sonnet" +} +``` + +### `prompt` +System prompt for the agent (maps to `system_prompt` parameter): + +```json +{ + "prompt": "You are a helpful assistant specialized in Python development" +} +``` + +## Example Configuration File + +Create a file named `my-agent.json`: + +```json +{ + "tools": [ + "fs_read", + "fs_write", + "execute_bash" + ], + "model": "claude-3-sonnet", + "prompt": "You are an expert Python developer. Help users write clean, efficient code." +} +``` + +Then load it in your Python code: + +```python +from strands import Agent + +agent = Agent(config="my-agent.json") +result = agent("Help me write a function to parse JSON files") +print(result.message) +``` + +## Parameter Precedence + +Constructor parameters take precedence over configuration file values: + +```python +# Config file has model: "claude-3-haiku" +# But constructor parameter overrides it +agent = Agent( + config="my-agent.json", + model="claude-3-sonnet" # This takes precedence +) +``` + +## Backward Compatibility + +The configuration feature is fully backward compatible. Existing Agent initialization continues to work unchanged: + +```python +# This still works exactly as before +agent = Agent( + model="claude-3-sonnet", + tools=["fs_read"], + system_prompt="You are helpful" +) +``` + +## Error Handling + +The SDK provides clear error messages for configuration issues: + +```python +try: + agent = Agent(config="/nonexistent/config.json") +except ValueError as e: + print(f"Configuration error: {e}") + # Output: Configuration error: Failed to load agent configuration: Agent config file not found: /nonexistent/config.json +``` + +## Future Enhancements + +Additional fields from the agent-format.md specification may be supported in future releases, including: + +- `mcpServers` - MCP server configurations +- `allowedTools` - Tool permission settings +- `resources` - File and resource access +- `hooks` - Lifecycle event handlers + +For the complete specification, see the [agent-format.md documentation](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md). diff --git a/mkdocs.yml b/mkdocs.yml index 18e6a939..096af65a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,6 +75,7 @@ nav: - Concepts: - Agents: - Agent Loop: user-guide/concepts/agents/agent-loop.md + - Configuration: user-guide/concepts/agents/configuration.md - State: user-guide/concepts/agents/state.md - Session Management: user-guide/concepts/agents/session-management.md - Prompts: user-guide/concepts/agents/prompts.md From f4b3425ed486b6c56c503242a0500b7b63b531e7 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 11 Sep 2025 20:29:11 -0400 Subject: [PATCH 02/45] Fix model ID format in documentation to align with Strands expectations - Update all documentation examples to use full Bedrock model IDs - Change from simplified names like 'claude-3-sonnet' to full format like 'us.anthropic.claude-sonnet-4-20250514-v1:0' - Update example configuration files to use correct format - Ensure compatibility with Strands BedrockModel expectations --- docs/examples/agent-configs/coding-assistant.json | 2 +- docs/examples/agent-configs/simple-agent.json | 2 +- docs/user-guide/concepts/agents/configuration.md | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json index b0b2e290..5bf480f2 100644 --- a/docs/examples/agent-configs/coding-assistant.json +++ b/docs/examples/agent-configs/coding-assistant.json @@ -4,6 +4,6 @@ "fs_write", "execute_bash" ], - "model": "claude-3-sonnet", + "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert software developer. Help users write clean, efficient, and well-documented code. Always explain your reasoning and provide examples when helpful." } diff --git a/docs/examples/agent-configs/simple-agent.json b/docs/examples/agent-configs/simple-agent.json index 8e0bcf2a..080fe346 100644 --- a/docs/examples/agent-configs/simple-agent.json +++ b/docs/examples/agent-configs/simple-agent.json @@ -1,4 +1,4 @@ { - "model": "claude-3-haiku", + "model": "us.anthropic.claude-3-haiku-20240307-v1:0", "prompt": "You are a helpful assistant." } diff --git a/docs/user-guide/concepts/agents/configuration.md b/docs/user-guide/concepts/agents/configuration.md index 9b8039ba..1fcf8fd2 100644 --- a/docs/user-guide/concepts/agents/configuration.md +++ b/docs/user-guide/concepts/agents/configuration.md @@ -15,7 +15,7 @@ agent = Agent(config="/path/to/agent-config.json") # Or from a configuration dictionary config = { "tools": ["fs_read", "fs_write"], - "model": "claude-3-sonnet", + "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are a helpful coding assistant" } agent = Agent(config=config) @@ -35,11 +35,11 @@ List of tools available to the agent: ``` ### `model` -Model ID to use for the agent: +Model ID to use for the agent (must be full Bedrock model ID): ```json { - "model": "claude-3-sonnet" + "model": "us.anthropic.claude-sonnet-4-20250514-v1:0" } ``` @@ -63,7 +63,7 @@ Create a file named `my-agent.json`: "fs_write", "execute_bash" ], - "model": "claude-3-sonnet", + "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert Python developer. Help users write clean, efficient code." } ``` @@ -83,11 +83,11 @@ print(result.message) Constructor parameters take precedence over configuration file values: ```python -# Config file has model: "claude-3-haiku" +# Config file has model: "us.anthropic.claude-3-haiku-20240307-v1:0" # But constructor parameter overrides it agent = Agent( config="my-agent.json", - model="claude-3-sonnet" # This takes precedence + model="us.anthropic.claude-sonnet-4-20250514-v1:0" # This takes precedence ) ``` @@ -98,7 +98,7 @@ The configuration feature is fully backward compatible. Existing Agent initializ ```python # This still works exactly as before agent = Agent( - model="claude-3-sonnet", + model="us.anthropic.claude-sonnet-4-20250514-v1:0", tools=["fs_read"], system_prompt="You are helpful" ) From e47979baca1236142fcacd5ac128f9b5b34d19c3 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 11 Sep 2025 20:35:02 -0400 Subject: [PATCH 03/45] Fix tool names to match strands-agents/tools specifications - Update from fs_read/fs_write to file_read/file_write - Update from execute_bash to shell - Align all documentation examples with authoritative tool names from strands-agents/tools repo --- docs/examples/agent-configs/coding-assistant.json | 6 +++--- docs/user-guide/concepts/agents/configuration.md | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json index 5bf480f2..84ebfa3e 100644 --- a/docs/examples/agent-configs/coding-assistant.json +++ b/docs/examples/agent-configs/coding-assistant.json @@ -1,8 +1,8 @@ { "tools": [ - "fs_read", - "fs_write", - "execute_bash" + "file_read", + "file_write", + "shell" ], "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert software developer. Help users write clean, efficient, and well-documented code. Always explain your reasoning and provide examples when helpful." diff --git a/docs/user-guide/concepts/agents/configuration.md b/docs/user-guide/concepts/agents/configuration.md index 1fcf8fd2..46cd8c38 100644 --- a/docs/user-guide/concepts/agents/configuration.md +++ b/docs/user-guide/concepts/agents/configuration.md @@ -14,7 +14,7 @@ agent = Agent(config="/path/to/agent-config.json") # Or from a configuration dictionary config = { - "tools": ["fs_read", "fs_write"], + "tools": ["shell", "calculator"], "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are a helpful coding assistant" } @@ -30,7 +30,7 @@ List of tools available to the agent: ```json { - "tools": ["fs_read", "fs_write", "execute_bash"] + "tools": ["file_read", "file_write", "shell"] } ``` @@ -59,9 +59,9 @@ Create a file named `my-agent.json`: ```json { "tools": [ - "fs_read", - "fs_write", - "execute_bash" + "file_read", + "file_write", + "shell" ], "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert Python developer. Help users write clean, efficient code." @@ -99,7 +99,7 @@ The configuration feature is fully backward compatible. Existing Agent initializ # This still works exactly as before agent = Agent( model="us.anthropic.claude-sonnet-4-20250514-v1:0", - tools=["fs_read"], + tools=["file_read"], system_prompt="You are helpful" ) ``` From 399fce30fef15b2cc39b9e1b365c3314ad19978d Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 11 Sep 2025 20:42:44 -0400 Subject: [PATCH 04/45] Update documentation to show correct tool usage - Show tool names from strands_tools package as primary method - Include file paths and tool objects as alternatives - Update examples to use 'calculator', 'shell', etc. - Align with standard Strands agent tool specification patterns --- .../agent-configs/coding-assistant.json | 5 ++- .../concepts/agents/configuration.md | 33 +++++++++++++++---- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json index 84ebfa3e..30e5e62f 100644 --- a/docs/examples/agent-configs/coding-assistant.json +++ b/docs/examples/agent-configs/coding-assistant.json @@ -1,8 +1,7 @@ { "tools": [ - "file_read", - "file_write", - "shell" + "shell", + "calculator" ], "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert software developer. Help users write clean, efficient, and well-documented code. Always explain your reasoning and provide examples when helpful." diff --git a/docs/user-guide/concepts/agents/configuration.md b/docs/user-guide/concepts/agents/configuration.md index 46cd8c38..e07d1a23 100644 --- a/docs/user-guide/concepts/agents/configuration.md +++ b/docs/user-guide/concepts/agents/configuration.md @@ -26,11 +26,30 @@ agent = Agent(config=config) Currently, the following fields from the agent-format.md specification are supported: ### `tools` -List of tools available to the agent: +List of tools available to the agent. Tools can be specified as: +1. **Tool names from strands_tools** (recommended): ```json { - "tools": ["file_read", "file_write", "shell"] + "tools": ["calculator", "shell", "current_time"] +} +``` + +2. **File paths** to custom tool files: +```json +{ + "tools": ["./tools/my_custom_tool.py", "/path/to/another_tool.py"] +} +``` + +3. **Tool objects** (when using Python dict config): +```python +from strands_tools import calculator, shell + +config = { + "tools": [calculator, shell], + "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", + "prompt": "You are a helpful assistant" } ``` @@ -59,9 +78,9 @@ Create a file named `my-agent.json`: ```json { "tools": [ - "file_read", - "file_write", - "shell" + "calculator", + "shell", + "current_time" ], "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", "prompt": "You are an expert Python developer. Help users write clean, efficient code." @@ -97,9 +116,11 @@ The configuration feature is fully backward compatible. Existing Agent initializ ```python # This still works exactly as before +from strands_tools import shell + agent = Agent( model="us.anthropic.claude-sonnet-4-20250514-v1:0", - tools=["file_read"], + tools=[shell], system_prompt="You are helpful" ) ``` From cc818a66ed8d6aa23cd68a3b0bf3efedab99596c Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 19:26:04 -0400 Subject: [PATCH 05/45] feat: add experimental AgentConfig and ToolPool documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive documentation for experimental AgentConfig - Add detailed ToolPool documentation with API reference - Create experimental features overview and index - Update mkdocs.yml to include experimental section - Document file:// prefix requirements and method renames - Include integration examples and best practices 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 148 +++++++++++ .../user-guide/concepts/experimental/index.md | 83 ++++++ .../concepts/experimental/tool-pool.md | 238 ++++++++++++++++++ mkdocs.yml | 4 + 4 files changed, 473 insertions(+) create mode 100644 docs/user-guide/concepts/experimental/agent-config.md create mode 100644 docs/user-guide/concepts/experimental/index.md create mode 100644 docs/user-guide/concepts/experimental/tool-pool.md diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md new file mode 100644 index 00000000..7802cb39 --- /dev/null +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -0,0 +1,148 @@ +# Experimental AgentConfig + +!!! warning "Experimental Feature" + This feature is experimental and may change in future versions. Use with caution in production environments. + +The experimental `AgentConfig` provides a declarative way to configure and create Agent instances with enhanced instantiation patterns. + +## Overview + +`AgentConfig` allows you to: + +- Load agent configurations from JSON files or dictionaries +- Create Agent instances with the `toAgent()` method +- Integrate with ToolPool for advanced tool management +- Use standardized configuration interfaces + +## Basic Usage + +### Dictionary Configuration + +```python +from strands.experimental import AgentConfig + +# Create config from dictionary +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant" +}) + +# Create agent instance +agent = config.toAgent() +``` + +### File Configuration + +Configuration files must use the `file://` prefix: + +```python +# Load from JSON file +config = AgentConfig("file:///path/to/config.json") +agent = config.toAgent() +``` + +Example `config.json`: +```json +{ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant specialized in data analysis" +} +``` + +## Integration with ToolPool + +`AgentConfig` works seamlessly with `ToolPool` for advanced tool management: + +```python +from strands.experimental import AgentConfig, ToolPool +from strands_tools import calculator, current_time + +# Create tool pool +tools = ToolPool([calculator, current_time]) + +# Create agent with tools +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant with access to tools" +}) + +agent = config.toAgent(tools=tools) +``` + +## Configuration Options + +### Supported Keys + +- `model`: Model identifier (string) +- `prompt`: System prompt for the agent (string) + +### Method Parameters + +The `toAgent()` method accepts: + +- `tools`: Optional ToolPool instance +- `**kwargs`: Additional Agent constructor parameters that override config values + +```python +# Override config values +agent = config.toAgent( + tools=my_tools, + temperature=0.7, + max_tokens=1000 +) +``` + +## File Path Requirements + +File paths must be prefixed with `file://` to maintain a standard interface: + +```python +# ✅ Correct +config = AgentConfig("file:///absolute/path/to/config.json") + +# ❌ Incorrect - will raise ValueError +config = AgentConfig("/absolute/path/to/config.json") +``` + +## Error Handling + +```python +from strands.experimental import AgentConfig + +try: + # This will raise ValueError + config = AgentConfig("/path/without/prefix.json") +except ValueError as e: + print(f"Error: {e}") # File paths must be prefixed with 'file://' +``` + +## Best Practices + +1. **Use file:// prefix**: Always prefix file paths with `file://` +2. **Validate configurations**: Test your JSON configurations before deployment +3. **Combine with ToolPool**: Use ToolPool for advanced tool management +4. **Override when needed**: Use kwargs to override config values dynamically + +## Example: Complete Workflow + +```python +from strands.experimental import AgentConfig, ToolPool +from strands_tools import calculator, web_search + +# Create tool pool +tools = ToolPool([calculator, web_search]) + +# Load configuration +config = AgentConfig("file:///app/configs/research-agent.json") + +# Create specialized agent +agent = config.toAgent( + tools=tools, + temperature=0.3 # Override default temperature +) + +# Use the agent +response = agent("Calculate the ROI of a $10,000 investment with 7% annual return over 5 years") +``` + +This experimental feature provides a foundation for more advanced agent configuration patterns while maintaining compatibility with the existing Agent API. diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md new file mode 100644 index 00000000..91f0855d --- /dev/null +++ b/docs/user-guide/concepts/experimental/index.md @@ -0,0 +1,83 @@ +# Experimental Features + +!!! warning "Experimental Features" + The features in this section are experimental and may change in future versions. Use with caution in production environments. + +Strands Agents includes experimental features that provide enhanced functionality and improved developer experience. These features are designed to be forward-compatible but may undergo changes based on user feedback and evolving requirements. + +## Available Experimental Features + +### [AgentConfig](agent-config.md) +Declarative agent configuration with enhanced instantiation patterns. + +- Load configurations from JSON files or dictionaries +- Create Agent instances with the `toAgent()` method +- Standardized configuration interfaces with `file://` prefix support +- Integration with ToolPool for advanced tool management + +### [ToolPool](tool-pool.md) +Clean, intuitive tool management with natural constructor API. + +- Direct tool function passing: `ToolPool([calculator, current_time])` +- Module imports with `ToolPool.from_module()` +- Mixed tool type support (AgentTool instances and `@tool` functions) +- Seamless Agent integration + +## Getting Started + +Import experimental features from the `strands.experimental` namespace: + +```python +from strands.experimental import AgentConfig, ToolPool +``` + +## Quick Example + +```python +from strands.experimental import AgentConfig, ToolPool +from strands_tools import calculator, current_time + +# Create tool pool +tools = ToolPool([calculator, current_time]) + +# Create agent configuration +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant with access to tools" +}) + +# Create agent +agent = config.toAgent(tools=tools) + +# Use the agent +response = agent("What time is it and what's 15 * 24?") +``` + +## Design Principles + +The experimental features follow these design principles: + +1. **Natural APIs**: Intuitive interfaces that feel natural to Python developers +2. **Backward Compatibility**: Work alongside existing Strands Agent features +3. **Type Safety**: Full type hints with modern Python typing syntax +4. **Composability**: Features work together seamlessly +5. **Standards Compliance**: Follow established patterns and conventions + +## Feedback and Evolution + +These experimental features are actively developed based on user feedback. If you have suggestions or encounter issues, please: + +1. Check the existing documentation and examples +2. Review the test cases in the SDK for additional usage patterns +3. Provide feedback through the appropriate channels + +## Migration Path + +When experimental features graduate to stable status: + +1. They will be moved to the main API namespace +2. Backward compatibility will be maintained during transition periods +3. Clear migration guides will be provided +4. Deprecation warnings will be issued for experimental namespaces + +The experimental namespace provides a safe space to iterate on new features while maintaining stability in the core API. diff --git a/docs/user-guide/concepts/experimental/tool-pool.md b/docs/user-guide/concepts/experimental/tool-pool.md new file mode 100644 index 00000000..25e451f4 --- /dev/null +++ b/docs/user-guide/concepts/experimental/tool-pool.md @@ -0,0 +1,238 @@ +# Experimental ToolPool + +!!! warning "Experimental Feature" + This feature is experimental and may change in future versions. Use with caution in production environments. + +The experimental `ToolPool` provides a clean, intuitive way to manage collections of tools with a natural constructor API. + +## Overview + +`ToolPool` allows you to: + +- Manage collections of tools with a clean constructor API +- Pass tool functions directly: `ToolPool([calculator, current_time])` +- Import entire modules of tools with `ToolPool.from_module()` +- Integrate seamlessly with Agent instances + +## Basic Usage + +### Direct Tool Function Passing + +```python +from strands.experimental import ToolPool +from strands_tools import calculator, current_time + +# Create pool with tool functions directly +pool = ToolPool([calculator, current_time]) + +# Use with Agent +from strands import Agent +agent = Agent(tools=pool.get_tools()) +``` + +### Empty Pool with Manual Addition + +```python +from strands.experimental import ToolPool +from strands_tools import calculator + +# Create empty pool +pool = ToolPool() + +# Add tools manually +pool.add_tool_function(calculator) + +# Get tool names +print(pool.list_tool_names()) # ['calculator'] + +# Get AgentTool instances +tools = pool.get_tools() +``` + +## Module Import + +Import all `@tool` decorated functions from a module: + +```python +from strands.experimental import ToolPool +import strands_tools + +# Import all tools from module +pool = ToolPool.from_module(strands_tools) + +# Or add to existing pool +pool = ToolPool() +pool.add_tools_from_module(strands_tools) +``` + +## API Reference + +### Constructor + +```python +ToolPool(tools: list[AgentTool | Callable] | None = None) +``` + +- `tools`: Optional list of AgentTool instances or `@tool` decorated functions + +### Methods + +#### `add_tool_function(tool_func: Callable) -> None` + +Add a `@tool` decorated function to the pool. + +```python +from strands import tool + +@tool +def my_calculator(a: int, b: int) -> int: + """Add two numbers.""" + return a + b + +pool = ToolPool() +pool.add_tool_function(my_calculator) +``` + +#### `add_tools_from_module(module: any) -> None` + +Add all `@tool` decorated functions from a module. + +```python +import my_tools_module + +pool = ToolPool() +pool.add_tools_from_module(my_tools_module) +``` + +#### `list_tool_names() -> list[str]` + +Get a list of all tool names in the pool. + +```python +pool = ToolPool([calculator, current_time]) +names = pool.list_tool_names() # ['calculator', 'current_time'] +``` + +#### `get_tools() -> list[AgentTool]` + +Get all tools as AgentTool instances for use with Agent. + +```python +pool = ToolPool([calculator, current_time]) +agent_tools = pool.get_tools() + +# Use with Agent +agent = Agent(tools=agent_tools) +``` + +#### `from_module(module: any) -> ToolPool` (Class Method) + +Create a ToolPool from all `@tool` functions in a module. + +```python +import strands_tools + +# Create pool from entire module +pool = ToolPool.from_module(strands_tools) +``` + +## Integration with AgentConfig + +ToolPool works seamlessly with the experimental AgentConfig: + +```python +from strands.experimental import AgentConfig, ToolPool +from strands_tools import calculator, web_search + +# Create tool pool +tools = ToolPool([calculator, web_search]) + +# Create agent config +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant with access to tools" +}) + +# Create agent with tools +agent = config.toAgent(tools=tools) +``` + +## Mixed Tool Types + +ToolPool accepts both AgentTool instances and `@tool` decorated functions: + +```python +from strands.experimental import ToolPool +from strands.types.tools import AgentTool +from strands_tools import calculator + +# Custom AgentTool +class CustomTool(AgentTool): + def __init__(self): + super().__init__(tool_name="custom_tool") + + def invoke(self, input_data, context): + return "Custom result" + +# Mix different tool types +pool = ToolPool([ + calculator, # @tool decorated function + CustomTool() # AgentTool instance +]) +``` + +## Error Handling + +```python +from strands.experimental import ToolPool + +def not_a_tool(): + """This function is not decorated with @tool""" + pass + +try: + pool = ToolPool([not_a_tool]) +except ValueError as e: + print(f"Error: {e}") # Function not_a_tool is not decorated with @tool +``` + +## Best Practices + +1. **Use direct function passing**: Pass `@tool` decorated functions directly to the constructor +2. **Module imports**: Use `from_module()` for importing entire tool modules +3. **Clear naming**: Tool names are automatically derived from function names +4. **Type safety**: ToolPool validates that functions are properly decorated +5. **Integration**: Use with AgentConfig for complete configuration management + +## Example: Complete Workflow + +```python +from strands.experimental import ToolPool, AgentConfig +from strands import tool +import strands_tools + +# Define custom tool +@tool +def custom_calculator(expression: str) -> float: + """Evaluate a mathematical expression safely.""" + # Safe evaluation logic here + return eval(expression) # Note: Use safe evaluation in production + +# Create tool pool with mixed sources +pool = ToolPool([custom_calculator]) +pool.add_tools_from_module(strands_tools) + +# Create agent configuration +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a mathematical assistant with access to calculation tools" +}) + +# Create agent with all tools +agent = config.toAgent(tools=pool) + +# Use the agent +response = agent("Calculate the compound interest on $1000 at 5% for 3 years") +``` + +This experimental feature provides a foundation for more intuitive tool management while maintaining compatibility with the existing Agent and tool infrastructure. diff --git a/mkdocs.yml b/mkdocs.yml index 096af65a..9ad257ff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,6 +112,10 @@ nav: - Graph: user-guide/concepts/multi-agent/graph.md - Workflow: user-guide/concepts/multi-agent/workflow.md - Multi-agent Patterns: user-guide/concepts/multi-agent/multi-agent-patterns.md + - Experimental: + - Overview: user-guide/concepts/experimental/index.md + - AgentConfig: user-guide/concepts/experimental/agent-config.md + - ToolPool: user-guide/concepts/experimental/tool-pool.md - Safety & Security: - Responsible AI: user-guide/safety-security/responsible-ai.md - Guardrails: user-guide/safety-security/guardrails.md From 5b2c63aba53d3c08d912d6554d414a8345f2659c Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 19:35:20 -0400 Subject: [PATCH 06/45] refactor: update experimental docs per feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove agents/configuration.md as functionality moved to experimental - Update AgentConfig to focus on configuration-based agents (no agent-format.md references) - Add ToolPool motivation: tool registry for single Strands runtime - Add customer interface example showing platform provider use case - Emphasize multi-tenant and agent marketplace capabilities - Update experimental index to reflect tool registry concept 🤖 Assisted by Amazon Q Developer --- .../concepts/agents/configuration.md | 149 ------------------ .../concepts/experimental/agent-config.md | 6 +- .../user-guide/concepts/experimental/index.md | 13 +- .../concepts/experimental/tool-pool.md | 64 +++++++- mkdocs.yml | 1 - 5 files changed, 73 insertions(+), 160 deletions(-) delete mode 100644 docs/user-guide/concepts/agents/configuration.md diff --git a/docs/user-guide/concepts/agents/configuration.md b/docs/user-guide/concepts/agents/configuration.md deleted file mode 100644 index e07d1a23..00000000 --- a/docs/user-guide/concepts/agents/configuration.md +++ /dev/null @@ -1,149 +0,0 @@ -# Agent Configuration - -The Strands SDK supports loading agent configuration from JSON files following the [agent-format.md specification](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md) used by Amazon Q Developer CLI. - -## Basic Usage - -You can initialize an Agent using a configuration file: - -```python -from strands import Agent - -# Load from configuration file -agent = Agent(config="/path/to/agent-config.json") - -# Or from a configuration dictionary -config = { - "tools": ["shell", "calculator"], - "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", - "prompt": "You are a helpful coding assistant" -} -agent = Agent(config=config) -``` - -## Supported Configuration Fields - -Currently, the following fields from the agent-format.md specification are supported: - -### `tools` -List of tools available to the agent. Tools can be specified as: - -1. **Tool names from strands_tools** (recommended): -```json -{ - "tools": ["calculator", "shell", "current_time"] -} -``` - -2. **File paths** to custom tool files: -```json -{ - "tools": ["./tools/my_custom_tool.py", "/path/to/another_tool.py"] -} -``` - -3. **Tool objects** (when using Python dict config): -```python -from strands_tools import calculator, shell - -config = { - "tools": [calculator, shell], - "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", - "prompt": "You are a helpful assistant" -} -``` - -### `model` -Model ID to use for the agent (must be full Bedrock model ID): - -```json -{ - "model": "us.anthropic.claude-sonnet-4-20250514-v1:0" -} -``` - -### `prompt` -System prompt for the agent (maps to `system_prompt` parameter): - -```json -{ - "prompt": "You are a helpful assistant specialized in Python development" -} -``` - -## Example Configuration File - -Create a file named `my-agent.json`: - -```json -{ - "tools": [ - "calculator", - "shell", - "current_time" - ], - "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", - "prompt": "You are an expert Python developer. Help users write clean, efficient code." -} -``` - -Then load it in your Python code: - -```python -from strands import Agent - -agent = Agent(config="my-agent.json") -result = agent("Help me write a function to parse JSON files") -print(result.message) -``` - -## Parameter Precedence - -Constructor parameters take precedence over configuration file values: - -```python -# Config file has model: "us.anthropic.claude-3-haiku-20240307-v1:0" -# But constructor parameter overrides it -agent = Agent( - config="my-agent.json", - model="us.anthropic.claude-sonnet-4-20250514-v1:0" # This takes precedence -) -``` - -## Backward Compatibility - -The configuration feature is fully backward compatible. Existing Agent initialization continues to work unchanged: - -```python -# This still works exactly as before -from strands_tools import shell - -agent = Agent( - model="us.anthropic.claude-sonnet-4-20250514-v1:0", - tools=[shell], - system_prompt="You are helpful" -) -``` - -## Error Handling - -The SDK provides clear error messages for configuration issues: - -```python -try: - agent = Agent(config="/nonexistent/config.json") -except ValueError as e: - print(f"Configuration error: {e}") - # Output: Configuration error: Failed to load agent configuration: Agent config file not found: /nonexistent/config.json -``` - -## Future Enhancements - -Additional fields from the agent-format.md specification may be supported in future releases, including: - -- `mcpServers` - MCP server configurations -- `allowedTools` - Tool permission settings -- `resources` - File and resource access -- `hooks` - Lifecycle event handlers - -For the complete specification, see the [agent-format.md documentation](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md). diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 7802cb39..3d9d0c94 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -3,14 +3,14 @@ !!! warning "Experimental Feature" This feature is experimental and may change in future versions. Use with caution in production environments. -The experimental `AgentConfig` provides a declarative way to configure and create Agent instances with enhanced instantiation patterns. +The experimental `AgentConfig` provides a declarative way to create configuration-based agents with enhanced instantiation patterns. ## Overview `AgentConfig` allows you to: -- Load agent configurations from JSON files or dictionaries -- Create Agent instances with the `toAgent()` method +- Create configuration-based agents from JSON files or dictionaries +- Use the `toAgent()` method for clean agent instantiation - Integrate with ToolPool for advanced tool management - Use standardized configuration interfaces diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md index 91f0855d..6cc2c026 100644 --- a/docs/user-guide/concepts/experimental/index.md +++ b/docs/user-guide/concepts/experimental/index.md @@ -8,20 +8,21 @@ Strands Agents includes experimental features that provide enhanced functionalit ## Available Experimental Features ### [AgentConfig](agent-config.md) -Declarative agent configuration with enhanced instantiation patterns. +Declarative configuration-based agent creation with enhanced instantiation patterns. -- Load configurations from JSON files or dictionaries -- Create Agent instances with the `toAgent()` method +- Create configuration-based agents from JSON files or dictionaries +- Use the `toAgent()` method for clean agent instantiation - Standardized configuration interfaces with `file://` prefix support - Integration with ToolPool for advanced tool management ### [ToolPool](tool-pool.md) -Clean, intuitive tool management with natural constructor API. +Tool registry and management system with natural constructor API. +- Centralized tool registry for single Strands runtime environments +- Customer interface for tool selection and custom agent creation - Direct tool function passing: `ToolPool([calculator, current_time])` - Module imports with `ToolPool.from_module()` -- Mixed tool type support (AgentTool instances and `@tool` functions) -- Seamless Agent integration +- Platform provider capabilities for multi-tenant tool management ## Getting Started diff --git a/docs/user-guide/concepts/experimental/tool-pool.md b/docs/user-guide/concepts/experimental/tool-pool.md index 25e451f4..ff0cd27b 100644 --- a/docs/user-guide/concepts/experimental/tool-pool.md +++ b/docs/user-guide/concepts/experimental/tool-pool.md @@ -3,16 +3,78 @@ !!! warning "Experimental Feature" This feature is experimental and may change in future versions. Use with caution in production environments. -The experimental `ToolPool` provides a clean, intuitive way to manage collections of tools with a natural constructor API. +The experimental `ToolPool` provides a clean, intuitive way to manage collections of tools with a natural constructor API, serving as a tool registry for a single Strands runtime. ## Overview +`ToolPool` is designed as a superset of tools available to the agent framework, providing an interface for customers to create their own agents by selecting from a curated list of available tools. Think of it as a tool registry that manages all tools within a single Strands runtime environment. + +### Key Concepts + +- **Tool Registry**: Centralized management of all available tools +- **Customer Interface**: Enable customers to select tools for their custom agents +- **Runtime Scope**: Manages tools within a single Strands runtime instance +- **Natural API**: Clean, intuitive constructor and method interfaces + +### Use Cases + +- **Platform Providers**: Offer a curated set of tools that customers can choose from +- **Multi-tenant Environments**: Manage tool availability per tenant or customer +- **Agent Marketplaces**: Allow users to build custom agents from available tools +- **Tool Governance**: Control which tools are available in different contexts + `ToolPool` allows you to: - Manage collections of tools with a clean constructor API - Pass tool functions directly: `ToolPool([calculator, current_time])` - Import entire modules of tools with `ToolPool.from_module()` - Integrate seamlessly with Agent instances +- Provide customers with tool selection interfaces + +## Customer Interface Example + +Here's how a platform provider might use ToolPool to offer tool selection to customers: + +```python +from strands.experimental import ToolPool, AgentConfig +from strands_tools import calculator, web_search, file_operations, data_analysis + +# Platform provider creates a comprehensive tool registry +platform_tools = ToolPool([ + calculator, + web_search, + file_operations, + data_analysis, + # ... more tools +]) + +# Customer selects tools for their specific use case +def create_customer_agent(selected_tool_names: list[str], customer_config: dict): + """Allow customers to create agents with selected tools.""" + + # Filter tools based on customer selection + customer_tools = ToolPool() + all_tools = platform_tools.get_tools() + + for tool in all_tools: + if tool.tool_name in selected_tool_names: + customer_tools.add_tool(tool) + + # Create customer's agent configuration + config = AgentConfig(customer_config) + + # Return configured agent with selected tools + return config.toAgent(tools=customer_tools) + +# Customer usage +my_agent = create_customer_agent( + selected_tool_names=["calculator", "web_search"], + customer_config={ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are my research assistant" + } +) +``` ## Basic Usage diff --git a/mkdocs.yml b/mkdocs.yml index 9ad257ff..bad3eaec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,7 +75,6 @@ nav: - Concepts: - Agents: - Agent Loop: user-guide/concepts/agents/agent-loop.md - - Configuration: user-guide/concepts/agents/configuration.md - State: user-guide/concepts/agents/state.md - Session Management: user-guide/concepts/agents/session-management.md - Prompts: user-guide/concepts/agents/prompts.md From b85dc8a92eca2384c4b25630bd79779dc71efe53 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 20:17:30 -0400 Subject: [PATCH 07/45] docs: update experimental AgentConfig with latest enhancements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add documentation for default tools behavior and experimental tool list - Document tool selection and validation from ToolPool registry - Add comprehensive error handling examples for all error types - Update best practices with dependency management recommendations - Include complete workflow example with proper error handling - Reflect latest API improvements and type hint cleanups 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 151 ++++++++++++++++-- 1 file changed, 134 insertions(+), 17 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 3d9d0c94..20834c1b 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -75,12 +75,13 @@ agent = config.toAgent(tools=tools) - `model`: Model identifier (string) - `prompt`: System prompt for the agent (string) +- `tools`: List of tool names to select from the provided ToolPool (optional) ### Method Parameters The `toAgent()` method accepts: -- `tools`: Optional ToolPool instance +- `tools`: Optional ToolPool instance to override the configured tools - `**kwargs`: Additional Agent constructor parameters that override config values ```python @@ -92,6 +93,58 @@ agent = config.toAgent( ) ``` +## Default Tools Behavior + +When no ToolPool is provided, AgentConfig attempts to create a default ToolPool with these tools from `strands_tools`: + +- `file_read` - File reading operations +- `editor` - Text editing capabilities +- `http_request` - HTTP requests +- `shell` - Shell command execution +- `use_agent` - Agent delegation + +!!! note "Experimental Tool List" + This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. + +If `strands_tools` is not installed, you must provide your own ToolPool: + +```python +from strands.experimental import AgentConfig, ToolPool +from strands import tool + +@tool +def my_custom_tool(input: str) -> str: + """My custom tool implementation.""" + return f"Processed: {input}" + +# Create custom ToolPool +custom_tools = ToolPool([my_custom_tool]) + +# Use with AgentConfig +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant" +}, tool_pool=custom_tools) +``` + +## Tool Selection + +When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolPool: + +```python +# Platform provider creates comprehensive ToolPool +platform_tools = ToolPool([calculator, web_search, file_ops, data_analysis]) + +# Customer selects specific tools +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a research assistant", + "tools": ["calculator", "web_search"] # Only these will be available +}, tool_pool=platform_tools) + +agent = config.toAgent() # Agent has only calculator and web_search +``` + ## File Path Requirements File paths must be prefixed with `file://` to maintain a standard interface: @@ -106,6 +159,7 @@ config = AgentConfig("/absolute/path/to/config.json") ## Error Handling +### File Path Errors ```python from strands.experimental import AgentConfig @@ -116,33 +170,96 @@ except ValueError as e: print(f"Error: {e}") # File paths must be prefixed with 'file://' ``` +### Tool Validation Errors +```python +from strands.experimental import AgentConfig, ToolPool + +# Tool not found in ToolPool +try: + config = AgentConfig({ + "model": "test-model", + "tools": ["nonexistent_tool"] + }, tool_pool=ToolPool()) +except ValueError as e: + print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolPool +``` + +### Missing Dependencies +```python +# When strands_tools not installed and no ToolPool provided +try: + config = AgentConfig({"model": "test-model"}) +except ImportError as e: + print(f"Error: {e}") + # strands_tools is not available and no ToolPool was specified. + # Either install strands_tools with 'pip install strands-agents-tools' + # or provide your own ToolPool with your own tools. +``` + +### Tool Configuration Without ToolPool +```python +# Specifying tools without providing ToolPool +try: + config = AgentConfig({ + "model": "test-model", + "tools": ["calculator"] + }) # No tool_pool parameter +except ValueError as e: + print(f"Error: {e}") # Tool names specified in config but no ToolPool provided +``` + ## Best Practices 1. **Use file:// prefix**: Always prefix file paths with `file://` -2. **Validate configurations**: Test your JSON configurations before deployment -3. **Combine with ToolPool**: Use ToolPool for advanced tool management -4. **Override when needed**: Use kwargs to override config values dynamically +2. **Install strands_tools**: Use `pip install strands-agents-tools` for default tools +3. **Provide custom ToolPool**: Create your own ToolPool if not using strands_tools +4. **Validate tool selection**: Ensure tool names exist in your ToolPool before configuration +5. **Tool registry pattern**: Use ToolPool as a registry for customer tool selection +6. **Override when needed**: Use kwargs to override config values dynamically +7. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications ## Example: Complete Workflow ```python from strands.experimental import AgentConfig, ToolPool -from strands_tools import calculator, web_search +from strands import tool -# Create tool pool -tools = ToolPool([calculator, web_search]) +# Define custom tools +@tool +def custom_calculator(expression: str) -> float: + """Evaluate a mathematical expression safely.""" + # Safe evaluation logic here + return eval(expression) # Note: Use safe evaluation in production -# Load configuration -config = AgentConfig("file:///app/configs/research-agent.json") +@tool +def data_processor(data: str) -> str: + """Process data with custom logic.""" + return f"Processed: {data}" -# Create specialized agent -agent = config.toAgent( - tools=tools, - temperature=0.3 # Override default temperature -) - -# Use the agent -response = agent("Calculate the ROI of a $10,000 investment with 7% annual return over 5 years") +try: + # Create tool pool with custom tools + tools = ToolPool([custom_calculator, data_processor]) + + # Load configuration with tool selection + config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a data analysis assistant", + "tools": ["custom_calculator"] # Only calculator available to agent + }, tool_pool=tools) + + # Create agent with selected tools + agent = config.toAgent(temperature=0.3) + + # Use the agent + response = agent("Calculate the compound interest on $1000 at 5% for 3 years") + +except ImportError as e: + print(f"Missing dependencies: {e}") + # Handle by installing strands_tools or providing custom ToolPool + +except ValueError as e: + print(f"Configuration error: {e}") + # Handle tool validation or file path errors ``` This experimental feature provides a foundation for more advanced agent configuration patterns while maintaining compatibility with the existing Agent API. From ba28e07f01e336381fe027a5e3271251654f697a Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 20:18:20 -0400 Subject: [PATCH 08/45] docs: add examples using default tools from strands_tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Show basic usage with automatic default tool loading - Demonstrate selecting specific tools from default set - Add warning about strands_tools dependency requirement - Provide practical examples for file and web capabilities 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 41 ++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 20834c1b..19302d1d 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -27,10 +27,49 @@ config = AgentConfig({ "prompt": "You are a helpful assistant" }) -# Create agent instance +# Create agent instance (uses default tools from strands_tools) agent = config.toAgent() ``` +### Using Default Tools + +When no ToolPool is provided, AgentConfig automatically loads default tools from `strands_tools`: + +```python +from strands.experimental import AgentConfig + +# This will use the default tools: file_read, editor, http_request, shell, use_agent +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant with file and web capabilities" +}) + +agent = config.toAgent() + +# Agent now has access to default tools +response = agent("Read the contents of README.md and summarize it") +``` + +### Selecting from Default Tools + +You can also select specific tools from the default set: + +```python +from strands.experimental import AgentConfig + +# Select only specific default tools +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a file management assistant", + "tools": ["file_read", "editor"] # Only file operations, no web/shell +}) + +agent = config.toAgent() +``` + +!!! warning "Requires strands_tools" + Default tools require `pip install strands-agents-tools`. If not installed, provide your own ToolPool. + ### File Configuration Configuration files must use the `file://` prefix: From 06b63d49e1913a3da4be18dfa69c09e0044a4a3d Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 20:19:15 -0400 Subject: [PATCH 09/45] docs: clarify ToolPool configuration requirement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update warning to specify 'configure your own ToolPool with your own tools' - More explicit about the configuration requirement when strands_tools not available 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 19302d1d..fbc0068a 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -68,7 +68,7 @@ agent = config.toAgent() ``` !!! warning "Requires strands_tools" - Default tools require `pip install strands-agents-tools`. If not installed, provide your own ToolPool. + Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolPool with your own tools. ### File Configuration From ebe5b7bd232aeef75cd8afea47491dfa9e38bcf2 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Tue, 23 Sep 2025 20:21:38 -0400 Subject: [PATCH 10/45] fix: update coding-assistant.json with correct tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Change tools from ['shell', 'calculator'] to ['shell', 'file_read', 'editor'] - Use appropriate tools for coding assistant functionality - Update model and prompt for better coding assistance 🤖 Assisted by Amazon Q Developer --- docs/examples/agent-configs/coding-assistant.json | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json index 30e5e62f..bafa2127 100644 --- a/docs/examples/agent-configs/coding-assistant.json +++ b/docs/examples/agent-configs/coding-assistant.json @@ -1,8 +1,5 @@ { - "tools": [ - "shell", - "calculator" - ], - "model": "us.anthropic.claude-sonnet-4-20250514-v1:0", - "prompt": "You are an expert software developer. Help users write clean, efficient, and well-documented code. Always explain your reasoning and provide examples when helpful." + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a coding assistant. Help users write, debug, and improve their code. You have access to file operations and can execute shell commands when needed.", + "tools": ["shell", "file_read", "editor"] } From 0b1c548d286c55a42b9d82c1095fbc177630bd57 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Wed, 24 Sep 2025 11:50:57 -0400 Subject: [PATCH 11/45] docs: update experimental docs for ToolPool to ToolBox rename MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename tool-pool.md to tool-box.md - Update all ToolPool references to ToolBox - Update get_tools() method references to list_tools() - Update tool_pool parameter references to tool_box - Update navigation and cross-references 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 74 ++++++++--------- .../user-guide/concepts/experimental/index.md | 14 ++-- .../{tool-pool.md => tool-box.md} | 82 +++++++++---------- mkdocs.yml | 2 +- 4 files changed, 86 insertions(+), 86 deletions(-) rename docs/user-guide/concepts/experimental/{tool-pool.md => tool-box.md} (73%) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index fbc0068a..c9d74252 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -11,7 +11,7 @@ The experimental `AgentConfig` provides a declarative way to create configuratio - Create configuration-based agents from JSON files or dictionaries - Use the `toAgent()` method for clean agent instantiation -- Integrate with ToolPool for advanced tool management +- Integrate with ToolBox for advanced tool management - Use standardized configuration interfaces ## Basic Usage @@ -33,7 +33,7 @@ agent = config.toAgent() ### Using Default Tools -When no ToolPool is provided, AgentConfig automatically loads default tools from `strands_tools`: +When no ToolBox is provided, AgentConfig automatically loads default tools from `strands_tools`: ```python from strands.experimental import AgentConfig @@ -68,7 +68,7 @@ agent = config.toAgent() ``` !!! warning "Requires strands_tools" - Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolPool with your own tools. + Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolBox with your own tools. ### File Configuration @@ -88,16 +88,16 @@ Example `config.json`: } ``` -## Integration with ToolPool +## Integration with ToolBox -`AgentConfig` works seamlessly with `ToolPool` for advanced tool management: +`AgentConfig` works seamlessly with `ToolBox` for advanced tool management: ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox from strands_tools import calculator, current_time # Create tool pool -tools = ToolPool([calculator, current_time]) +tools = ToolBox([calculator, current_time]) # Create agent with tools config = AgentConfig({ @@ -114,13 +114,13 @@ agent = config.toAgent(tools=tools) - `model`: Model identifier (string) - `prompt`: System prompt for the agent (string) -- `tools`: List of tool names to select from the provided ToolPool (optional) +- `tools`: List of tool names to select from the provided ToolBox (optional) ### Method Parameters The `toAgent()` method accepts: -- `tools`: Optional ToolPool instance to override the configured tools +- `tools`: Optional ToolBox instance to override the configured tools - `**kwargs`: Additional Agent constructor parameters that override config values ```python @@ -134,7 +134,7 @@ agent = config.toAgent( ## Default Tools Behavior -When no ToolPool is provided, AgentConfig attempts to create a default ToolPool with these tools from `strands_tools`: +When no ToolBox is provided, AgentConfig attempts to create a default ToolBox with these tools from `strands_tools`: - `file_read` - File reading operations - `editor` - Text editing capabilities @@ -145,10 +145,10 @@ When no ToolPool is provided, AgentConfig attempts to create a default ToolPool !!! note "Experimental Tool List" This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. -If `strands_tools` is not installed, you must provide your own ToolPool: +If `strands_tools` is not installed, you must provide your own ToolBox: ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox from strands import tool @tool @@ -156,30 +156,30 @@ def my_custom_tool(input: str) -> str: """My custom tool implementation.""" return f"Processed: {input}" -# Create custom ToolPool -custom_tools = ToolPool([my_custom_tool]) +# Create custom ToolBox +custom_tools = ToolBox([my_custom_tool]) # Use with AgentConfig config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant" -}, tool_pool=custom_tools) +}, tool_box=custom_tools) ``` ## Tool Selection -When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolPool: +When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolBox: ```python -# Platform provider creates comprehensive ToolPool -platform_tools = ToolPool([calculator, web_search, file_ops, data_analysis]) +# Platform provider creates comprehensive ToolBox +platform_tools = ToolBox([calculator, web_search, file_ops, data_analysis]) # Customer selects specific tools config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a research assistant", "tools": ["calculator", "web_search"] # Only these will be available -}, tool_pool=platform_tools) +}, tool_box=platform_tools) agent = config.toAgent() # Agent has only calculator and web_search ``` @@ -211,56 +211,56 @@ except ValueError as e: ### Tool Validation Errors ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox -# Tool not found in ToolPool +# Tool not found in ToolBox try: config = AgentConfig({ "model": "test-model", "tools": ["nonexistent_tool"] - }, tool_pool=ToolPool()) + }, tool_box=ToolBox()) except ValueError as e: - print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolPool + print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolBox ``` ### Missing Dependencies ```python -# When strands_tools not installed and no ToolPool provided +# When strands_tools not installed and no ToolBox provided try: config = AgentConfig({"model": "test-model"}) except ImportError as e: print(f"Error: {e}") - # strands_tools is not available and no ToolPool was specified. + # strands_tools is not available and no ToolBox was specified. # Either install strands_tools with 'pip install strands-agents-tools' - # or provide your own ToolPool with your own tools. + # or provide your own ToolBox with your own tools. ``` -### Tool Configuration Without ToolPool +### Tool Configuration Without ToolBox ```python -# Specifying tools without providing ToolPool +# Specifying tools without providing ToolBox try: config = AgentConfig({ "model": "test-model", "tools": ["calculator"] - }) # No tool_pool parameter + }) # No tool_box parameter except ValueError as e: - print(f"Error: {e}") # Tool names specified in config but no ToolPool provided + print(f"Error: {e}") # Tool names specified in config but no ToolBox provided ``` ## Best Practices 1. **Use file:// prefix**: Always prefix file paths with `file://` 2. **Install strands_tools**: Use `pip install strands-agents-tools` for default tools -3. **Provide custom ToolPool**: Create your own ToolPool if not using strands_tools -4. **Validate tool selection**: Ensure tool names exist in your ToolPool before configuration -5. **Tool registry pattern**: Use ToolPool as a registry for customer tool selection +3. **Provide custom ToolBox**: Create your own ToolBox if not using strands_tools +4. **Validate tool selection**: Ensure tool names exist in your ToolBox before configuration +5. **Tool registry pattern**: Use ToolBox as a registry for customer tool selection 6. **Override when needed**: Use kwargs to override config values dynamically 7. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications ## Example: Complete Workflow ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox from strands import tool # Define custom tools @@ -277,14 +277,14 @@ def data_processor(data: str) -> str: try: # Create tool pool with custom tools - tools = ToolPool([custom_calculator, data_processor]) + tools = ToolBox([custom_calculator, data_processor]) # Load configuration with tool selection config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a data analysis assistant", "tools": ["custom_calculator"] # Only calculator available to agent - }, tool_pool=tools) + }, tool_box=tools) # Create agent with selected tools agent = config.toAgent(temperature=0.3) @@ -294,7 +294,7 @@ try: except ImportError as e: print(f"Missing dependencies: {e}") - # Handle by installing strands_tools or providing custom ToolPool + # Handle by installing strands_tools or providing custom ToolBox except ValueError as e: print(f"Configuration error: {e}") diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md index 6cc2c026..a6facad2 100644 --- a/docs/user-guide/concepts/experimental/index.md +++ b/docs/user-guide/concepts/experimental/index.md @@ -13,15 +13,15 @@ Declarative configuration-based agent creation with enhanced instantiation patte - Create configuration-based agents from JSON files or dictionaries - Use the `toAgent()` method for clean agent instantiation - Standardized configuration interfaces with `file://` prefix support -- Integration with ToolPool for advanced tool management +- Integration with ToolBox for advanced tool management -### [ToolPool](tool-pool.md) +### [ToolBox](tool-box.md) Tool registry and management system with natural constructor API. - Centralized tool registry for single Strands runtime environments - Customer interface for tool selection and custom agent creation -- Direct tool function passing: `ToolPool([calculator, current_time])` -- Module imports with `ToolPool.from_module()` +- Direct tool function passing: `ToolBox([calculator, current_time])` +- Module imports with `ToolBox.from_module()` - Platform provider capabilities for multi-tenant tool management ## Getting Started @@ -29,17 +29,17 @@ Tool registry and management system with natural constructor API. Import experimental features from the `strands.experimental` namespace: ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox ``` ## Quick Example ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox from strands_tools import calculator, current_time # Create tool pool -tools = ToolPool([calculator, current_time]) +tools = ToolBox([calculator, current_time]) # Create agent configuration config = AgentConfig({ diff --git a/docs/user-guide/concepts/experimental/tool-pool.md b/docs/user-guide/concepts/experimental/tool-box.md similarity index 73% rename from docs/user-guide/concepts/experimental/tool-pool.md rename to docs/user-guide/concepts/experimental/tool-box.md index ff0cd27b..7562e6ff 100644 --- a/docs/user-guide/concepts/experimental/tool-pool.md +++ b/docs/user-guide/concepts/experimental/tool-box.md @@ -1,13 +1,13 @@ -# Experimental ToolPool +# Experimental ToolBox !!! warning "Experimental Feature" This feature is experimental and may change in future versions. Use with caution in production environments. -The experimental `ToolPool` provides a clean, intuitive way to manage collections of tools with a natural constructor API, serving as a tool registry for a single Strands runtime. +The experimental `ToolBox` provides a clean, intuitive way to manage collections of tools with a natural constructor API, serving as a tool registry for a single Strands runtime. ## Overview -`ToolPool` is designed as a superset of tools available to the agent framework, providing an interface for customers to create their own agents by selecting from a curated list of available tools. Think of it as a tool registry that manages all tools within a single Strands runtime environment. +`ToolBox` is designed as a superset of tools available to the agent framework, providing an interface for customers to create their own agents by selecting from a curated list of available tools. Think of it as a tool registry that manages all tools within a single Strands runtime environment. ### Key Concepts @@ -23,24 +23,24 @@ The experimental `ToolPool` provides a clean, intuitive way to manage collection - **Agent Marketplaces**: Allow users to build custom agents from available tools - **Tool Governance**: Control which tools are available in different contexts -`ToolPool` allows you to: +`ToolBox` allows you to: - Manage collections of tools with a clean constructor API -- Pass tool functions directly: `ToolPool([calculator, current_time])` -- Import entire modules of tools with `ToolPool.from_module()` +- Pass tool functions directly: `ToolBox([calculator, current_time])` +- Import entire modules of tools with `ToolBox.from_module()` - Integrate seamlessly with Agent instances - Provide customers with tool selection interfaces ## Customer Interface Example -Here's how a platform provider might use ToolPool to offer tool selection to customers: +Here's how a platform provider might use ToolBox to offer tool selection to customers: ```python -from strands.experimental import ToolPool, AgentConfig +from strands.experimental import ToolBox, AgentConfig from strands_tools import calculator, web_search, file_operations, data_analysis # Platform provider creates a comprehensive tool registry -platform_tools = ToolPool([ +platform_tools = ToolBox([ calculator, web_search, file_operations, @@ -53,8 +53,8 @@ def create_customer_agent(selected_tool_names: list[str], customer_config: dict) """Allow customers to create agents with selected tools.""" # Filter tools based on customer selection - customer_tools = ToolPool() - all_tools = platform_tools.get_tools() + customer_tools = ToolBox() + all_tools = platform_tools.list_tools() for tool in all_tools: if tool.tool_name in selected_tool_names: @@ -81,25 +81,25 @@ my_agent = create_customer_agent( ### Direct Tool Function Passing ```python -from strands.experimental import ToolPool +from strands.experimental import ToolBox from strands_tools import calculator, current_time # Create pool with tool functions directly -pool = ToolPool([calculator, current_time]) +pool = ToolBox([calculator, current_time]) # Use with Agent from strands import Agent -agent = Agent(tools=pool.get_tools()) +agent = Agent(tools=pool.list_tools()) ``` ### Empty Pool with Manual Addition ```python -from strands.experimental import ToolPool +from strands.experimental import ToolBox from strands_tools import calculator # Create empty pool -pool = ToolPool() +pool = ToolBox() # Add tools manually pool.add_tool_function(calculator) @@ -108,7 +108,7 @@ pool.add_tool_function(calculator) print(pool.list_tool_names()) # ['calculator'] # Get AgentTool instances -tools = pool.get_tools() +tools = pool.list_tools() ``` ## Module Import @@ -116,14 +116,14 @@ tools = pool.get_tools() Import all `@tool` decorated functions from a module: ```python -from strands.experimental import ToolPool +from strands.experimental import ToolBox import strands_tools # Import all tools from module -pool = ToolPool.from_module(strands_tools) +pool = ToolBox.from_module(strands_tools) # Or add to existing pool -pool = ToolPool() +pool = ToolBox() pool.add_tools_from_module(strands_tools) ``` @@ -132,7 +132,7 @@ pool.add_tools_from_module(strands_tools) ### Constructor ```python -ToolPool(tools: list[AgentTool | Callable] | None = None) +ToolBox(tools: list[AgentTool | Callable] | None = None) ``` - `tools`: Optional list of AgentTool instances or `@tool` decorated functions @@ -151,7 +151,7 @@ def my_calculator(a: int, b: int) -> int: """Add two numbers.""" return a + b -pool = ToolPool() +pool = ToolBox() pool.add_tool_function(my_calculator) ``` @@ -162,7 +162,7 @@ Add all `@tool` decorated functions from a module. ```python import my_tools_module -pool = ToolPool() +pool = ToolBox() pool.add_tools_from_module(my_tools_module) ``` @@ -171,43 +171,43 @@ pool.add_tools_from_module(my_tools_module) Get a list of all tool names in the pool. ```python -pool = ToolPool([calculator, current_time]) +pool = ToolBox([calculator, current_time]) names = pool.list_tool_names() # ['calculator', 'current_time'] ``` -#### `get_tools() -> list[AgentTool]` +#### `list_tools() -> list[AgentTool]` Get all tools as AgentTool instances for use with Agent. ```python -pool = ToolPool([calculator, current_time]) -agent_tools = pool.get_tools() +pool = ToolBox([calculator, current_time]) +agent_tools = pool.list_tools() # Use with Agent agent = Agent(tools=agent_tools) ``` -#### `from_module(module: any) -> ToolPool` (Class Method) +#### `from_module(module: any) -> ToolBox` (Class Method) -Create a ToolPool from all `@tool` functions in a module. +Create a ToolBox from all `@tool` functions in a module. ```python import strands_tools # Create pool from entire module -pool = ToolPool.from_module(strands_tools) +pool = ToolBox.from_module(strands_tools) ``` ## Integration with AgentConfig -ToolPool works seamlessly with the experimental AgentConfig: +ToolBox works seamlessly with the experimental AgentConfig: ```python -from strands.experimental import AgentConfig, ToolPool +from strands.experimental import AgentConfig, ToolBox from strands_tools import calculator, web_search # Create tool pool -tools = ToolPool([calculator, web_search]) +tools = ToolBox([calculator, web_search]) # Create agent config config = AgentConfig({ @@ -221,10 +221,10 @@ agent = config.toAgent(tools=tools) ## Mixed Tool Types -ToolPool accepts both AgentTool instances and `@tool` decorated functions: +ToolBox accepts both AgentTool instances and `@tool` decorated functions: ```python -from strands.experimental import ToolPool +from strands.experimental import ToolBox from strands.types.tools import AgentTool from strands_tools import calculator @@ -237,7 +237,7 @@ class CustomTool(AgentTool): return "Custom result" # Mix different tool types -pool = ToolPool([ +pool = ToolBox([ calculator, # @tool decorated function CustomTool() # AgentTool instance ]) @@ -246,14 +246,14 @@ pool = ToolPool([ ## Error Handling ```python -from strands.experimental import ToolPool +from strands.experimental import ToolBox def not_a_tool(): """This function is not decorated with @tool""" pass try: - pool = ToolPool([not_a_tool]) + pool = ToolBox([not_a_tool]) except ValueError as e: print(f"Error: {e}") # Function not_a_tool is not decorated with @tool ``` @@ -263,13 +263,13 @@ except ValueError as e: 1. **Use direct function passing**: Pass `@tool` decorated functions directly to the constructor 2. **Module imports**: Use `from_module()` for importing entire tool modules 3. **Clear naming**: Tool names are automatically derived from function names -4. **Type safety**: ToolPool validates that functions are properly decorated +4. **Type safety**: ToolBox validates that functions are properly decorated 5. **Integration**: Use with AgentConfig for complete configuration management ## Example: Complete Workflow ```python -from strands.experimental import ToolPool, AgentConfig +from strands.experimental import ToolBox, AgentConfig from strands import tool import strands_tools @@ -281,7 +281,7 @@ def custom_calculator(expression: str) -> float: return eval(expression) # Note: Use safe evaluation in production # Create tool pool with mixed sources -pool = ToolPool([custom_calculator]) +pool = ToolBox([custom_calculator]) pool.add_tools_from_module(strands_tools) # Create agent configuration diff --git a/mkdocs.yml b/mkdocs.yml index bad3eaec..c44f9da6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,7 +114,7 @@ nav: - Experimental: - Overview: user-guide/concepts/experimental/index.md - AgentConfig: user-guide/concepts/experimental/agent-config.md - - ToolPool: user-guide/concepts/experimental/tool-pool.md + - ToolBox: user-guide/concepts/experimental/tool-box.md - Safety & Security: - Responsible AI: user-guide/safety-security/responsible-ai.md - Guardrails: user-guide/safety-security/guardrails.md From ce0ab2944c01946f7999d7211c1ed3e46d099519 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Wed, 24 Sep 2025 12:05:12 -0400 Subject: [PATCH 12/45] docs: fix method name from toAgent to to_agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update all references to use correct Python method name to_agent() - Maintain consistency with actual implementation 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 20 +++++++++---------- .../user-guide/concepts/experimental/index.md | 4 ++-- .../concepts/experimental/tool-box.md | 6 +++--- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index c9d74252..6acce971 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -10,7 +10,7 @@ The experimental `AgentConfig` provides a declarative way to create configuratio `AgentConfig` allows you to: - Create configuration-based agents from JSON files or dictionaries -- Use the `toAgent()` method for clean agent instantiation +- Use the `to_agent()` method for clean agent instantiation - Integrate with ToolBox for advanced tool management - Use standardized configuration interfaces @@ -28,7 +28,7 @@ config = AgentConfig({ }) # Create agent instance (uses default tools from strands_tools) -agent = config.toAgent() +agent = config.to_agent() ``` ### Using Default Tools @@ -44,7 +44,7 @@ config = AgentConfig({ "prompt": "You are a helpful assistant with file and web capabilities" }) -agent = config.toAgent() +agent = config.to_agent() # Agent now has access to default tools response = agent("Read the contents of README.md and summarize it") @@ -64,7 +64,7 @@ config = AgentConfig({ "tools": ["file_read", "editor"] # Only file operations, no web/shell }) -agent = config.toAgent() +agent = config.to_agent() ``` !!! warning "Requires strands_tools" @@ -77,7 +77,7 @@ Configuration files must use the `file://` prefix: ```python # Load from JSON file config = AgentConfig("file:///path/to/config.json") -agent = config.toAgent() +agent = config.to_agent() ``` Example `config.json`: @@ -105,7 +105,7 @@ config = AgentConfig({ "prompt": "You are a helpful assistant with access to tools" }) -agent = config.toAgent(tools=tools) +agent = config.to_agent(tools=tools) ``` ## Configuration Options @@ -118,14 +118,14 @@ agent = config.toAgent(tools=tools) ### Method Parameters -The `toAgent()` method accepts: +The `to_agent()` method accepts: - `tools`: Optional ToolBox instance to override the configured tools - `**kwargs`: Additional Agent constructor parameters that override config values ```python # Override config values -agent = config.toAgent( +agent = config.to_agent( tools=my_tools, temperature=0.7, max_tokens=1000 @@ -181,7 +181,7 @@ config = AgentConfig({ "tools": ["calculator", "web_search"] # Only these will be available }, tool_box=platform_tools) -agent = config.toAgent() # Agent has only calculator and web_search +agent = config.to_agent() # Agent has only calculator and web_search ``` ## File Path Requirements @@ -287,7 +287,7 @@ try: }, tool_box=tools) # Create agent with selected tools - agent = config.toAgent(temperature=0.3) + agent = config.to_agent(temperature=0.3) # Use the agent response = agent("Calculate the compound interest on $1000 at 5% for 3 years") diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md index a6facad2..fb48e888 100644 --- a/docs/user-guide/concepts/experimental/index.md +++ b/docs/user-guide/concepts/experimental/index.md @@ -11,7 +11,7 @@ Strands Agents includes experimental features that provide enhanced functionalit Declarative configuration-based agent creation with enhanced instantiation patterns. - Create configuration-based agents from JSON files or dictionaries -- Use the `toAgent()` method for clean agent instantiation +- Use the `to_agent()` method for clean agent instantiation - Standardized configuration interfaces with `file://` prefix support - Integration with ToolBox for advanced tool management @@ -48,7 +48,7 @@ config = AgentConfig({ }) # Create agent -agent = config.toAgent(tools=tools) +agent = config.to_agent(tools=tools) # Use the agent response = agent("What time is it and what's 15 * 24?") diff --git a/docs/user-guide/concepts/experimental/tool-box.md b/docs/user-guide/concepts/experimental/tool-box.md index 7562e6ff..87f98a0b 100644 --- a/docs/user-guide/concepts/experimental/tool-box.md +++ b/docs/user-guide/concepts/experimental/tool-box.md @@ -64,7 +64,7 @@ def create_customer_agent(selected_tool_names: list[str], customer_config: dict) config = AgentConfig(customer_config) # Return configured agent with selected tools - return config.toAgent(tools=customer_tools) + return config.to_agent(tools=customer_tools) # Customer usage my_agent = create_customer_agent( @@ -216,7 +216,7 @@ config = AgentConfig({ }) # Create agent with tools -agent = config.toAgent(tools=tools) +agent = config.to_agent(tools=tools) ``` ## Mixed Tool Types @@ -291,7 +291,7 @@ config = AgentConfig({ }) # Create agent with all tools -agent = config.toAgent(tools=pool) +agent = config.to_agent(tools=pool) # Use the agent response = agent("Calculate the compound interest on $1000 at 5% for 3 years") From e59cdc73ec49ed129a81b46bed18ccb79c19408e Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 10:07:23 -0400 Subject: [PATCH 13/45] docs: update experimental features to use ToolRegistry instead of ToolBox MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove ToolBox documentation and navigation references - Update AgentConfig examples to use ToolRegistry from strands.tools.registry - Update import statements and constructor patterns - Fix parameter names: tool_box -> tool_registry - Update all code examples to use process_tools() method 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 86 ++--- .../user-guide/concepts/experimental/index.md | 28 +- .../concepts/experimental/tool-box.md | 300 ------------------ mkdocs.yml | 1 - 4 files changed, 58 insertions(+), 357 deletions(-) delete mode 100644 docs/user-guide/concepts/experimental/tool-box.md diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 6acce971..3a556f7a 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -11,7 +11,7 @@ The experimental `AgentConfig` provides a declarative way to create configuratio - Create configuration-based agents from JSON files or dictionaries - Use the `to_agent()` method for clean agent instantiation -- Integrate with ToolBox for advanced tool management +- Integrate with ToolRegistry for advanced tool management - Use standardized configuration interfaces ## Basic Usage @@ -33,7 +33,7 @@ agent = config.to_agent() ### Using Default Tools -When no ToolBox is provided, AgentConfig automatically loads default tools from `strands_tools`: +When no ToolRegistry is provided, AgentConfig automatically loads default tools from `strands_tools`: ```python from strands.experimental import AgentConfig @@ -68,7 +68,7 @@ agent = config.to_agent() ``` !!! warning "Requires strands_tools" - Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolBox with your own tools. + Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolRegistry with your own tools. ### File Configuration @@ -88,16 +88,18 @@ Example `config.json`: } ``` -## Integration with ToolBox +## Integration with ToolRegistry -`AgentConfig` works seamlessly with `ToolBox` for advanced tool management: +`AgentConfig` works seamlessly with `ToolRegistry` for advanced tool management: ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry from strands_tools import calculator, current_time -# Create tool pool -tools = ToolBox([calculator, current_time]) +# Create tool registry +tool_registry = ToolRegistry() +tool_registry.process_tools([calculator, current_time]) # Create agent with tools config = AgentConfig({ @@ -114,13 +116,13 @@ agent = config.to_agent(tools=tools) - `model`: Model identifier (string) - `prompt`: System prompt for the agent (string) -- `tools`: List of tool names to select from the provided ToolBox (optional) +- `tools`: List of tool names to select from the provided ToolRegistry (optional) ### Method Parameters The `to_agent()` method accepts: -- `tools`: Optional ToolBox instance to override the configured tools +- `tools`: Optional ToolRegistry instance to override the configured tools - `**kwargs`: Additional Agent constructor parameters that override config values ```python @@ -134,7 +136,7 @@ agent = config.to_agent( ## Default Tools Behavior -When no ToolBox is provided, AgentConfig attempts to create a default ToolBox with these tools from `strands_tools`: +When no ToolRegistry is provided, AgentConfig attempts to create a default ToolRegistry with these tools from `strands_tools`: - `file_read` - File reading operations - `editor` - Text editing capabilities @@ -145,10 +147,11 @@ When no ToolBox is provided, AgentConfig attempts to create a default ToolBox wi !!! note "Experimental Tool List" This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. -If `strands_tools` is not installed, you must provide your own ToolBox: +If `strands_tools` is not installed, you must provide your own ToolRegistry: ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry from strands import tool @tool @@ -156,30 +159,32 @@ def my_custom_tool(input: str) -> str: """My custom tool implementation.""" return f"Processed: {input}" -# Create custom ToolBox -custom_tools = ToolBox([my_custom_tool]) +# Create custom ToolRegistry +custom_tool_registry = ToolRegistry() +custom_tool_registry.process_tools([my_custom_tool]) # Use with AgentConfig config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant" -}, tool_box=custom_tools) +}, tool_registry=custom_tool_registry) ``` ## Tool Selection -When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolBox: +When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolRegistry: ```python -# Platform provider creates comprehensive ToolBox -platform_tools = ToolBox([calculator, web_search, file_ops, data_analysis]) +# Platform provider creates comprehensive ToolRegistry +platform_tool_registry = ToolRegistry() +platform_tool_registry.process_tools([calculator, web_search, file_ops, data_analysis]) # Customer selects specific tools config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a research assistant", "tools": ["calculator", "web_search"] # Only these will be available -}, tool_box=platform_tools) +}, tool_registry=platform_tool_registry) agent = config.to_agent() # Agent has only calculator and web_search ``` @@ -211,56 +216,58 @@ except ValueError as e: ### Tool Validation Errors ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry -# Tool not found in ToolBox +# Tool not found in ToolRegistry try: config = AgentConfig({ "model": "test-model", "tools": ["nonexistent_tool"] - }, tool_box=ToolBox()) + }, tool_registry=ToolRegistry()) except ValueError as e: - print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolBox + print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolRegistry ``` ### Missing Dependencies ```python -# When strands_tools not installed and no ToolBox provided +# When strands_tools not installed and no ToolRegistry provided try: config = AgentConfig({"model": "test-model"}) except ImportError as e: print(f"Error: {e}") - # strands_tools is not available and no ToolBox was specified. + # strands_tools is not available and no ToolRegistry was specified. # Either install strands_tools with 'pip install strands-agents-tools' - # or provide your own ToolBox with your own tools. + # or provide your own ToolRegistry with your own tools. ``` -### Tool Configuration Without ToolBox +### Tool Configuration Without ToolRegistry ```python -# Specifying tools without providing ToolBox +# Specifying tools without providing ToolRegistry try: config = AgentConfig({ "model": "test-model", "tools": ["calculator"] - }) # No tool_box parameter + }) # No tool_registry parameter except ValueError as e: - print(f"Error: {e}") # Tool names specified in config but no ToolBox provided + print(f"Error: {e}") # Tool names specified in config but no ToolRegistry provided ``` ## Best Practices 1. **Use file:// prefix**: Always prefix file paths with `file://` 2. **Install strands_tools**: Use `pip install strands-agents-tools` for default tools -3. **Provide custom ToolBox**: Create your own ToolBox if not using strands_tools -4. **Validate tool selection**: Ensure tool names exist in your ToolBox before configuration -5. **Tool registry pattern**: Use ToolBox as a registry for customer tool selection +3. **Provide custom ToolRegistry**: Create your own ToolRegistry if not using strands_tools +4. **Validate tool selection**: Ensure tool names exist in your ToolRegistry before configuration +5. **Tool registry pattern**: Use ToolRegistry as a registry for customer tool selection 6. **Override when needed**: Use kwargs to override config values dynamically 7. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications ## Example: Complete Workflow ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry from strands import tool # Define custom tools @@ -276,15 +283,16 @@ def data_processor(data: str) -> str: return f"Processed: {data}" try: - # Create tool pool with custom tools - tools = ToolBox([custom_calculator, data_processor]) + # Create tool registry with custom tools + tool_registry = ToolRegistry() + tool_registry.process_tools([custom_calculator, data_processor]) # Load configuration with tool selection config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a data analysis assistant", "tools": ["custom_calculator"] # Only calculator available to agent - }, tool_box=tools) + }, tool_registry=tool_registry) # Create agent with selected tools agent = config.to_agent(temperature=0.3) @@ -294,7 +302,7 @@ try: except ImportError as e: print(f"Missing dependencies: {e}") - # Handle by installing strands_tools or providing custom ToolBox + # Handle by installing strands_tools or providing custom ToolRegistry except ValueError as e: print(f"Configuration error: {e}") diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md index fb48e888..875ed771 100644 --- a/docs/user-guide/concepts/experimental/index.md +++ b/docs/user-guide/concepts/experimental/index.md @@ -13,42 +13,36 @@ Declarative configuration-based agent creation with enhanced instantiation patte - Create configuration-based agents from JSON files or dictionaries - Use the `to_agent()` method for clean agent instantiation - Standardized configuration interfaces with `file://` prefix support -- Integration with ToolBox for advanced tool management - -### [ToolBox](tool-box.md) -Tool registry and management system with natural constructor API. - -- Centralized tool registry for single Strands runtime environments -- Customer interface for tool selection and custom agent creation -- Direct tool function passing: `ToolBox([calculator, current_time])` -- Module imports with `ToolBox.from_module()` -- Platform provider capabilities for multi-tenant tool management +- Integration with built-in ToolRegistry for tool management ## Getting Started Import experimental features from the `strands.experimental` namespace: ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig ``` ## Quick Example ```python -from strands.experimental import AgentConfig, ToolBox +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry from strands_tools import calculator, current_time -# Create tool pool -tools = ToolBox([calculator, current_time]) +# Create tool registry +tool_registry = ToolRegistry() +tool_registry.process_tools([calculator, current_time]) # Create agent configuration config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with access to tools" -}) + "prompt": "You are a helpful assistant with access to tools", + "tools": ["calculator", "current_time"] +}, tool_registry=tool_registry) # Create agent -agent = config.to_agent(tools=tools) +agent = config.to_agent() # Use the agent response = agent("What time is it and what's 15 * 24?") diff --git a/docs/user-guide/concepts/experimental/tool-box.md b/docs/user-guide/concepts/experimental/tool-box.md deleted file mode 100644 index 87f98a0b..00000000 --- a/docs/user-guide/concepts/experimental/tool-box.md +++ /dev/null @@ -1,300 +0,0 @@ -# Experimental ToolBox - -!!! warning "Experimental Feature" - This feature is experimental and may change in future versions. Use with caution in production environments. - -The experimental `ToolBox` provides a clean, intuitive way to manage collections of tools with a natural constructor API, serving as a tool registry for a single Strands runtime. - -## Overview - -`ToolBox` is designed as a superset of tools available to the agent framework, providing an interface for customers to create their own agents by selecting from a curated list of available tools. Think of it as a tool registry that manages all tools within a single Strands runtime environment. - -### Key Concepts - -- **Tool Registry**: Centralized management of all available tools -- **Customer Interface**: Enable customers to select tools for their custom agents -- **Runtime Scope**: Manages tools within a single Strands runtime instance -- **Natural API**: Clean, intuitive constructor and method interfaces - -### Use Cases - -- **Platform Providers**: Offer a curated set of tools that customers can choose from -- **Multi-tenant Environments**: Manage tool availability per tenant or customer -- **Agent Marketplaces**: Allow users to build custom agents from available tools -- **Tool Governance**: Control which tools are available in different contexts - -`ToolBox` allows you to: - -- Manage collections of tools with a clean constructor API -- Pass tool functions directly: `ToolBox([calculator, current_time])` -- Import entire modules of tools with `ToolBox.from_module()` -- Integrate seamlessly with Agent instances -- Provide customers with tool selection interfaces - -## Customer Interface Example - -Here's how a platform provider might use ToolBox to offer tool selection to customers: - -```python -from strands.experimental import ToolBox, AgentConfig -from strands_tools import calculator, web_search, file_operations, data_analysis - -# Platform provider creates a comprehensive tool registry -platform_tools = ToolBox([ - calculator, - web_search, - file_operations, - data_analysis, - # ... more tools -]) - -# Customer selects tools for their specific use case -def create_customer_agent(selected_tool_names: list[str], customer_config: dict): - """Allow customers to create agents with selected tools.""" - - # Filter tools based on customer selection - customer_tools = ToolBox() - all_tools = platform_tools.list_tools() - - for tool in all_tools: - if tool.tool_name in selected_tool_names: - customer_tools.add_tool(tool) - - # Create customer's agent configuration - config = AgentConfig(customer_config) - - # Return configured agent with selected tools - return config.to_agent(tools=customer_tools) - -# Customer usage -my_agent = create_customer_agent( - selected_tool_names=["calculator", "web_search"], - customer_config={ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are my research assistant" - } -) -``` - -## Basic Usage - -### Direct Tool Function Passing - -```python -from strands.experimental import ToolBox -from strands_tools import calculator, current_time - -# Create pool with tool functions directly -pool = ToolBox([calculator, current_time]) - -# Use with Agent -from strands import Agent -agent = Agent(tools=pool.list_tools()) -``` - -### Empty Pool with Manual Addition - -```python -from strands.experimental import ToolBox -from strands_tools import calculator - -# Create empty pool -pool = ToolBox() - -# Add tools manually -pool.add_tool_function(calculator) - -# Get tool names -print(pool.list_tool_names()) # ['calculator'] - -# Get AgentTool instances -tools = pool.list_tools() -``` - -## Module Import - -Import all `@tool` decorated functions from a module: - -```python -from strands.experimental import ToolBox -import strands_tools - -# Import all tools from module -pool = ToolBox.from_module(strands_tools) - -# Or add to existing pool -pool = ToolBox() -pool.add_tools_from_module(strands_tools) -``` - -## API Reference - -### Constructor - -```python -ToolBox(tools: list[AgentTool | Callable] | None = None) -``` - -- `tools`: Optional list of AgentTool instances or `@tool` decorated functions - -### Methods - -#### `add_tool_function(tool_func: Callable) -> None` - -Add a `@tool` decorated function to the pool. - -```python -from strands import tool - -@tool -def my_calculator(a: int, b: int) -> int: - """Add two numbers.""" - return a + b - -pool = ToolBox() -pool.add_tool_function(my_calculator) -``` - -#### `add_tools_from_module(module: any) -> None` - -Add all `@tool` decorated functions from a module. - -```python -import my_tools_module - -pool = ToolBox() -pool.add_tools_from_module(my_tools_module) -``` - -#### `list_tool_names() -> list[str]` - -Get a list of all tool names in the pool. - -```python -pool = ToolBox([calculator, current_time]) -names = pool.list_tool_names() # ['calculator', 'current_time'] -``` - -#### `list_tools() -> list[AgentTool]` - -Get all tools as AgentTool instances for use with Agent. - -```python -pool = ToolBox([calculator, current_time]) -agent_tools = pool.list_tools() - -# Use with Agent -agent = Agent(tools=agent_tools) -``` - -#### `from_module(module: any) -> ToolBox` (Class Method) - -Create a ToolBox from all `@tool` functions in a module. - -```python -import strands_tools - -# Create pool from entire module -pool = ToolBox.from_module(strands_tools) -``` - -## Integration with AgentConfig - -ToolBox works seamlessly with the experimental AgentConfig: - -```python -from strands.experimental import AgentConfig, ToolBox -from strands_tools import calculator, web_search - -# Create tool pool -tools = ToolBox([calculator, web_search]) - -# Create agent config -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with access to tools" -}) - -# Create agent with tools -agent = config.to_agent(tools=tools) -``` - -## Mixed Tool Types - -ToolBox accepts both AgentTool instances and `@tool` decorated functions: - -```python -from strands.experimental import ToolBox -from strands.types.tools import AgentTool -from strands_tools import calculator - -# Custom AgentTool -class CustomTool(AgentTool): - def __init__(self): - super().__init__(tool_name="custom_tool") - - def invoke(self, input_data, context): - return "Custom result" - -# Mix different tool types -pool = ToolBox([ - calculator, # @tool decorated function - CustomTool() # AgentTool instance -]) -``` - -## Error Handling - -```python -from strands.experimental import ToolBox - -def not_a_tool(): - """This function is not decorated with @tool""" - pass - -try: - pool = ToolBox([not_a_tool]) -except ValueError as e: - print(f"Error: {e}") # Function not_a_tool is not decorated with @tool -``` - -## Best Practices - -1. **Use direct function passing**: Pass `@tool` decorated functions directly to the constructor -2. **Module imports**: Use `from_module()` for importing entire tool modules -3. **Clear naming**: Tool names are automatically derived from function names -4. **Type safety**: ToolBox validates that functions are properly decorated -5. **Integration**: Use with AgentConfig for complete configuration management - -## Example: Complete Workflow - -```python -from strands.experimental import ToolBox, AgentConfig -from strands import tool -import strands_tools - -# Define custom tool -@tool -def custom_calculator(expression: str) -> float: - """Evaluate a mathematical expression safely.""" - # Safe evaluation logic here - return eval(expression) # Note: Use safe evaluation in production - -# Create tool pool with mixed sources -pool = ToolBox([custom_calculator]) -pool.add_tools_from_module(strands_tools) - -# Create agent configuration -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a mathematical assistant with access to calculation tools" -}) - -# Create agent with all tools -agent = config.to_agent(tools=pool) - -# Use the agent -response = agent("Calculate the compound interest on $1000 at 5% for 3 years") -``` - -This experimental feature provides a foundation for more intuitive tool management while maintaining compatibility with the existing Agent and tool infrastructure. diff --git a/mkdocs.yml b/mkdocs.yml index c44f9da6..d727f2f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,7 +114,6 @@ nav: - Experimental: - Overview: user-guide/concepts/experimental/index.md - AgentConfig: user-guide/concepts/experimental/agent-config.md - - ToolBox: user-guide/concepts/experimental/tool-box.md - Safety & Security: - Responsible AI: user-guide/safety-security/responsible-ai.md - Guardrails: user-guide/safety-security/guardrails.md From 8b41270d28fb305776e067858418436dde0fc31f Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:27:15 -0400 Subject: [PATCH 14/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 3a556f7a..a1c66d5e 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -1,4 +1,4 @@ -# Experimental AgentConfig +# AgentConfig [Experimental] !!! warning "Experimental Feature" This feature is experimental and may change in future versions. Use with caution in production environments. From ac52d8f3e72280ce689b0f37d86649251cc8f64e Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:27:26 -0400 Subject: [PATCH 15/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index a1c66d5e..c3f79081 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -11,7 +11,7 @@ The experimental `AgentConfig` provides a declarative way to create configuratio - Create configuration-based agents from JSON files or dictionaries - Use the `to_agent()` method for clean agent instantiation -- Integrate with ToolRegistry for advanced tool management +- Integrate with [ToolRegistry](https://strandsagents.com/latest/documentation/docs/api-reference/tools/#strands.tools.registry.ToolRegistry) for advanced tool management - Use standardized configuration interfaces ## Basic Usage From ea559b5f7c16074d48297bc492d52a9423fa1b85 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:27:34 -0400 Subject: [PATCH 16/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index c3f79081..aed771dd 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -23,7 +23,7 @@ from strands.experimental import AgentConfig # Create config from dictionary config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant" }) From 347e315440eeb4ffa6c83abaf2aaa4401c992c8b Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:28:18 -0400 Subject: [PATCH 17/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index aed771dd..223a1c5c 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -93,13 +93,6 @@ Example `config.json`: `AgentConfig` works seamlessly with `ToolRegistry` for advanced tool management: ```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry -from strands_tools import calculator, current_time - -# Create tool registry -tool_registry = ToolRegistry() -tool_registry.process_tools([calculator, current_time]) # Create agent with tools config = AgentConfig({ From a265a8ea53bf66ab3c52526310e938740b31b413 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:29:05 -0400 Subject: [PATCH 18/45] Apply suggestions from code review Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 223a1c5c..72689631 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -97,10 +97,9 @@ Example `config.json`: # Create agent with tools config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with access to tools" + "prompt": "You are a helpful assistant with access to tools", + "tools": ["say", "current_time"] # Loads the say and current_time tool, but not the calculator tool }) - -agent = config.to_agent(tools=tools) ``` ## Configuration Options @@ -138,7 +137,7 @@ When no ToolRegistry is provided, AgentConfig attempts to create a default ToolR - `use_agent` - Agent delegation !!! note "Experimental Tool List" - This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. + This is a short list of tools that we think are useful when building agents. The list is experimental and will be revisited as tools evolve. If `strands_tools` is not installed, you must provide your own ToolRegistry: @@ -226,7 +225,8 @@ except ValueError as e: ```python # When strands_tools not installed and no ToolRegistry provided try: - config = AgentConfig({"model": "test-model"}) + config = AgentConfig({"model": "test-model", "tools": ["file_read"]}) + except ImportError as e: print(f"Error: {e}") # strands_tools is not available and no ToolRegistry was specified. From 2624b8199ea257128d4be4e74716d19e76914f6b Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:35:25 -0400 Subject: [PATCH 19/45] docs: comprehensive improvements to experimental AgentConfig documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove top-level experimental index file and update navigation - Fix invalid Agent parameter (temperature -> agent_id, name, description) - Add raise_exception_on_missing_tool parameter documentation - Update Tool Validation Errors and Tool Configuration sections with error handling - Add GitHub links to all default tools in strands-agents/tools repo - Combine Default Tools Behavior with Using Default Tools section - Add Agent class parameter override examples (agent_id, name) - Change Using Default Tools example to pirate agent without tools requirement - Improve error handling examples and best practices - Add comprehensive workflow example with proper error handling 🤖 Assisted by Amazon Q Developer --- .../user-guide/concepts/experimental/index.md | 78 ------------------- mkdocs.yml | 1 - 2 files changed, 79 deletions(-) delete mode 100644 docs/user-guide/concepts/experimental/index.md diff --git a/docs/user-guide/concepts/experimental/index.md b/docs/user-guide/concepts/experimental/index.md deleted file mode 100644 index 875ed771..00000000 --- a/docs/user-guide/concepts/experimental/index.md +++ /dev/null @@ -1,78 +0,0 @@ -# Experimental Features - -!!! warning "Experimental Features" - The features in this section are experimental and may change in future versions. Use with caution in production environments. - -Strands Agents includes experimental features that provide enhanced functionality and improved developer experience. These features are designed to be forward-compatible but may undergo changes based on user feedback and evolving requirements. - -## Available Experimental Features - -### [AgentConfig](agent-config.md) -Declarative configuration-based agent creation with enhanced instantiation patterns. - -- Create configuration-based agents from JSON files or dictionaries -- Use the `to_agent()` method for clean agent instantiation -- Standardized configuration interfaces with `file://` prefix support -- Integration with built-in ToolRegistry for tool management - -## Getting Started - -Import experimental features from the `strands.experimental` namespace: - -```python -from strands.experimental import AgentConfig -``` - -## Quick Example - -```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry -from strands_tools import calculator, current_time - -# Create tool registry -tool_registry = ToolRegistry() -tool_registry.process_tools([calculator, current_time]) - -# Create agent configuration -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with access to tools", - "tools": ["calculator", "current_time"] -}, tool_registry=tool_registry) - -# Create agent -agent = config.to_agent() - -# Use the agent -response = agent("What time is it and what's 15 * 24?") -``` - -## Design Principles - -The experimental features follow these design principles: - -1. **Natural APIs**: Intuitive interfaces that feel natural to Python developers -2. **Backward Compatibility**: Work alongside existing Strands Agent features -3. **Type Safety**: Full type hints with modern Python typing syntax -4. **Composability**: Features work together seamlessly -5. **Standards Compliance**: Follow established patterns and conventions - -## Feedback and Evolution - -These experimental features are actively developed based on user feedback. If you have suggestions or encounter issues, please: - -1. Check the existing documentation and examples -2. Review the test cases in the SDK for additional usage patterns -3. Provide feedback through the appropriate channels - -## Migration Path - -When experimental features graduate to stable status: - -1. They will be moved to the main API namespace -2. Backward compatibility will be maintained during transition periods -3. Clear migration guides will be provided -4. Deprecation warnings will be issued for experimental namespaces - -The experimental namespace provides a safe space to iterate on new features while maintaining stability in the core API. diff --git a/mkdocs.yml b/mkdocs.yml index d727f2f5..66601d72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,7 +112,6 @@ nav: - Workflow: user-guide/concepts/multi-agent/workflow.md - Multi-agent Patterns: user-guide/concepts/multi-agent/multi-agent-patterns.md - Experimental: - - Overview: user-guide/concepts/experimental/index.md - AgentConfig: user-guide/concepts/experimental/agent-config.md - Safety & Security: - Responsible AI: user-guide/safety-security/responsible-ai.md From 9fe8fd2d134061ddb830dfac2cdad5467e268525 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:43:16 -0400 Subject: [PATCH 20/45] docs: fix Using Default Tools example to use pirate agent without tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update lines 39-51 to show pirate agent example instead of file operations - Remove tool dependency from the basic example as requested 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 72689631..ed7ea147 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -38,16 +38,16 @@ When no ToolRegistry is provided, AgentConfig automatically loads default tools ```python from strands.experimental import AgentConfig -# This will use the default tools: file_read, editor, http_request, shell, use_agent +# Simple agent without tools config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with file and web capabilities" + "prompt": "You are a helpful assistant who talks like a pirate. Always respond with 'Ahoy!' and use pirate language." }) agent = config.to_agent() -# Agent now has access to default tools -response = agent("Read the contents of README.md and summarize it") +# Agent will respond in pirate language +response = agent("Hello, how are you today?") ``` ### Selecting from Default Tools From 1e3bfda65e5a731b35fb8b51d513469715696ace Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:44:50 -0400 Subject: [PATCH 21/45] docs: add model provider documentation reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add link to model provider docs for model identifier usage - Reference quickstart guide for string model ID usage 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index ed7ea147..71cc61d0 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -106,7 +106,7 @@ config = AgentConfig({ ### Supported Keys -- `model`: Model identifier (string) +- `model`: Model identifier (string) - see [model provider documentation](https://strandsagents.com/latest/user-guide/quickstart/#using-a-string-model-id) - `prompt`: System prompt for the agent (string) - `tools`: List of tool names to select from the provided ToolRegistry (optional) From 29214b9c37660e24ce4473f8adb1833827b4b794 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:49:43 -0400 Subject: [PATCH 22/45] docs: move agent config JSON examples inline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add simple-agent.json and coding-assistant.json examples inline to documentation - Remove separate agent-configs directory and files - Improve file configuration section with concrete examples 🤖 Assisted by Amazon Q Developer --- .../agent-configs/coding-assistant.json | 5 ----- docs/examples/agent-configs/simple-agent.json | 4 ---- .../concepts/experimental/agent-config.md | 17 ++++++++++++++--- 3 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 docs/examples/agent-configs/coding-assistant.json delete mode 100644 docs/examples/agent-configs/simple-agent.json diff --git a/docs/examples/agent-configs/coding-assistant.json b/docs/examples/agent-configs/coding-assistant.json deleted file mode 100644 index bafa2127..00000000 --- a/docs/examples/agent-configs/coding-assistant.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a coding assistant. Help users write, debug, and improve their code. You have access to file operations and can execute shell commands when needed.", - "tools": ["shell", "file_read", "editor"] -} diff --git a/docs/examples/agent-configs/simple-agent.json b/docs/examples/agent-configs/simple-agent.json deleted file mode 100644 index 080fe346..00000000 --- a/docs/examples/agent-configs/simple-agent.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "model": "us.anthropic.claude-3-haiku-20240307-v1:0", - "prompt": "You are a helpful assistant." -} diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 71cc61d0..d99ce02d 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -80,11 +80,22 @@ config = AgentConfig("file:///path/to/config.json") agent = config.to_agent() ``` -Example `config.json`: +#### Simple Agent Example + ```json { - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant specialized in data analysis" + "model": "us.anthropic.claude-3-haiku-20240307-v1:0", + "prompt": "You are a helpful assistant." +} +``` + +#### Coding Assistant Example + +```json +{ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a coding assistant. Help users write, debug, and improve their code. You have access to file operations and can execute shell commands when needed.", + "tools": ["shell", "file_read", "editor"] } ``` From 4ec30f811f436799f1a92743948fbb4faabd22b5 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:52:38 -0400 Subject: [PATCH 23/45] docs: add GitHub links to default tools in AgentConfig MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Link each default tool to its source code in strands-agents/tools repo - Make file_read, editor, http_request, shell, and use_agent clickable links 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index d99ce02d..048fae52 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -141,11 +141,11 @@ agent = config.to_agent( When no ToolRegistry is provided, AgentConfig attempts to create a default ToolRegistry with these tools from `strands_tools`: -- `file_read` - File reading operations -- `editor` - Text editing capabilities -- `http_request` - HTTP requests -- `shell` - Shell command execution -- `use_agent` - Agent delegation +- [`file_read`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/file_read.py) - File reading operations +- [`editor`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/editor.py) - Text editing capabilities +- [`http_request`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/http_request.py) - HTTP requests +- [`shell`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/shell.py) - Shell command execution +- [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation !!! note "Experimental Tool List" This is a short list of tools that we think are useful when building agents. The list is experimental and will be revisited as tools evolve. From 830ef23204cf21fa879b8e1696338a72e4be498c Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:54:19 -0400 Subject: [PATCH 24/45] docs: fix invalid Agent parameters in AgentConfig examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace temperature, max_tokens with valid Agent parameters - Use agent_id, name, description which are actual Agent constructor parameters - Fix both examples at lines 133-136 and line 302 🤖 Assisted by Amazon Q Developer --- .../user-guide/concepts/experimental/agent-config.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 048fae52..8d01ad6b 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -129,11 +129,11 @@ The `to_agent()` method accepts: - `**kwargs`: Additional Agent constructor parameters that override config values ```python -# Override config values +# Override config values with valid Agent parameters agent = config.to_agent( - tools=my_tools, - temperature=0.7, - max_tokens=1000 + agent_id="my-agent-123", + name="Data Analyst", + description="Specialized data analysis agent" ) ``` @@ -298,8 +298,8 @@ try: "tools": ["custom_calculator"] # Only calculator available to agent }, tool_registry=tool_registry) - # Create agent with selected tools - agent = config.to_agent(temperature=0.3) + # Create agent with selected tools and override parameters + agent = config.to_agent(agent_id="data-analyst-001", name="Data Analyst") # Use the agent response = agent("Calculate the compound interest on $1000 at 5% for 3 years") From 9e5802622672d05d7b4babd3ce84446ddd1c1a3e Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:55:25 -0400 Subject: [PATCH 25/45] docs: update line 112 to use file_read and editor tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace say and current_time with file_read and editor tools - Use consistent tool examples throughout documentation 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 8d01ad6b..69b8f90b 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -109,7 +109,7 @@ agent = config.to_agent() config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant with access to tools", - "tools": ["say", "current_time"] # Loads the say and current_time tool, but not the calculator tool + "tools": ["file_read", "editor"] }) ``` From d41a2d249d1f4105ff6b700fb41ea8c94fc1a713 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:57:15 -0400 Subject: [PATCH 26/45] docs: consolidate Default Tools Behavior into Using Default Tools section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move tools list and custom ToolRegistry example up to Using Default Tools - Remove duplicate Default Tools Behavior section - Improve organization and reduce redundancy 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 68 +++++++++---------- 1 file changed, 32 insertions(+), 36 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 69b8f90b..03476c75 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -35,6 +35,15 @@ agent = config.to_agent() When no ToolRegistry is provided, AgentConfig automatically loads default tools from `strands_tools`: +- [`file_read`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/file_read.py) - File reading operations +- [`editor`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/editor.py) - Text editing capabilities +- [`http_request`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/http_request.py) - HTTP requests +- [`shell`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/shell.py) - Shell command execution +- [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation + +!!! note "Experimental Tool List" + This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. + ```python from strands.experimental import AgentConfig @@ -50,6 +59,29 @@ agent = config.to_agent() response = agent("Hello, how are you today?") ``` +If `strands_tools` is not installed, you must provide your own ToolRegistry: + +```python +from strands.experimental import AgentConfig +from strands.tools.registry import ToolRegistry +from strands import tool + +@tool +def my_custom_tool(input: str) -> str: + """My custom tool implementation.""" + return f"Processed: {input}" + +# Create custom ToolRegistry +custom_tool_registry = ToolRegistry() +custom_tool_registry.process_tools([my_custom_tool]) + +# Use with AgentConfig +config = AgentConfig({ + "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "prompt": "You are a helpful assistant" +}, tool_registry=custom_tool_registry) +``` + ### Selecting from Default Tools You can also select specific tools from the default set: @@ -137,42 +169,6 @@ agent = config.to_agent( ) ``` -## Default Tools Behavior - -When no ToolRegistry is provided, AgentConfig attempts to create a default ToolRegistry with these tools from `strands_tools`: - -- [`file_read`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/file_read.py) - File reading operations -- [`editor`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/editor.py) - Text editing capabilities -- [`http_request`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/http_request.py) - HTTP requests -- [`shell`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/shell.py) - Shell command execution -- [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation - -!!! note "Experimental Tool List" - This is a short list of tools that we think are useful when building agents. The list is experimental and will be revisited as tools evolve. - -If `strands_tools` is not installed, you must provide your own ToolRegistry: - -```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry -from strands import tool - -@tool -def my_custom_tool(input: str) -> str: - """My custom tool implementation.""" - return f"Processed: {input}" - -# Create custom ToolRegistry -custom_tool_registry = ToolRegistry() -custom_tool_registry.process_tools([my_custom_tool]) - -# Use with AgentConfig -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant" -}, tool_registry=custom_tool_registry) -``` - ## Tool Selection When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolRegistry: From f075561577cb899e25d6e9ec78efc9e235b5d611 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 18:59:11 -0400 Subject: [PATCH 27/45] docs: fix inaccurate description of default tools behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarify that AgentConfig instantiates a default ToolRegistry with subset of strands_tools - More accurate than saying it 'loads default tools' - Emphasizes tool selection capability 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 03476c75..f67b7fb5 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -33,7 +33,7 @@ agent = config.to_agent() ### Using Default Tools -When no ToolRegistry is provided, AgentConfig automatically loads default tools from `strands_tools`: +When no ToolRegistry is provided, AgentConfig automatically instantiates a default ToolRegistry with a subset of the strands_tools from which you can select for your agent: - [`file_read`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/file_read.py) - File reading operations - [`editor`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/editor.py) - Text editing capabilities From a9630754822d25f4285d20ee6f470a1b3540802b Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 19:02:19 -0400 Subject: [PATCH 28/45] docs: update agent example to use file_read tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Change from pirate agent to file system assistant - Add file_read tool to demonstrate tool usage - Update prompt and example interaction to show file system capabilities 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index f67b7fb5..13363747 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -42,21 +42,22 @@ When no ToolRegistry is provided, AgentConfig automatically instantiates a defau - [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation !!! note "Experimental Tool List" - This is a minimum viable list of tools to enable agent building. The list is experimental and will be revisited as tools evolve. + This is a minimal list of tools to get you started with building your own agent. ```python from strands.experimental import AgentConfig -# Simple agent without tools +# Agent with file_read tool config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant who talks like a pirate. Always respond with 'Ahoy!' and use pirate language." + "prompt": "You are a helpful assistant that can help answer questions about your file system.", + "tools": ["file_read"] }) agent = config.to_agent() -# Agent will respond in pirate language -response = agent("Hello, how are you today?") +# Agent can read files and answer questions about the file system +response = agent("What's in my README.md file?") ``` If `strands_tools` is not installed, you must provide your own ToolRegistry: From 4a6e953f96543ab9e4690a3a0f9ed526e76fb26d Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 19:03:31 -0400 Subject: [PATCH 29/45] docs: add back experimental caveat to tool list note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restore warning that tool list is experimental and will be revisited - Keep both user-friendly description and experimental warning 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 13363747..cde967d4 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -42,7 +42,7 @@ When no ToolRegistry is provided, AgentConfig automatically instantiates a defau - [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation !!! note "Experimental Tool List" - This is a minimal list of tools to get you started with building your own agent. + This is a minimal list of tools to get you started with building your own agent. The list is experimental and will be revisited as tools evolve. ```python from strands.experimental import AgentConfig From 5b6e8785b7e424aca3e7b42c453bc4d3270ee6e9 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 19:24:52 -0400 Subject: [PATCH 30/45] docs: remove duplicate Selecting from Default Tools section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Delete redundant section that was duplicated in the documentation - Keep content organized and avoid repetition 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index cde967d4..49696cb0 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -83,26 +83,6 @@ config = AgentConfig({ }, tool_registry=custom_tool_registry) ``` -### Selecting from Default Tools - -You can also select specific tools from the default set: - -```python -from strands.experimental import AgentConfig - -# Select only specific default tools -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a file management assistant", - "tools": ["file_read", "editor"] # Only file operations, no web/shell -}) - -agent = config.to_agent() -``` - -!!! warning "Requires strands_tools" - Default tools require `pip install strands-agents-tools`. If not installed, you will have to configure your own ToolRegistry with your own tools. - ### File Configuration Configuration files must use the `file://` prefix: From 3e84a3e8c2a3bfa4461a7dc5fe9ff7b5cd6da5a1 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Thu, 25 Sep 2025 19:26:47 -0400 Subject: [PATCH 31/45] docs: update error handling sections for raise_exception_on_missing_tool parameter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update Tool Validation Errors to show both strict and lenient behaviors - Update Missing Dependencies section with parameter usage examples - Update Tool Configuration Without ToolRegistry section - Add best practice for controlling error behavior - Show examples of skipping missing tools vs raising exceptions 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 49696cb0..4272a399 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -199,39 +199,56 @@ except ValueError as e: from strands.experimental import AgentConfig from strands.tools.registry import ToolRegistry -# Tool not found in ToolRegistry +# Tool not found in ToolRegistry (with raise_exception_on_missing_tool=True, default behavior) try: config = AgentConfig({ "model": "test-model", "tools": ["nonexistent_tool"] - }, tool_registry=ToolRegistry()) + }, tool_registry=ToolRegistry(), raise_exception_on_missing_tool=True) except ValueError as e: - print(f"Error: {e}") # Tool 'nonexistent_tool' not found in ToolRegistry + print(f"Error: {e}") # Tool(s) 'nonexistent_tool' not found in ToolRegistry + +# Skip missing tools instead of raising errors +config = AgentConfig({ + "model": "test-model", + "tools": ["existing_tool", "nonexistent_tool"] +}, tool_registry=my_tool_registry, raise_exception_on_missing_tool=False) +# Only existing_tool will be available, nonexistent_tool is silently skipped ``` ### Missing Dependencies ```python -# When strands_tools not installed and no ToolRegistry provided +# When strands_tools not installed and no ToolRegistry provided (with raise_exception_on_missing_tool=True) try: - config = AgentConfig({"model": "test-model", "tools": ["file_read"]}) - + config = AgentConfig({"model": "test-model", "tools": ["file_read"]}, raise_exception_on_missing_tool=True) except ImportError as e: print(f"Error: {e}") # strands_tools is not available and no ToolRegistry was specified. # Either install strands_tools with 'pip install strands-agents-tools' # or provide your own ToolRegistry with your own tools. + +# Skip missing tools when strands_tools not available +config = AgentConfig({"model": "test-model", "tools": ["file_read"]}, raise_exception_on_missing_tool=False) +# Will create agent without any tools since strands_tools is not available ``` ### Tool Configuration Without ToolRegistry ```python -# Specifying tools without providing ToolRegistry +# Specifying tools without providing ToolRegistry (with raise_exception_on_missing_tool=True) try: config = AgentConfig({ "model": "test-model", "tools": ["calculator"] - }) # No tool_registry parameter + }, raise_exception_on_missing_tool=True) # No tool_registry parameter except ValueError as e: - print(f"Error: {e}") # Tool names specified in config but no ToolRegistry provided + print(f"Error: {e}") # Tool(s) not found in ToolRegistry + +# Skip missing tools when no ToolRegistry provided +config = AgentConfig({ + "model": "test-model", + "tools": ["calculator"] +}, raise_exception_on_missing_tool=False) # No tool_registry parameter +# Will attempt to use default ToolRegistry, skip unavailable tools ``` ## Best Practices @@ -243,6 +260,7 @@ except ValueError as e: 5. **Tool registry pattern**: Use ToolRegistry as a registry for customer tool selection 6. **Override when needed**: Use kwargs to override config values dynamically 7. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications +8. **Control error behavior**: Use `raise_exception_on_missing_tool=False` to skip missing tools instead of failing ## Example: Complete Workflow From 26e2fc8142e6eda5752a9f92858a3eabfa1d481e Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 15:59:39 -0400 Subject: [PATCH 32/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 4272a399..22b550c4 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -257,10 +257,9 @@ config = AgentConfig({ 2. **Install strands_tools**: Use `pip install strands-agents-tools` for default tools 3. **Provide custom ToolRegistry**: Create your own ToolRegistry if not using strands_tools 4. **Validate tool selection**: Ensure tool names exist in your ToolRegistry before configuration -5. **Tool registry pattern**: Use ToolRegistry as a registry for customer tool selection -6. **Override when needed**: Use kwargs to override config values dynamically -7. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications -8. **Control error behavior**: Use `raise_exception_on_missing_tool=False` to skip missing tools instead of failing +5. **Override when needed**: Use kwargs in `to_agent` to override Agent parameters values dynamically +6. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications +7. **Control error behavior**: Use `raise_exception_on_missing_tool=False` to skip missing tools instead of failing ## Example: Complete Workflow From d3e0074215ccad7251fb01606ec586d4d8688a47 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:00:10 -0400 Subject: [PATCH 33/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 22b550c4..695f3dc4 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -49,7 +49,6 @@ from strands.experimental import AgentConfig # Agent with file_read tool config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant that can help answer questions about your file system.", "tools": ["file_read"] }) From c0a791f1a287923972cb65367a92bfb42c2fdc7b Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:00:22 -0400 Subject: [PATCH 34/45] Update docs/user-guide/concepts/experimental/agent-config.md Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 695f3dc4..35d04723 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -78,7 +78,8 @@ custom_tool_registry.process_tools([my_custom_tool]) # Use with AgentConfig config = AgentConfig({ "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant" + "prompt": "You are a helpful assistant", + "tools": ["my_custom_tool"] }, tool_registry=custom_tool_registry) ``` From 857a64b06e182d274a9bcd14f7c5ea991f287e6e Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:00:53 -0400 Subject: [PATCH 35/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 35d04723..47c1bb0e 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -77,7 +77,6 @@ custom_tool_registry.process_tools([my_custom_tool]) # Use with AgentConfig config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant", "tools": ["my_custom_tool"] }, tool_registry=custom_tool_registry) From a16c847b25131d24d4e760d9e61999a39f15a44b Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:01:01 -0400 Subject: [PATCH 36/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 47c1bb0e..a25590fa 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -87,10 +87,10 @@ config = AgentConfig({ Configuration files must use the `file://` prefix: ```python +from strands.experimental import AgentConfig # Load from JSON file config = AgentConfig("file:///path/to/config.json") agent = config.to_agent() -``` #### Simple Agent Example From 79f488ca7b86fba8d23df0e4fad7cdd869fdfde2 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:01:11 -0400 Subject: [PATCH 37/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index a25590fa..00f4f97e 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -96,7 +96,6 @@ agent = config.to_agent() ```json { - "model": "us.anthropic.claude-3-haiku-20240307-v1:0", "prompt": "You are a helpful assistant." } ``` From c5e121aeb369203b2df175937c1c726d0ff84a31 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:01:26 -0400 Subject: [PATCH 38/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- .../concepts/experimental/agent-config.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 00f4f97e..89fb07ca 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -110,19 +110,6 @@ agent = config.to_agent() } ``` -## Integration with ToolRegistry - -`AgentConfig` works seamlessly with `ToolRegistry` for advanced tool management: - -```python - -# Create agent with tools -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a helpful assistant with access to tools", - "tools": ["file_read", "editor"] -}) -``` ## Configuration Options From 48508677217c55677b2a7f8cc1b3f4ff9cf0c4a2 Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:01:35 -0400 Subject: [PATCH 39/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 89fb07ca..a199dcab 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -104,7 +104,7 @@ agent = config.to_agent() ```json { - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", + "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a coding assistant. Help users write, debug, and improve their code. You have access to file operations and can execute shell commands when needed.", "tools": ["shell", "file_read", "editor"] } From 915b0c08e5adb303d16f5d15871a9ab3f308127e Mon Sep 17 00:00:00 2001 From: Matt Lee <1302416+mr-lee@users.noreply.github.com> Date: Fri, 26 Sep 2025 16:01:43 -0400 Subject: [PATCH 40/45] Apply suggestion from @Unshure Co-authored-by: Nick Clegg --- docs/user-guide/concepts/experimental/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index a199dcab..6f6c6087 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -124,7 +124,7 @@ agent = config.to_agent() The `to_agent()` method accepts: - `tools`: Optional ToolRegistry instance to override the configured tools -- `**kwargs`: Additional Agent constructor parameters that override config values +- `**kwargs`: Additional [Agent constructor parameters](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent.Agent.__init__) that override config values ```python # Override config values with valid Agent parameters From 89343e7bee937539017d9e62b3370f29bcf71522 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Fri, 26 Sep 2025 16:02:58 -0400 Subject: [PATCH 41/45] docs: remove Example: Complete Workflow section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove lengthy example section to simplify documentation - Keep concise closing statement about experimental feature 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 46 ------------------- 1 file changed, 46 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 6f6c6087..c57ebb0b 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -246,50 +246,4 @@ config = AgentConfig({ 6. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications 7. **Control error behavior**: Use `raise_exception_on_missing_tool=False` to skip missing tools instead of failing -## Example: Complete Workflow - -```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry -from strands import tool - -# Define custom tools -@tool -def custom_calculator(expression: str) -> float: - """Evaluate a mathematical expression safely.""" - # Safe evaluation logic here - return eval(expression) # Note: Use safe evaluation in production - -@tool -def data_processor(data: str) -> str: - """Process data with custom logic.""" - return f"Processed: {data}" - -try: - # Create tool registry with custom tools - tool_registry = ToolRegistry() - tool_registry.process_tools([custom_calculator, data_processor]) - - # Load configuration with tool selection - config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a data analysis assistant", - "tools": ["custom_calculator"] # Only calculator available to agent - }, tool_registry=tool_registry) - - # Create agent with selected tools and override parameters - agent = config.to_agent(agent_id="data-analyst-001", name="Data Analyst") - - # Use the agent - response = agent("Calculate the compound interest on $1000 at 5% for 3 years") - -except ImportError as e: - print(f"Missing dependencies: {e}") - # Handle by installing strands_tools or providing custom ToolRegistry - -except ValueError as e: - print(f"Configuration error: {e}") - # Handle tool validation or file path errors -``` - This experimental feature provides a foundation for more advanced agent configuration patterns while maintaining compatibility with the existing Agent API. From c8b9859277cfe4ee201c93975327d16f45792ebe Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Fri, 26 Sep 2025 18:36:29 -0400 Subject: [PATCH 42/45] docs: update agent-config.md for new config_to_agent function MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace AgentConfig class documentation with config_to_agent function - Update all examples to use new functional interface - Remove ToolRegistry complexity from documentation - Add migration guide from old AgentConfig class - Simplify error handling examples to match Agent class behavior - Update tool loading examples to use Agent's standard formats 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 263 +++++++----------- 1 file changed, 98 insertions(+), 165 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index c57ebb0b..e6536eae 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -1,97 +1,44 @@ -# AgentConfig [Experimental] +# Agent Configuration [Experimental] !!! warning "Experimental Feature" This feature is experimental and may change in future versions. Use with caution in production environments. -The experimental `AgentConfig` provides a declarative way to create configuration-based agents with enhanced instantiation patterns. +The experimental `config_to_agent` function provides a simple way to create agents from configuration files or dictionaries. ## Overview -`AgentConfig` allows you to: +`config_to_agent` allows you to: -- Create configuration-based agents from JSON files or dictionaries -- Use the `to_agent()` method for clean agent instantiation -- Integrate with [ToolRegistry](https://strandsagents.com/latest/documentation/docs/api-reference/tools/#strands.tools.registry.ToolRegistry) for advanced tool management -- Use standardized configuration interfaces +- Create agents from JSON files or dictionaries +- Use a simple functional interface for agent instantiation +- Support both file paths and dictionary configurations +- Leverage the Agent class's built-in tool loading capabilities ## Basic Usage ### Dictionary Configuration ```python -from strands.experimental import AgentConfig +from strands.experimental import config_to_agent -# Create config from dictionary -config = AgentConfig({ +# Create agent from dictionary +agent = config_to_agent({ "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a helpful assistant" }) - -# Create agent instance (uses default tools from strands_tools) -agent = config.to_agent() ``` -### Using Default Tools - -When no ToolRegistry is provided, AgentConfig automatically instantiates a default ToolRegistry with a subset of the strands_tools from which you can select for your agent: - -- [`file_read`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/file_read.py) - File reading operations -- [`editor`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/editor.py) - Text editing capabilities -- [`http_request`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/http_request.py) - HTTP requests -- [`shell`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/shell.py) - Shell command execution -- [`use_agent`](https://github.com/strands-agents/tools/blob/main/src/strands_tools/use_agent.py) - Agent delegation - -!!! note "Experimental Tool List" - This is a minimal list of tools to get you started with building your own agent. The list is experimental and will be revisited as tools evolve. +### File Configuration ```python -from strands.experimental import AgentConfig - -# Agent with file_read tool -config = AgentConfig({ - "prompt": "You are a helpful assistant that can help answer questions about your file system.", - "tools": ["file_read"] -}) +from strands.experimental import config_to_agent -agent = config.to_agent() - -# Agent can read files and answer questions about the file system -response = agent("What's in my README.md file?") +# Load from JSON file (with or without file:// prefix) +agent = config_to_agent("/path/to/config.json") +# or +agent = config_to_agent("file:///path/to/config.json") ``` -If `strands_tools` is not installed, you must provide your own ToolRegistry: - -```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry -from strands import tool - -@tool -def my_custom_tool(input: str) -> str: - """My custom tool implementation.""" - return f"Processed: {input}" - -# Create custom ToolRegistry -custom_tool_registry = ToolRegistry() -custom_tool_registry.process_tools([my_custom_tool]) - -# Use with AgentConfig -config = AgentConfig({ - "prompt": "You are a helpful assistant", - "tools": ["my_custom_tool"] -}, tool_registry=custom_tool_registry) -``` - -### File Configuration - -Configuration files must use the `file://` prefix: - -```python -from strands.experimental import AgentConfig -# Load from JSON file -config = AgentConfig("file:///path/to/config.json") -agent = config.to_agent() - #### Simple Agent Example ```json @@ -106,144 +53,130 @@ agent = config.to_agent() { "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0", "prompt": "You are a coding assistant. Help users write, debug, and improve their code. You have access to file operations and can execute shell commands when needed.", - "tools": ["shell", "file_read", "editor"] + "tools": ["strands_tools.file_read", "strands_tools.editor", "strands_tools.shell"] } ``` - ## Configuration Options ### Supported Keys - `model`: Model identifier (string) - see [model provider documentation](https://strandsagents.com/latest/user-guide/quickstart/#using-a-string-model-id) - `prompt`: System prompt for the agent (string) -- `tools`: List of tool names to select from the provided ToolRegistry (optional) +- `tools`: List of tool names, module paths, or file paths (list of strings) +- `name`: Agent name (string) +- `agent_id`: Agent identifier (string) +- `session_manager`: Session manager instance +- `conversation_manager`: Conversation manager instance +- `hooks`: List of hook providers +- `callback_handler`: Callback handler instance +- `state`: Initial agent state (dict) +- `trace_attributes`: Tracing attributes (dict) + +### Tool Loading + +The `tools` configuration supports the same formats as the Agent class: + +```json +{ + "tools": [ + "strands_tools.file_read", // Module path + "my_app.tools.cake_tool", // Custom module path + "/path/to/another_tool.py" // File path + ] +} +``` + +The Agent class handles all tool loading internally, including: +- Loading from module paths +- Loading from file paths +- Error handling for missing tools +- Tool validation -### Method Parameters +## Function Parameters -The `to_agent()` method accepts: +The `config_to_agent` function accepts: -- `tools`: Optional ToolRegistry instance to override the configured tools +- `config`: Either a file path (string) or configuration dictionary - `**kwargs`: Additional [Agent constructor parameters](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent.Agent.__init__) that override config values ```python # Override config values with valid Agent parameters -agent = config.to_agent( +agent = config_to_agent( + "/path/to/config.json", agent_id="my-agent-123", - name="Data Analyst", - description="Specialized data analysis agent" + name="Data Analyst" ) ``` -## Tool Selection - -When `tools` is specified in the configuration, AgentConfig validates and selects only those tools from the provided ToolRegistry: +## Error Handling +### File Not Found ```python -# Platform provider creates comprehensive ToolRegistry -platform_tool_registry = ToolRegistry() -platform_tool_registry.process_tools([calculator, web_search, file_ops, data_analysis]) - -# Customer selects specific tools -config = AgentConfig({ - "model": "anthropic.claude-3-5-sonnet-20241022-v2:0", - "prompt": "You are a research assistant", - "tools": ["calculator", "web_search"] # Only these will be available -}, tool_registry=platform_tool_registry) - -agent = config.to_agent() # Agent has only calculator and web_search -``` - -## File Path Requirements +from strands.experimental import config_to_agent -File paths must be prefixed with `file://` to maintain a standard interface: +try: + agent = config_to_agent("/nonexistent/config.json") +except FileNotFoundError as e: + print(f"Error: {e}") # Configuration file not found +``` +### Invalid JSON ```python -# ✅ Correct -config = AgentConfig("file:///absolute/path/to/config.json") - -# ❌ Incorrect - will raise ValueError -config = AgentConfig("/absolute/path/to/config.json") +try: + agent = config_to_agent("/path/to/invalid.json") +except json.JSONDecodeError as e: + print(f"Error: {e}") # Invalid JSON format ``` -## Error Handling - -### File Path Errors +### Invalid Configuration Type ```python -from strands.experimental import AgentConfig - try: - # This will raise ValueError - config = AgentConfig("/path/without/prefix.json") + agent = config_to_agent(123) # Invalid type except ValueError as e: - print(f"Error: {e}") # File paths must be prefixed with 'file://' + print(f"Error: {e}") # Config must be a file path string or dictionary ``` -### Tool Validation Errors -```python -from strands.experimental import AgentConfig -from strands.tools.registry import ToolRegistry +### Tool Loading Errors -# Tool not found in ToolRegistry (with raise_exception_on_missing_tool=True, default behavior) -try: - config = AgentConfig({ - "model": "test-model", - "tools": ["nonexistent_tool"] - }, tool_registry=ToolRegistry(), raise_exception_on_missing_tool=True) -except ValueError as e: - print(f"Error: {e}") # Tool(s) 'nonexistent_tool' not found in ToolRegistry +Tool loading errors are handled by the Agent class according to its standard behavior: -# Skip missing tools instead of raising errors -config = AgentConfig({ +```python +# If tools cannot be loaded, Agent will raise appropriate errors +agent = config_to_agent({ "model": "test-model", - "tools": ["existing_tool", "nonexistent_tool"] -}, tool_registry=my_tool_registry, raise_exception_on_missing_tool=False) -# Only existing_tool will be available, nonexistent_tool is silently skipped + "tools": ["nonexistent_tool"] +}) +# This will raise an error from the Agent class during tool loading ``` -### Missing Dependencies +## Best Practices + +1. **Use absolute paths**: Prefer absolute file paths for configuration files +2. **Handle errors gracefully**: Catch FileNotFoundError and JSONDecodeError for robust applications +3. **Override when needed**: Use kwargs to override configuration values dynamically +4. **Leverage Agent defaults**: Only specify configuration values you want to override +5. **Use standard tool formats**: Follow Agent class conventions for tool specifications + +## Migration from AgentConfig Class + +If you were using the previous `AgentConfig` class, here's how to migrate: + +### Before (AgentConfig class) ```python -# When strands_tools not installed and no ToolRegistry provided (with raise_exception_on_missing_tool=True) -try: - config = AgentConfig({"model": "test-model", "tools": ["file_read"]}, raise_exception_on_missing_tool=True) -except ImportError as e: - print(f"Error: {e}") - # strands_tools is not available and no ToolRegistry was specified. - # Either install strands_tools with 'pip install strands-agents-tools' - # or provide your own ToolRegistry with your own tools. - -# Skip missing tools when strands_tools not available -config = AgentConfig({"model": "test-model", "tools": ["file_read"]}, raise_exception_on_missing_tool=False) -# Will create agent without any tools since strands_tools is not available +from strands.experimental.agent_config import AgentConfig + +config = AgentConfig("/path/to/config.json") +agent = config.to_agent() ``` -### Tool Configuration Without ToolRegistry +### After (config_to_agent function) ```python -# Specifying tools without providing ToolRegistry (with raise_exception_on_missing_tool=True) -try: - config = AgentConfig({ - "model": "test-model", - "tools": ["calculator"] - }, raise_exception_on_missing_tool=True) # No tool_registry parameter -except ValueError as e: - print(f"Error: {e}") # Tool(s) not found in ToolRegistry +from strands.experimental import config_to_agent -# Skip missing tools when no ToolRegistry provided -config = AgentConfig({ - "model": "test-model", - "tools": ["calculator"] -}, raise_exception_on_missing_tool=False) # No tool_registry parameter -# Will attempt to use default ToolRegistry, skip unavailable tools +agent = config_to_agent("/path/to/config.json") ``` -## Best Practices - -1. **Use file:// prefix**: Always prefix file paths with `file://` -2. **Install strands_tools**: Use `pip install strands-agents-tools` for default tools -3. **Provide custom ToolRegistry**: Create your own ToolRegistry if not using strands_tools -4. **Validate tool selection**: Ensure tool names exist in your ToolRegistry before configuration -5. **Override when needed**: Use kwargs in `to_agent` to override Agent parameters values dynamically -6. **Handle errors gracefully**: Catch ImportError and ValueError for robust applications -7. **Control error behavior**: Use `raise_exception_on_missing_tool=False` to skip missing tools instead of failing +The new interface is simpler and delegates all complexity to the existing Agent class, providing a more consistent experience. -This experimental feature provides a foundation for more advanced agent configuration patterns while maintaining compatibility with the existing Agent API. +This experimental feature provides a foundation for more advanced agent configuration patterns while maintaining full compatibility with the existing Agent API. From 2accbc7f40a2bfc7614ba73492c12a6c0050f259 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Fri, 26 Sep 2025 18:38:54 -0400 Subject: [PATCH 43/45] docs: limit config_to_agent supported keys to core configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove advanced Agent parameters from supported configuration keys - Only document: model, prompt, tools, name as supported in config - Advanced parameters can still be passed via kwargs override - Update examples to reflect simplified configuration interface - Keep documentation focused on basic agent configuration use cases 🤖 Assisted by Amazon Q Developer --- docs/user-guide/concepts/experimental/agent-config.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index e6536eae..31bd9bf3 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -65,13 +65,6 @@ agent = config_to_agent("file:///path/to/config.json") - `prompt`: System prompt for the agent (string) - `tools`: List of tool names, module paths, or file paths (list of strings) - `name`: Agent name (string) -- `agent_id`: Agent identifier (string) -- `session_manager`: Session manager instance -- `conversation_manager`: Conversation manager instance -- `hooks`: List of hook providers -- `callback_handler`: Callback handler instance -- `state`: Initial agent state (dict) -- `trace_attributes`: Tracing attributes (dict) ### Tool Loading @@ -104,7 +97,6 @@ The `config_to_agent` function accepts: # Override config values with valid Agent parameters agent = config_to_agent( "/path/to/config.json", - agent_id="my-agent-123", name="Data Analyst" ) ``` From 119418121dc89e8a8c96ac3a70418ccc913393ba Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Fri, 26 Sep 2025 18:48:39 -0400 Subject: [PATCH 44/45] docs: add JSON schema validation documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document configuration validation with detailed error examples - Show validation error messages for invalid fields, types, and tool items - Explain how validation provides helpful error paths for debugging - Add examples of common validation errors users might encounter 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 31bd9bf3..3d1aee89 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -103,6 +103,32 @@ agent = config_to_agent( ## Error Handling +### Configuration Validation + +The `config_to_agent` function validates configuration against a JSON schema and provides detailed error messages: + +```python +from strands.experimental import config_to_agent + +# Invalid field +try: + agent = config_to_agent({"model": "test-model", "invalid_field": "value"}) +except ValueError as e: + print(f"Error: {e}") # Configuration validation error at root: Additional properties are not allowed ('invalid_field' was unexpected) + +# Wrong field type +try: + agent = config_to_agent({"model": "test-model", "tools": "not-a-list"}) +except ValueError as e: + print(f"Error: {e}") # Configuration validation error at tools: 'not-a-list' is not of type 'array' + +# Invalid tool item +try: + agent = config_to_agent({"model": "test-model", "tools": ["valid-tool", 123]}) +except ValueError as e: + print(f"Error: {e}") # Configuration validation error at tools -> 1: 123 is not of type 'string' +``` + ### File Not Found ```python from strands.experimental import config_to_agent From 13d371d9736b10bb910f6c870d5ec1fb94f3cc13 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Fri, 26 Sep 2025 20:39:18 -0400 Subject: [PATCH 45/45] docs: clarify tool limitations and add validation details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add prominent note about tool loading limitations for code-based instantiation - Document Python-specific tool support (files, modules, @tool functions) - Add example of programmatic tool addition after agent creation - Explain tool validation error messages with examples - Clarify that MCP server support will enable other language tools - Update tool loading examples to be more specific about Python requirements 🤖 Assisted by Amazon Q Developer --- .../concepts/experimental/agent-config.md | 44 +++++++++++++++++-- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/concepts/experimental/agent-config.md b/docs/user-guide/concepts/experimental/agent-config.md index 3d1aee89..200aa0bf 100644 --- a/docs/user-guide/concepts/experimental/agent-config.md +++ b/docs/user-guide/concepts/experimental/agent-config.md @@ -14,6 +14,18 @@ The experimental `config_to_agent` function provides a simple way to create agen - Support both file paths and dictionary configurations - Leverage the Agent class's built-in tool loading capabilities +!!! note "Tool Loading Limitations" + Configuration-based agent setup only works for tools that don't require code-based instantiation. For tools that need constructor arguments or complex setup, use the programmatic approach after creating the agent: + + ```python + import http.client + from sample_module import ToolWithConfigArg + + agent = config_to_agent("config.json") + # Add tools that need code-based instantiation + agent.process_tools([ToolWithConfigArg(http.client.HTTPSConnection("localhost"))]) + ``` + ## Basic Usage ### Dictionary Configuration @@ -63,23 +75,33 @@ agent = config_to_agent("file:///path/to/config.json") - `model`: Model identifier (string) - see [model provider documentation](https://strandsagents.com/latest/user-guide/quickstart/#using-a-string-model-id) - `prompt`: System prompt for the agent (string) -- `tools`: List of tool names, module paths, or file paths (list of strings) +- `tools`: List of tool specifications (list of strings) - `name`: Agent name (string) ### Tool Loading -The `tools` configuration supports the same formats as the Agent class: +The `tools` configuration supports Python-specific tool loading formats: ```json { "tools": [ - "strands_tools.file_read", // Module path + "strands_tools.file_read", // Python module path "my_app.tools.cake_tool", // Custom module path - "/path/to/another_tool.py" // File path + "/path/to/another_tool.py", // File path + "my_module.my_tool_function" // @tool annotated function ] } ``` +!!! important "Python Tool Support Only" + Currently, tool loading is Python-specific and supports: + + - **File paths**: Python files containing @tool annotated functions + - **Module names**: Python modules with @tool annotated functions + - **Function references**: Specific @tool annotated functions in modules + + Support for tools in other languages will be added when MCP server support is introduced to this feature. + The Agent class handles all tool loading internally, including: - Loading from module paths - Loading from file paths @@ -129,6 +151,20 @@ except ValueError as e: print(f"Error: {e}") # Configuration validation error at tools -> 1: 123 is not of type 'string' ``` +### Tool Validation Errors + +The function validates that tools can be loaded and provides helpful error messages: + +```python +# Tool not found +try: + agent = config_to_agent({"model": "test-model", "tools": ["nonexistent_tool"]}) +except ValueError as e: + print(f"Error: {e}") + # Tool 'nonexistent_tool' not found. The configured tool is not annotated with @tool, + # and is not a module or file. To properly import this tool, you must annotate it with @tool. +``` + ### File Not Found ```python from strands.experimental import config_to_agent