tool executors

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

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
 

docs/user-guide/concepts/tools/executors.md

@@ -0,0 +1,48 @@
+# 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.
+
+### 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
+
+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).

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 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:
+
+```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

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