Add comprehensive agent configuration documentation #252

mr-lee · 2025-09-15T15:24:59Z

Description

Document JSON and Python dict configuration options
Show correct tool specification using strands_tools package names
Add examples for model, prompt, and tools configuration
Update coding assistant example with proper tool names
Maintain backward compatibility examples

Type of Change

New content addition

Motivation and Context

This is a partner PR to the addition of supporting "Agent Config" to enable a subset of the Strands agent to be generated off of config.

Areas Affected

Agents

Screenshots

N/A

Checklist

I have read the CONTRIBUTING document
My changes follow the project's documentation style
I have tested the documentation locally using mkdocs serve
Links in the documentation are valid and working
Images/diagrams are properly sized and formatted
All new and existing tests pass

Additional Notes

Will link related PR once published.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- Update all references to use correct Python method name to_agent() - Maintain consistency with actual implementation 🤖 Assisted by Amazon Q Developer

…lBox - 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

docs/user-guide/concepts/experimental/agent-config.md

docs/user-guide/concepts/experimental/index.md

docs/user-guide/concepts/experimental/agent-config.md

docs/examples/agent-configs/simple-agent.json

Unshure · 2025-09-25T18:27:03Z

docs/examples/agent-configs/coding-assistant.json

@@ -0,0 +1,5 @@
+{
+  "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",


lets not include model in these configs becuase we needed to add some custom logic to help ease the pain of inference configs: https://github.com/strands-agents/sdk-python/blob/main/src/strands/models/bedrock.py#L33-L36

are you sure? The configs don't work otherwise...

They would work, it would just use the default model set by the agent: https://github.com/strands-agents/sdk-python/blob/main/src/strands/models/bedrock.py#L34

Co-authored-by: Nick Clegg <nac542@gmail.com>

…ation - 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

- 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

- Add link to model provider docs for model identifier usage - Reference quickstart guide for string model ID usage 🤖 Assisted by Amazon Q Developer

- 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

- 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

- 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

- Replace say and current_time with file_read and editor tools - Use consistent tool examples throughout documentation 🤖 Assisted by Amazon Q Developer

…tion - 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

- 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

- 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

- Restore warning that tool list is experimental and will be revisited - Keep both user-friendly description and experimental warning 🤖 Assisted by Amazon Q Developer

- Delete redundant section that was duplicated in the documentation - Keep content organized and avoid repetition 🤖 Assisted by Amazon Q Developer

…ool parameter - 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

docs/user-guide/concepts/experimental/agent-config.md

Co-authored-by: Nick Clegg <nac542@gmail.com>

- Remove lengthy example section to simplify documentation - Keep concise closing statement about experimental feature 🤖 Assisted by Amazon Q Developer

- 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

- 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

- 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

@tool

- 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

mr-lee mentioned this pull request Sep 15, 2025

Add agent configuration support with JSON/dict configs and tool name resolution strands-agents/sdk-python#865

Closed

7 tasks

mr-lee force-pushed the feature/agent-config-docs-clean branch from f7692ee to df2dbee Compare September 23, 2025 23:26

mrlee-amazon added 12 commits September 24, 2025 18:11

Fix tool names to match strands-agents/tools specifications

e47979b

- 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

Update documentation to show correct tool usage

399fce3

- 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

docs: clarify ToolPool configuration requirement

06b63d4

- 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

fix: update coding-assistant.json with correct tools

ebe5b7b

- 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: fix method name from toAgent to to_agent

ce0ab29

- Update all references to use correct Python method name to_agent() - Maintain consistency with actual implementation 🤖 Assisted by Amazon Q Developer

mr-lee force-pushed the feature/agent-config-docs-clean branch from aacd5aa to ce0ab29 Compare September 24, 2025 22:11

Unshure requested changes Sep 25, 2025

View reviewed changes

mr-lee and others added 13 commits September 25, 2025 16:27

Update docs/user-guide/concepts/experimental/agent-config.md

8b41270

Co-authored-by: Nick Clegg <nac542@gmail.com>

Update docs/user-guide/concepts/experimental/agent-config.md

ac52d8f

Co-authored-by: Nick Clegg <nac542@gmail.com>

Update docs/user-guide/concepts/experimental/agent-config.md

ea559b5

Co-authored-by: Nick Clegg <nac542@gmail.com>

Update docs/user-guide/concepts/experimental/agent-config.md

347e315

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestions from code review

a265a8e

Co-authored-by: Nick Clegg <nac542@gmail.com>

docs: fix Using Default Tools example to use pirate agent without tools

9fe8fd2

- 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: add model provider documentation reference

1e3bfda

- Add link to model provider docs for model identifier usage - Reference quickstart guide for string model ID usage 🤖 Assisted by Amazon Q Developer

docs: move agent config JSON examples inline

29214b9

- 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

docs: add GitHub links to default tools in AgentConfig

4ec30f8

- 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: fix invalid Agent parameters in AgentConfig examples

830ef23

- 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

docs: update line 112 to use file_read and editor tools

9e58026

- Replace say and current_time with file_read and editor tools - Use consistent tool examples throughout documentation 🤖 Assisted by Amazon Q Developer

mrlee-amazon added 5 commits September 25, 2025 18:59

docs: fix inaccurate description of default tools behavior

f075561

- 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: update agent example to use file_read tool

a963075

- 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: add back experimental caveat to tool list note

4a6e953

- 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: remove duplicate Selecting from Default Tools section

5b6e878

- Delete redundant section that was duplicated in the documentation - Keep content organized and avoid repetition 🤖 Assisted by Amazon Q Developer

Unshure reviewed Sep 26, 2025

View reviewed changes

docs/user-guide/concepts/experimental/agent-config.md Show resolved Hide resolved

docs/user-guide/concepts/experimental/agent-config.md Outdated Show resolved Hide resolved

Unshure requested changes Sep 26, 2025

View reviewed changes

mr-lee mentioned this pull request Sep 26, 2025

Add agent configuration support with JSON/dict configs and tool name resolution v2 strands-agents/sdk-python#934

Closed

7 tasks

mr-lee and others added 10 commits September 26, 2025 15:59

Update docs/user-guide/concepts/experimental/agent-config.md

26e2fc8

Co-authored-by: Nick Clegg <nac542@gmail.com>

Update docs/user-guide/concepts/experimental/agent-config.md

d3e0074

Co-authored-by: Nick Clegg <nac542@gmail.com>

Update docs/user-guide/concepts/experimental/agent-config.md

c0a791f

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

857a64b

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

a16c847

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

79f488c

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

c5e121a

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

4850867

Co-authored-by: Nick Clegg <nac542@gmail.com>

Apply suggestion from @Unshure

915b0c0

Co-authored-by: Nick Clegg <nac542@gmail.com>

docs: remove Example: Complete Workflow section

89343e7

- Remove lengthy example section to simplify documentation - Keep concise closing statement about experimental feature 🤖 Assisted by Amazon Q Developer

mr-lee mentioned this pull request Sep 26, 2025

feat: add experimental AgentConfig with comprehensive tool management strands-agents/sdk-python#935

Open

7 tasks

mrlee-amazon added 4 commits September 26, 2025 18:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add comprehensive agent configuration documentation #252

Add comprehensive agent configuration documentation #252

Uh oh!

mr-lee commented Sep 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Unshure Sep 25, 2025

Uh oh!

mr-lee Sep 25, 2025

Uh oh!

Unshure Sep 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

		@@ -0,0 +1,5 @@
		{
		"model": "anthropic.claude-3-5-sonnet-20241022-v2:0",

Add comprehensive agent configuration documentation #252

Are you sure you want to change the base?

Add comprehensive agent configuration documentation #252

Uh oh!

Conversation

mr-lee commented Sep 15, 2025

Description

Type of Change

Motivation and Context

Areas Affected

Screenshots

Checklist

Additional Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Unshure Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

mr-lee Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Unshure Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!