generated from amazon-archives/__template_Apache-2.0
-
Notifications
You must be signed in to change notification settings - Fork 105
Add comprehensive agent configuration documentation #252
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Unshure
merged 47 commits into
strands-agents:main
from
mr-lee:feature/agent-config-docs-clean
Oct 21, 2025
Merged
Changes from all commits
Commits
Show all changes
47 commits
Select commit
Hold shift + click to select a range
ddf8e81
Add agent configuration documentation and examples
mrlee-amazon 2e9242d
Fix model ID format in documentation to align with Strands expectations
mrlee-amazon 36a1d10
Fix tool names to match strands-agents/tools specifications
mrlee-amazon b7145e3
Update documentation to show correct tool usage
mrlee-amazon d5e96c1
feat: add experimental AgentConfig and ToolPool documentation
mrlee-amazon cda2f9e
refactor: update experimental docs per feedback
mrlee-amazon 2c05cbb
docs: update experimental AgentConfig with latest enhancements
mrlee-amazon 70fe2b1
docs: add examples using default tools from strands_tools
mrlee-amazon 69a6f81
docs: clarify ToolPool configuration requirement
mrlee-amazon 62bf316
fix: update coding-assistant.json with correct tools
mrlee-amazon d7f9a2c
docs: update experimental docs for ToolPool to ToolBox rename
mrlee-amazon 9b183cd
docs: fix method name from toAgent to to_agent
mrlee-amazon 723c6b0
docs: update experimental features to use ToolRegistry instead of Too…
mrlee-amazon d3b8c11
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee 3683f39
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee fc45286
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee 689e0a8
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee 9fbd54d
Apply suggestions from code review
mr-lee f816c95
docs: comprehensive improvements to experimental AgentConfig document…
mrlee-amazon f547ad7
docs: fix Using Default Tools example to use pirate agent without tools
mrlee-amazon f578da9
docs: add model provider documentation reference
mrlee-amazon d173d3d
docs: move agent config JSON examples inline
mrlee-amazon 947d318
docs: add GitHub links to default tools in AgentConfig
mrlee-amazon c7aaa1d
docs: fix invalid Agent parameters in AgentConfig examples
mrlee-amazon 9f8fa25
docs: update line 112 to use file_read and editor tools
mrlee-amazon f8e1c9d
docs: consolidate Default Tools Behavior into Using Default Tools sec…
mrlee-amazon 0bc149a
docs: fix inaccurate description of default tools behavior
mrlee-amazon 99300a8
docs: update agent example to use file_read tool
mrlee-amazon 4dee59e
docs: add back experimental caveat to tool list note
mrlee-amazon 6a0660e
docs: remove duplicate Selecting from Default Tools section
mrlee-amazon 2b1bdd8
docs: update error handling sections for raise_exception_on_missing_t…
mrlee-amazon 2eaf880
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee 2bf1e27
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee 3eec6d1
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee fe0cd25
Apply suggestion from @Unshure
mr-lee 9329e31
Apply suggestion from @Unshure
mr-lee 488733a
Apply suggestion from @Unshure
mr-lee af922ab
Apply suggestion from @Unshure
mr-lee 95f9fc4
Apply suggestion from @Unshure
mr-lee 492cf75
Apply suggestion from @Unshure
mr-lee 6184e24
docs: remove Example: Complete Workflow section
mrlee-amazon 98e8a3c
docs: update agent-config.md for new config_to_agent function
mrlee-amazon 20409e1
docs: limit config_to_agent supported keys to core configuration
mrlee-amazon 43bc11b
docs: add JSON schema validation documentation
mrlee-amazon 5bfcb66
docs: clarify tool limitations and add validation details
mrlee-amazon 0559bc7
update docs to match updated pr
Unshure aa226a4
Add model override docs
Unshure File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,163 @@ | ||
# Agent Configuration [Experimental] | ||
|
||
!!! warning "Experimental Feature" | ||
This feature is experimental and may change in future versions. Use with caution in production environments. | ||
|
||
The experimental `config_to_agent` function provides a simple way to create agents from configuration files or dictionaries. | ||
|
||
## Overview | ||
|
||
`config_to_agent` allows you to: | ||
|
||
- 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 config_to_agent | ||
|
||
# Create agent from dictionary | ||
agent = config_to_agent({ | ||
"model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0", | ||
"prompt": "You are a helpful assistant" | ||
}) | ||
``` | ||
|
||
### File Configuration | ||
|
||
```python | ||
from strands.experimental import config_to_agent | ||
|
||
# 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") | ||
``` | ||
|
||
#### Simple Agent Example | ||
|
||
```json | ||
{ | ||
"prompt": "You are a helpful assistant." | ||
} | ||
``` | ||
|
||
#### Coding Assistant Example | ||
|
||
```json | ||
{ | ||
"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": ["strands_tools.file_read", "strands_tools.editor", "strands_tools.shell"] | ||
} | ||
``` | ||
|
||
## Configuration Options | ||
|
||
### Supported Keys | ||
|
||
- `model`: Model identifier (string) - [[Only supports AWS Bedrock model provider string](../../../quickstart/#using-a-string-model-id)] | ||
- `prompt`: System prompt for the agent (string) | ||
- `tools`: List of tool specifications (list of strings) | ||
- `name`: Agent name (string) | ||
|
||
### Tool Loading | ||
|
||
The `tools` configuration supports Python-specific tool loading formats: | ||
|
||
```json | ||
{ | ||
"tools": [ | ||
"strands_tools.file_read", // Python module path | ||
"my_app.tools.cake_tool", // Custom module path | ||
"/path/to/another_tool.py", // File path | ||
"my_module.my_tool_function" // @tool annotated function | ||
] | ||
} | ||
``` | ||
|
||
The Agent class handles all tool loading internally, including: | ||
|
||
- Loading from module paths | ||
- Loading from file paths | ||
- Error handling for missing tools | ||
- Tool validation | ||
|
||
!!! 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"))]) | ||
``` | ||
|
||
### Model Configurations | ||
|
||
The `model` property uses the [string based model id feature](../../../quickstart/#using-a-string-model-id). You can reference [AWS's Model Id's](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) to identify a model id to use. If you want to use a different model provider, you can pass in a model as part of the `**kwargs` of the `config_to_agent` function: | ||
|
||
```python | ||
from strands.experimental import config_to_agent | ||
from strands.models.openai import OpenAIModel | ||
|
||
# Create agent from dictionary | ||
agent = config_to_agent( | ||
config={"name": "Data Analyst"}, | ||
model=OpenAIModel( | ||
client_args={ | ||
"api_key": "<KEY>", | ||
}, | ||
model_id="gpt-4o", | ||
) | ||
) | ||
``` | ||
|
||
Additionally, you can override the `agent.model` attribute of an agent to configure a new model provider: | ||
|
||
```python | ||
from strands.experimental import config_to_agent | ||
from strands.models.openai import OpenAIModel | ||
|
||
# Create agent from dictionary | ||
agent = config_to_agent( | ||
config={"name": "Data Analyst"} | ||
) | ||
|
||
agent.model = OpenAIModel( | ||
client_args={ | ||
"api_key": "<KEY>", | ||
}, | ||
model_id="gpt-4o", | ||
) | ||
``` | ||
|
||
## Function Parameters | ||
|
||
The `config_to_agent` function accepts: | ||
|
||
- `config`: Either a file path (string) or configuration dictionary | ||
- `**kwargs`: Additional [Agent constructor parameters](../../../../api-reference/agent/#strands.agent.agent.Agent.__init__) that override config values | ||
|
||
```python | ||
# Override config values with valid Agent parameters | ||
agent = config_to_agent( | ||
"/path/to/config.json", | ||
name="Data Analyst" | ||
) | ||
``` | ||
|
||
## Best Practices | ||
|
||
1. **Override when needed**: Use kwargs to override configuration values dynamically | ||
2. **Leverage Agent defaults**: Only specify configuration values you want to override | ||
3. **Use standard tool formats**: Follow Agent class conventions for tool specifications | ||
4. **Handle errors gracefully**: Catch FileNotFoundError and JSONDecodeError for robust applications | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.