From 8630b2b7505805b9e3ec031cb7f5f8931e589acd Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Thu, 28 Aug 2025 10:51:35 -0400 Subject: [PATCH 1/4] tool executors --- docs/api-reference/tools.md | 10 +++++ docs/user-guide/concepts/tools/executors.md | 46 +++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 57 insertions(+) create mode 100644 docs/user-guide/concepts/tools/executors.md diff --git a/docs/api-reference/tools.md b/docs/api-reference/tools.md index 097d7dfa..2744782f 100644 --- a/docs/api-reference/tools.md +++ b/docs/api-reference/tools.md @@ -20,6 +20,16 @@ ::: strands.tools.watcher options: heading_level: 2 +::: strands.tools.executors + options: + heading_level: 2 + members: false +::: strands.tools.executors.concurrent + options: + heading_level: 3 +::: strands.tools.executors.sequential + options: + heading_level: 3 ::: strands.tools.mcp options: heading_level: 2 diff --git a/docs/user-guide/concepts/tools/executors.md b/docs/user-guide/concepts/tools/executors.md new file mode 100644 index 00000000..152139c3 --- /dev/null +++ b/docs/user-guide/concepts/tools/executors.md @@ -0,0 +1,46 @@ +# Tool Executors + +Tool executors allow users to customize the execution strategy of tools executed by the agent (e.g., concurrent vs sequential). Currently, Strands is packaged with 2 executors. + +## Concurrent Executor + +Use `ConcurrentToolExecutor` (the default) to execute tools concurrently: + +```python +from strands import Agent +from strands.tools.executors import ConcurrentToolExecutor + +agent = Agent( + tool_executor=ConcurrentToolExecutor(), + tools=[weather_tool, time_tool] +) +# or simply Agent(tools=[weather_tool, time_tool]) + +agent("What is the weather and time in New York?") +``` + +Assuming the model returns `weather_tool` and `time_tool` use requests, the `ConcurrentToolExecutor` will execute both concurrently. + +> Note: The model may decide to return one tool use request at a time. Under these circumstances, the tools will execute sequentially. Concurrency is only achieved if the model returns multiple tool use requests in a single response. + +## Sequential Executor + +Use `SequentialToolExecutor` to execute tools sequentially: + +```python +from strands import Agent +from strands.tools.executors import SequentialToolExecutor + +agent = Agent( + tool_executor=SequentialToolExecutor(), + tools=[screenshot_tool, email_tool] +) + +agent("Please take a screenshot and then email the screenshot to my friend") +``` + +Assuming the model returns `screenshot_tool` and `email_tool` use requests, the `SequentialToolExecutor` will execute both sequentially in the order given. + +## Custom Executor + +Custom tool executors are not currently supported but are planned for a future release. You can track progress on this feature at [GitHub Issue #762](https://github.com/strands-agents/sdk-python/issues/762). diff --git a/mkdocs.yml b/mkdocs.yml index 311de0d4..6ae5af57 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ nav: - Overview: user-guide/concepts/tools/tools_overview.md - Python: user-guide/concepts/tools/python-tools.md - Model Context Protocol (MCP): user-guide/concepts/tools/mcp-tools.md + - Executors: user-guide/concepts/tools/executors.md - Community Tools Package: user-guide/concepts/tools/community-tools-package.md - Model Providers: - Amazon Bedrock: user-guide/concepts/model-providers/amazon-bedrock.md From 8f2c406f557441858f271aed7721d7cab9732bae Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Thu, 28 Aug 2025 16:10:29 -0400 Subject: [PATCH 2/4] agent loop - remove reference to concurrent tool execution --- docs/user-guide/concepts/agents/agent-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/agents/agent-loop.md b/docs/user-guide/concepts/agents/agent-loop.md index 74a363fb..cced63f5 100644 --- a/docs/user-guide/concepts/agents/agent-loop.md +++ b/docs/user-guide/concepts/agents/agent-loop.md @@ -74,7 +74,7 @@ The agent loop includes a tool execution system that: 1. Validates tool requests from the model 2. Looks up tools in the registry -3. Executes tools concurrently with proper error handling +3. Executes tools with proper error handling 4. Captures and formats results 5. Feeds results back to the model From 75b5212feee9e9aff031823d445c0b92a97fb292 Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Fri, 29 Aug 2025 10:41:38 -0400 Subject: [PATCH 3/4] address feedback --- docs/user-guide/concepts/tools/executors.md | 4 +++- .../concepts/tools/tools_overview.md | 22 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/tools/executors.md b/docs/user-guide/concepts/tools/executors.md index 152139c3..8b4d3c13 100644 --- a/docs/user-guide/concepts/tools/executors.md +++ b/docs/user-guide/concepts/tools/executors.md @@ -21,7 +21,9 @@ agent("What is the weather and time in New York?") Assuming the model returns `weather_tool` and `time_tool` use requests, the `ConcurrentToolExecutor` will execute both concurrently. -> Note: The model may decide to return one tool use request at a time. Under these circumstances, the tools will execute sequentially. Concurrency is only achieved if the model returns multiple tool use requests in a single response. +### Sequential Behavior + +On certain prompts, the model may decide to return one tool use request at a time. Under these circumstances, the tools will execute sequentially. Concurrency is only achieved if the model returns multiple tool use requests in a single response. Certain models however offer additional abilities to coherce a desired behavior. For example, Anthropic exposes an explicit parallel tool use setting ([docs](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use#parallel-tool-use)). ## Sequential Executor diff --git a/docs/user-guide/concepts/tools/tools_overview.md b/docs/user-guide/concepts/tools/tools_overview.md index 08ae69ed..1b8c9815 100644 --- a/docs/user-guide/concepts/tools/tools_overview.md +++ b/docs/user-guide/concepts/tools/tools_overview.md @@ -90,6 +90,28 @@ If a tool name contains hyphens, you can invoke the tool using underscores inste result = agent.tool.read_all(path="/path/to/file.txt") ``` +## Tool Execution + +When models return multiple tool requests, you can control whether they execute concurrently or sequentially. Agents use concurrent execution by default, but you can specify sequential execution for cases where order matters: + +```python +from strands import Agent +from strands.tools.executors import SequentialToolExecutor + +# Concurrent execution (default) +agent = Agent(tools=[weather_tool, time_tool]) +agent("What is the weather and time in New York?") + +# Sequential execution +agent = Agent( + tool_executor=SequentialToolExecutor(), + tools=[screenshot_tool, email_tool] +) +agent("Take a screenshot and email it to my friend") +``` + +For more details, see [Tool Executors](executors.md). + ## Building & Loading Tools ### 1. Python Tools From 23a093c0f63c5f0ba0e4f1bde81c0bb96062aa57 Mon Sep 17 00:00:00 2001 From: Patrick Gray Date: Fri, 29 Aug 2025 10:44:14 -0400 Subject: [PATCH 4/4] section title - tool executors --- docs/user-guide/concepts/tools/tools_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/tools/tools_overview.md b/docs/user-guide/concepts/tools/tools_overview.md index 1b8c9815..d7986261 100644 --- a/docs/user-guide/concepts/tools/tools_overview.md +++ b/docs/user-guide/concepts/tools/tools_overview.md @@ -90,7 +90,7 @@ If a tool name contains hyphens, you can invoke the tool using underscores inste result = agent.tool.read_all(path="/path/to/file.txt") ``` -## Tool Execution +## Tool Executors When models return multiple tool requests, you can control whether they execute concurrently or sequentially. Agents use concurrent execution by default, but you can specify sequential execution for cases where order matters: