Skip to content
Merged
Show file tree
Hide file tree
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 Sep 12, 2025
2e9242d
Fix model ID format in documentation to align with Strands expectations
mrlee-amazon Sep 12, 2025
36a1d10
Fix tool names to match strands-agents/tools specifications
mrlee-amazon Sep 12, 2025
b7145e3
Update documentation to show correct tool usage
mrlee-amazon Sep 12, 2025
d5e96c1
feat: add experimental AgentConfig and ToolPool documentation
mrlee-amazon Sep 23, 2025
cda2f9e
refactor: update experimental docs per feedback
mrlee-amazon Sep 23, 2025
2c05cbb
docs: update experimental AgentConfig with latest enhancements
mrlee-amazon Sep 24, 2025
70fe2b1
docs: add examples using default tools from strands_tools
mrlee-amazon Sep 24, 2025
69a6f81
docs: clarify ToolPool configuration requirement
mrlee-amazon Sep 24, 2025
62bf316
fix: update coding-assistant.json with correct tools
mrlee-amazon Sep 24, 2025
d7f9a2c
docs: update experimental docs for ToolPool to ToolBox rename
mrlee-amazon Sep 24, 2025
9b183cd
docs: fix method name from toAgent to to_agent
mrlee-amazon Sep 24, 2025
723c6b0
docs: update experimental features to use ToolRegistry instead of Too…
mrlee-amazon Sep 25, 2025
d3b8c11
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 25, 2025
3683f39
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 25, 2025
fc45286
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 25, 2025
689e0a8
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 25, 2025
9fbd54d
Apply suggestions from code review
mr-lee Sep 25, 2025
f816c95
docs: comprehensive improvements to experimental AgentConfig document…
mrlee-amazon Sep 25, 2025
f547ad7
docs: fix Using Default Tools example to use pirate agent without tools
mrlee-amazon Sep 25, 2025
f578da9
docs: add model provider documentation reference
mrlee-amazon Sep 25, 2025
d173d3d
docs: move agent config JSON examples inline
mrlee-amazon Sep 25, 2025
947d318
docs: add GitHub links to default tools in AgentConfig
mrlee-amazon Sep 25, 2025
c7aaa1d
docs: fix invalid Agent parameters in AgentConfig examples
mrlee-amazon Sep 25, 2025
9f8fa25
docs: update line 112 to use file_read and editor tools
mrlee-amazon Sep 25, 2025
f8e1c9d
docs: consolidate Default Tools Behavior into Using Default Tools sec…
mrlee-amazon Sep 25, 2025
0bc149a
docs: fix inaccurate description of default tools behavior
mrlee-amazon Sep 25, 2025
99300a8
docs: update agent example to use file_read tool
mrlee-amazon Sep 25, 2025
4dee59e
docs: add back experimental caveat to tool list note
mrlee-amazon Sep 25, 2025
6a0660e
docs: remove duplicate Selecting from Default Tools section
mrlee-amazon Sep 25, 2025
2b1bdd8
docs: update error handling sections for raise_exception_on_missing_t…
mrlee-amazon Sep 25, 2025
2eaf880
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 26, 2025
2bf1e27
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 26, 2025
3eec6d1
Update docs/user-guide/concepts/experimental/agent-config.md
mr-lee Sep 26, 2025
fe0cd25
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
9329e31
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
488733a
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
af922ab
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
95f9fc4
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
492cf75
Apply suggestion from @Unshure
mr-lee Sep 26, 2025
6184e24
docs: remove Example: Complete Workflow section
mrlee-amazon Sep 26, 2025
98e8a3c
docs: update agent-config.md for new config_to_agent function
mrlee-amazon Sep 26, 2025
20409e1
docs: limit config_to_agent supported keys to core configuration
mrlee-amazon Sep 26, 2025
43bc11b
docs: add JSON schema validation documentation
mrlee-amazon Sep 26, 2025
5bfcb66
docs: clarify tool limitations and add validation details
mrlee-amazon Sep 27, 2025
0559bc7
update docs to match updated pr
Unshure Oct 19, 2025
aa226a4
Add model override docs
Unshure Oct 21, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions docs/user-guide/concepts/experimental/agent-config.md
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

2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,8 @@ 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:
- AgentConfig: user-guide/concepts/experimental/agent-config.md
- Safety & Security:
- Responsible AI: user-guide/safety-security/responsible-ai.md
- Guardrails: user-guide/safety-security/guardrails.md
Expand Down