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/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 diff --git a/docs/user-guide/concepts/tools/executors.md b/docs/user-guide/concepts/tools/executors.md new file mode 100644 index 00000000..8b4d3c13 --- /dev/null +++ b/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). diff --git a/docs/user-guide/concepts/tools/tools_overview.md b/docs/user-guide/concepts/tools/tools_overview.md index 08ae69ed..d7986261 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 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 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